Security for Bitbucket contains a pre-receive hook, which can run a scan on any code before it is pushed into Bitbucket. The Security Hook has two modes:

  • Default: Reject the push if any vulnerabilities are found

  • Warn-only: Print a message to the pusher notifying them of the scan failures, but allow the push to succeed.

Bypassing the hook

Sometimes the synchronous scanning of pushes is not feasible due to the size or complexity of the commits pushed. In those cases, developers can include the string **skip-soteri-security-check** in the commit message of the commit which should not be scanned.

If a scan is subsequently triggered via the Repository Scan Report page or the Global Scan Dashboard, the contents of the commit will be scanned. The bypass directive applies to the pre-receive hook only.

When the pre-receive hook is enabled and a commit is bypassed, a warning message is displayed to the pusher:

Inheritance Model

Personal repositories (those with ~username in the path) do not support inheritance, since they don’t belong to a project.

The security hook can be enabled on the repository level, on the project level, or globally. When the repository-level hook is configured as “Inherited”, it inherits settings either from the project level or from the global configuration. The following table outlines whether or not the hook runs in each of these cases:

Repository Hook Toggle

Project Hook Toggle

Global Hook Toggle

Resulting Behavior

ENABLED

ENABLED

ENABLED

Hook ON

ENABLED

ENABLED

DISABLED

Hook ON

ENABLED

DISABLED

ENABLED

Hook ON

ENABLED

DISABLED

DISABLED

Hook ON

INHERITED

ENABLED

ENABLED

Hook ON (inherited from project)

INHERITED

ENABLED

DISABLED

Hook ON (inherited from project)

INHERITED

DISABLED

ENABLED

Hook ON (inherited from global)

INHERITED

DISABLED

DISABLED

Hook OFF

DISABLED

ENABLED

ENABLED

Hook OFF

DISABLED

ENABLED

DISABLED

Hook OFF

DISABLED

DISABLED

ENABLED

Hook OFF

DISABLED

DISABLED

DISABLED

Hook OFF

Enabling the hook on the repository level

To enable the hook on a repository level, go to the desired repository, Settings → Hooks, and then enable the Reject Vulnerable Commits hook. A pop-up will prompt you with the option whether to configure the hook in reject or warn-only mode.

Enabling the hook on the project level

To enable the hook on a project level (which is great for blocking vulnerabilities for new repositories), go to the desired project, Settings → Hooks, and then enable the Reject Vulnerable Commits hook. A pop-up will prompt you with the option whether to configure the hook in reject or warn-only mode.

Enabling the hook globally

To enable the hook on a global scale, have your Bitbucket administrator go to Administration → Security for Bitbucket Settings and then modify the Global hook drop-down option:

Example of a blocked push