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

Note: using with git-submodules

At the moment Security for Bitbucket doesn't validate changes in git-submodules recursively, scanning parent repository changes only, in case you push all changes together. If your workflow prohibits modifying/pushing sub-modules from parent repo, or if you push nested sub-modules first after such modification, your repositories will be secured and fully scanned by the Security for Bitbucket hook.

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:

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