Defining Repository-Level Detection Rules

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

To address repository-specific needs, you can use a per-repository configuration file. This file is committed to an individual repository and affects only the repository where it is committed. When this option is enabled, Security for Bitbucket looks for a file named soteri-security.yml in the root directory of the repository. You will need to create and commit this file yourself if the repository has no soteri-security.yml yet.

Rules and options configured in this file are used both when repository content is updated (if Soteri - Scan Commits hook is enabled) and when you trigger scans manually from the Soteri Security Scan tab of the repository.

As of version 3.10.0, this file is always loaded from the latest commit of the default branch. This ensures that scans of even historical branches are conducted with the most up-to-date configuration.

Per-repository configuration is disabled by default. The global settings page has a toggle to enable custom repository rules support:

localhost_7990_bitbucket_plugins_servlet_security-for-bitbucket-settings (5) copy.png

Supported Configuration

This table documents all supported soteri-security.yml configuration options.

Option key	Type	Description
`inherit_builtin_rules` (default true)	Boolean	Set this to false to NOT inherit built-in rules. If true, file contents are checked against globally enabled built-in rules.
`inherit_custom_rules` (default true)	Boolean	Set this to false to NOT inherit globally defined custom rules. If true, file contents are checked against globally defined and enabled custom rules.
`rules`	List of Strings	Use this field to apply a specific set of built-in rules that will always apply, regardless of `inherit_builtin_rules`. Use in conjunction with `inherit_builtin_rules: false` to define a specific set of built-in rules to check against. Alternately, if `inherit_builtin_rules` is true, use this field to re-enable one or more globally disabled built-in rules. Rule names can be referenced from the settings page, or Built-In Scanning Rules.
`custom_rules`	List of 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.
`allowlist_paths`	Regular Expression	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. Consider using https://regex101.com/ to test your regexes.
`skip_file_paths`	List of Strings	Use this list to mark specific files as not to be scanned. This is useful for excluding files known to contain binary data, minified files, or other places where secrets will not be found. Any time a scan skips files in this manner, an audit log event will be generated.
`skip_file_patterns`	List of Regular Expressions	Use this list to match file paths which should not be scanned. This has the same effect as `skip_file_paths`, but matches against a pattern rather than an exact path. Any time a scan skips files in this manner, an audit log event will be generated.

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"
skip_file_paths:
  # Skip a generated file committed to the repository.
  - dist/main.js.chunk
  # Skip scanning a tool that may evade detection as a binary wrapped in a shell script.
  - tools/shell-binary-installer.sh
skip_file_patterns:
  # Skip scanning a vendored `node_modules` directory.
  - "^node_modules/(.*)$"

Pre-Receive Hook

When Security for Bitbucket is installed and enabled, any changes which might invalidate soteri-security.yml on the default branch will be blocked by an included pre-receive hook. Changes which can be rejected must both:

Target a repository’s default branch. This includes:
- Direct pushes to the default branch.
- The merging of pull requests which target the default branch.
Modify soteri-security.yml such that it is no longer valid. Examples of potential reasons why soteri-security.yml could be invalid:
- Doesn’t parse as a valid YAML. You can use online tools to check that your YAML is valid before committing, like this one.
  - Note that the YAML standard forbids tab characters. You must use spaces in soteri-security.yml.
- Properties don’t parse as expected (e.g., inherit_builtin_rules must be parsable as a boolean).
- Provided regular expressions are invalid (e.g., for allowlist_paths or any defined custom_rules). You can use online tools to validate that your regexes are valid before committing, like this one.
- Rule names that don’t have regular expressions associated with them.