Defining Repository-Level Detection Rules

Some repositories may have specific requirements for vulnerability detection, which differs from the rules defined globally.

To address repository-specific needs you can use per-repository rules. They are committed to individual repositories and affects only the repository where they are committed. This feature is disabled by default. The global settings page has a toggle to enable custom repository rules support:

The per-repository rules configuration toggle on Security For Bitbucket's global settings page. — The per-repository rules toggle on Security For Bitbucket’s global settings page

When this option is enabled, Security for Bitbucket looks for a file named soteri-security.yml at the root of the repository. You will need to create and commit this file yourself if the repository has no soteri-security.yml yet.

Here are the current options that are supported:

Option key	Description
`inherit_builtin_rules` (default true)	Set this to false to NOT inherit built-in rules. If true, file contents are checked against built-in rules
`inherit_custom_rules` (default true)	Set this to false to NOT inherit globally defined custom rules. If true, file contents are checked against globally defined custom rules.
`rules`	Use this field to apply a certain set of built-in rules. You can use this in conjunction with `inherit_builtin_rule: false` to define a specific set of rules to check against, or to re-enable a globally disabled rule. Rule names can be referenced from the settings page, or Vulnerabilities Detected by Security for Bitbucket.
`custom_rules`	Use this field to define and apply your own custom rules. Rules are defined as key value pairs`{rule_name}: {rule_regexp}` with the same formatting as the custom rules page. Note, that if you re-define a rule with the same name as one of custom rules, it will override the global custom rule.
`allowlist_paths`	Use this list to mark specific files or paths (using a regular expression as the value) as allowed even if they contain vulnerabilities. This can be useful for storing some non-sensitive credentials and configuration data. See more details on allow-listing here: Allow-listing Detected Secrets

Below is an example of a soteri-security.yml config:

YAML

inherit_builtin_rules: false
inherit_custom_rules: false
rules:
   - RSA_PRIVATE_KEY
   - SSH_PRIVATE_KEY
custom_rules:
  # Comments are supported.
  BITCOIN_ADDRESS: '^[13][a-km-zA-HJ-NP-Z0-9]{26,33}$'
  YOUTUBE_LINKS: '<a\s+(?:[^>]*)href=\"((?:https|http):\/\/\w{0,3}.youtube+\.\w{2,3}\/watch\?v=[\w-]{11})">(?:.*?)<\/a>'
allowlist_paths:
  - config/server.yml
  - (.*)\.insecure

Rules configured in this file are used both when repository content is updated (if security validation hook is enabled) and when you trigger scan manually from Security Scan tab of the repository.