Scanning Every Push with the Soteri - Scan Commits 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”, or
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, and
Warn-only: print a message to the pusher notifying them of the scan failures, but allow the push to succeed.
Note: UI Edits and 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. Any commits pushed in the same push operation which do not contain the skip-string will still 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:
![](../../__attachments/14786232491/image-20210708-221346.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
When a commit skips the security check, a log message is printed to the Bitbucket log which looks like this:
[INFO] 2022-02-22 13:01:22,106 WARN [hook-callback:thread-1] admin @1R4HND9x781x74x0 0:0:0:0:0:0:0:1 "POST /scm/dev/rep_3.git/git-receive-pack HTTP/1.1" i.s.b.s.h.ValidationPreRepositoryHookCommitCallback 'Soteri - Scan Commits': Checks bypassed in push to DEV/rep_1 by jsecurity. Commits skipped: 24debf934a018ab840494cda536fbb5624cee12a f2ec25125a9732eb708cf175326e6065e47154af a1444c181d2d99b1bc8817799ecd4021bef2bda1
And an Auditable Event is created in Bitbucket’s Audit Log. More information on Audited Events can be found in Viewing Audited Events.
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.
Global hook setting | Project hook toggle | Repository hook setting | Resulting Behavior |
---|---|---|---|
ONLY WHEN ENABLED | DISABLED | DISABLED | Hook OFF |
ONLY WHEN ENABLED | DISABLED | INHERITED | Hook OFF |
ONLY WHEN ENABLED | DISABLED | ENABLED | Hook ON |
ONLY WHEN ENABLED | ENABLED | DISABLED | Hook OFF |
ONLY WHEN ENABLED | ENABLED | INHERITED | Hook ON (mode inherited from project) |
ONLY WHEN ENABLED | ENABLED | ENABLED | Hook ON |
INHERITED OR ENABLED | DISABLED | DISABLED | Hook OFF |
INHERITED OR ENABLED | DISABLED | INHERITED | Hook ON (mode inherited from global) |
INHERITED OR ENABLED | DISABLED | ENABLED | Hook ON |
INHERITED OR ENABLED | ENABLED | DISABLED | Hook OFF |
INHERITED OR ENABLED | ENABLED | INHERITED | Hook ON (mode inherited from project) |
INHERITED OR ENABLED | ENABLED | ENABLED | Hook ON |
ALWAYS | DISABLED | DISABLED | Hook ON (repo setting overridden) |
ALWAYS | DISABLED | INHERITED | Hook ON (mode inherited from global) |
ALWAYS | DISABLED | ENABLED | Hook ON |
ALWAYS | ENABLED | DISABLED | Hook ON (repo setting overridden) |
ALWAYS | ENABLED | INHERITED | Hook ON (mode inherited from project) |
ALWAYS | ENABLED | ENABLED | Hook ON |
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:
![The enable hook dropdown in the Security For Bitbucket settings.](../../__attachments/14786232368/Screen%20Shot%202021-10-21%20at%209.05.40%20AM-20211021-160557.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
The enable hook dropdown in the Security For Bitbucket settings.
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:
![The global hook mode dropdown in the Security For Bitbucket settings.](../../__attachments/14786232368/Screen%20Shot%202021-10-21%20at%209.02.34%20AM-20211021-160252.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
The global hook mode dropdown in the Security For Bitbucket settings.
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 Soteri - Scan Commits hook. A pop-up will prompt you with the option whether to configure the hook in reject or warn-only mode.
![](../../__attachments/14786232368/Screen%20Shot%202021-12-23%20at%2011.22.30%20AM.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
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 Soteri - Scan Commits hook. A pop-up will prompt you with the option whether to configure the hook in reject or warn-only mode.
![](../../__attachments/14786232368/Screen%20Shot%202021-12-23%20at%2011.21.58%20AM.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
Example of a blocked push
![](../../__attachments/14786232368/Screenshot%202023-04-20%20at%2011.32.06%20AM.png?inst-v=dd2e15ff-a066-4891-84cc-df8425dc8a25)
Blocked pushes contain details about each finding. For example, in the first finding:
AWS_CLIENT_ID
is the name of the rule which generated the findingsec_1.js
is the file in which the finding was detectedf75f856f62ebe2eec523617a29f51eca7587523c
is the hash of the commit in which the finding was detectedline 7
is the finding’s line number(11:31)
are the starting and ending indices of the finding withinline 7