Scanning Every Push with the Security Hook

Security for Bitbucket contains a pre-receive hook, which can run a scan on any code before it is pushed into Bitbucket. At the Bitbucket instance level, the Security Hook can be configured to run:

• Only when explicitly enabled for a repository or project.

• For repositories where the hook is configured as “inherited” (the Bitbucket default) or “enabled”.

• Always (cannot be disabled on the repository or project level).

When enabled, the Security Hook has two modes:

• Block: 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.

Note: UI Edits & Warn-only mode

Warnings can’t be presented to users when they commit using the Bitbucket built-in web editor.

Note: using with git-submodules

Repositories included via git-submodules are treated as separate repositories. When enabling the hook, make sure to also enable it on any relevant repositories included via git-submodules.

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

The security hook can be enabled globally, on a project level, or on the repository level. 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.

If the global hook is set to “always (cannot be disabled)”, security checks cannot be weakened. For instance, if the global hook is set to block, even if the repository hook is set to warn, potentially vulnerable commits will be blocked. If the hook is overridden on, an additional customizable message will be displayed to developers.

Personal repositories (those with ~username in the path) do not support inheritance, since they don’t belong to a project. The only way to enable the Security Hook for all personal repositories is to enable the Global Hook “always (cannot be disabled)”.

Enabling the hook globally

To enable the hook on a global scale, Bitbucket administrator, or anyone granted access to Security for Bitbucket, can go to Administration → Security for Bitbucket Settings and then modify the Enable hook drop-down option:

When the global hook enabled is set to either “when explicitly enabled or inherited” or “always”, the global hook mode can be configured to be Block or Warn:

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 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.

Example of a blocked push