Scan Performance Tuning

By default, Security for Bitbucket distributes scanning to every Bitbucket Data Center node, and runs 2 scans in parallel per node. Server installations are treated as single-node Data Center installations.

Scans beyond the number of scans run in parallel are stored in a queue. This queue is accessible to all Bitbucket nodes. You can turn on debug logging to see detailed information about the scans being run on each node.

Scheduling periodic scans

You can schedule full-instance scans to take place periodically, such as once every week.

To configure periodic scanning, click the value next to Scheduled Scans.

A dialog box showing a text field for entering a Quartz Cron Expression will be shown. Additionally, some clickable examples are shown which will fill in the cron expression for you.

Enter your desired expression, or click on a built-in expression to get started, then hit Apply. Note that schedules are evaluated in terms of UTC, not local or server time - but will be interpreted for you in your browser’s local time. For example:

0 0 12 ? * 6

Which means “at second 0, minute 0, hour 12, any day of the month, every month, the sixth day of the week” will be displayed as:

At 07:00 AM, only on Saturday (America/New_York).

This is because 12:00 PM UTC is 7:00 AM EST at the time of interpretation.

If you would like to turn off periodic scanning, hit Clear instead. Never indicates that periodic scheduled scanning is off.

Audit events are created when the schedule is updated and when the scheduled scan runs.

Viewing and changing parallel scans

To speed up scanning, you can change the number of parallel threads used by Security for Bitbucket during scans via the Security for Bitbucket Settings page. Select the desired number of parallel scans per node in the corresponding dropdown box:

By default, your current setting should be automatically selected.

For example, if you choose “4”, this will change the number of scan threads on every Bitbucket node to 4.

To maximize scanning performance, choose "Maximum" to use all available CPUs on each node, but be advised that this can affect overall Bitbucket performance dramatically.

This setting is stored and persists upon plugin update and Bitbucket restarts.

Troubleshooting number of available processors

In certain situations, the number of processors detected by Security for Bitbucket might not match the number of processors actually available to the server. If you are running in a Docker deployment and believe you should have more processing power available, you should update your JVM flags as discussed in https://www.databasesandlife.com/java-docker-aws-ecs-multicore/.

Changing parallel scans programmatically

You may change the number of parallel scans with the following API call:

curl -u admin -X PUT https://{bitbucket.server}/rest/security/latest/status/active/{size}

where

• admin is your Bitbucket admin user (you’ll be prompted for a password),

• bitbucket.server is the URL of your Bitbucket server, and

• size is the number of parallel scan threads used per Bitbucket node.

For instance, setting size to 4 will change the number of scan threads on every Bitbucket node to 4. As a performance consideration, the requested number of threads is clamped to the available number of CPUs. To maximize scanning performance, you can specify the value 0 to use all available CPUs, but be advised that this can affect overall Bitbucket performance dramatically.

Security for Bitbucket does not currently support configuring a different number of parallel threads on different Bitbucket nodes.

To obtain the number of parallel scans, perform the following API call:

curl -u admin -X GET https://{bitbucket.server}/rest/security/latest/cluster/worker-pool/size

where

• admin is your Bitbucket admin user (you’ll be prompted for a password), and

• bitbucket.server is the URL of your Bitbucket server.

This call returns a positive integer which is the configured number of parallel scans. Note that if this setting was set to 0 (to set number of threads to the number of available CPUs), the returned number will be the actual number of available CPUs, not 0.

Changing the maximum scannable file size

One option to improve performance is to automatically skip scanning for files greater than a certain file size. Many times, source code repositories are used to store large data files in addition to source code files - generally, these data files are unlikely to contain secrets and can be safely skipped.

Adjust this setting under the “Scan Performance” heading:

Clicking on the value will open a dialog that allows you to adjust the maximum file size. The field allows entering an arbitrary byte value which is interpreted to readable units below the field:

For no limit, enter 0:

Changing the maximum scannable line length

While changing the maximum scannable file size can eliminate a great deal of files for which scanning would be pointless, sometimes non-binary files contain lines far too long to reasonably contain scannable material. Minified Javascript, for example, may have lines that run on for kilobytes, but ultimately result in a file that may only be 2 MiB large.

In this case, you can also tune the maximum scannable line length, beyond which the line will not be scanned, and an entry will be created in the audit logs for them.

Adjust this setting under the “Scan Performance” heading:

Clicking on the value will open a dialog that allows you to adjust the maximum line length. The field allows entering an arbitrary byte value which is interpreted to readable units below the field:

Only bytes are counted, not character width (columns). This makes a difference if your source code files are in a character encoding that exceeds 1 byte per character - for example, if your source code or data files contain certain non-English diacritics, non-Latin characters, emoji characters, and other UTF-8 features.

For no limit, enter 0:

Modifying which Bitbucket nodes run scans

If you have multiple Bitbucket Data Center nodes running, you can choose which ones run scans. This feature current is only supported via the REST API.

Name the nodes that should participate in scanning

Note that Bitbucket Data Center will not prevent you from naming nodes identically. If two nodes are named identically, and Security for Bitbucket is configured such that scans should run on that node name, then scans will run on both nodes.

Use Bitbucket’s concept of naming cluster nodes to name the nodes you wish to participate in scanning. See the Atlassian’s documentation on Adding and removing Data Center nodes (Item 3 under “Adding a node”).

See and change which nodes are running scans

To see which nodes are participating in scanning:

curl -u admin -X GET https://{bitbucket.server}/rest/security/latest/cluster/scan-nodes

where

• admin is your Bitbucket admin user (you’ll be prompted for a password), and

• bitbucket.server is the URL of your Bitbucket server.

This will return a JSON formatted response which looks like this:

{
  "scanNodeNames": [],
  "message": "Scan node configuration is empty. All nodes will participate in scanning"
}

To change which nodes run scans, for instance:

curl -u admin -X PUT https://{bitbucket.server}/rest/security/latest/cluster/scan-nodes -H "Content-Type: application/json" -d '{"scanNodeNames": [{scanNodeNames}]}'

where

• admin is your Bitbucket admin user (you’ll be prompted for a password),

• bitbucket.server is the URL of your Bitbucket server, and

• scanNodeNames is a list of the node names you want to participate in scanning; e.g., "bitbucket-scan-node1", "bitbucket-scan-node2".

To reset back to the default behavior, where all nodes participate in scanning, send a DELETE to the same endpoint:

curl -u admin -X DELETE https://{bitbucket.server}/rest/security/latest/cluster/scan-nodes

or, you can make scanNodeNames empty:

curl -u admin -X PUT https://{bitbucket.server}/rest/security/latest/cluster/scan-nodes -H "Content-Type: application/json" -d '{"scanNodeNames": []}'

Both have the same effect.

Verifying distributed scanning

To verify that Security for Bitbucket was successful in setting up a distributed scan queue in your Bitbucket installation, perform the following API call:

curl -u admin -X GET https://{bitbucket.sever}/rest/security/latest/status/cluster/distributed-scanning-enabled

This call will either return true if Security for Bitbucket was able to set up distributed scanning, or false if something went wrong. If distributed scanning isn’t working in your Bitbucket setup, please contact our support team.