Defining Global Custom Detection Rules

Security for Bitbucket allows for creation of custom scanning rules using regular expressions. The rules can only be created, enabled, or disabled by Bitbucket Administrators or anyone that's been granted explicit access.

Please make sure the rules you add aren’t too broad, as they can impact the performance of Bitbucket.

To create a rule, access the settings page. The custom rules area appears near the bottom as shown:

If a secret on a single line matches more than one rule (built-in, custom, or a per-repository rule), only the first match will be reported.

Developing custom rules

Our application uses the built-in JDK java regex library (Java 8). The supported regex constructs are documented here.

The tool we recommend for testing out new custom rules is https://regex101.com.

Make sure to select “Java 8” as the “Flavor”:

Warn-only custom rules

When you have configured the Security Hook to scan every push and block when there are findings, you can optionally configure some custom rules to not block pushes, but to warn only. This can be useful if, for example, you want to be notified of the presence of certain sensitive but non-critical information, but accept the risk of dissemination. Below, two custom rules identify Bitcoin Addresses, which we do not want disseminated, and Youtube Links, which we consider sensitive but low-risk upon dissemination:

Settings Page, Custom Rules Dropdown, Blocking and Warn-Only Selectors Highlighted

In the example above, the “Bitcoin Address” rule is configured to be blocking, and “Youtube Links” are configured to be warn-only. This leads to the following behavior when a commit that contains these findings is pushed:

If the commit contains a Bitcoin Address (blocking), the entire push is blocked with a message highlighting the finding.
If the commit contains a Youtube Link (warn-only) and no Bitcoin Address or other finding, the push is allowed with a warning message highlighting the YouTube Link.
If the commit contains both a Bitcoin Address and a Youtube Link, the push is blocked with a message highlighting both findings.

Example custom rules

Bitcoin Address

NONE

^[13][a-km-zA-HJ-NP-Z0-9]{26,33}$

Youtube Links

CODE

<a\s+(?:[^>]*)href=\"((?:https|http):\/\/\w{0,3}.youtube+\.\w{2,3}\/watch\?v=[\w-]{11})">(?:.*?)<\/a>