Secret scanning
A Data Center license is required to use this feature. Get an evaluation license to try it out, or purchase a license now.
On this page
About secret scanning
While your team collaborates on code to build software, sensitive information such as passwords, tokens, private keys, environment variables, .pem files or other secrets may accidentally get added to your repositories. As soon as code containing secrets gets pushed into your repositories, secrets are added to the commit history and persist until they are revoked. Unidentified breaches may result in the potential use of secrets by any users with access to your repositories.
To improve the security of your repositories and help you make sure that secrets are not accidentally exposed in your code, Bitbucket scans your repositories for secrets and triggers notifications when leaked secrets are detected within new commits. Email notifications are sent out to everyone involved in the commit history of the secret: the authors, committers, and the developer who pushed or merged the code containing secrets into the repositories.
Secret scanning is enabled by default in your Bitbucket instance, and both global and system admins can disable or enable secret scanning by modifying the configuration properties in the bitbucket.properties file.
Customize the scanner
The scanner makes use of default patterns to scan your repositories and can detect a majority of the generic secrets. You can customize the scanner to optimize the performance and reduce the number of false positives—modify or delete the default patterns or add your own regex patterns and file paths.
Project or repository admins, can further configure the scanner at each level. You can't remove the rules inherited from the higher levels unless you have admin permission to the original location (repository, project, global). Forked repositories will use their own rules and will not sync rules from the parent.
To customize:
From either the System, Project, or Repository settings, select Secret scanning.
- Select Create new rule to add your own rule or select More actions … > Edit to modify a default rule.
Enter the rule details such as name, including regex for Line pattern or Path pattern.
When you specify both path and line pattern regex, scanning looks for the pattern only in the specified file paths.
- Select Save.
To remove a rule, select More actions … > Remove.
Customize allowlist rules
You can add an allowlist at the project or repository level to negate matches from scanning rules. Allowlist rule patterns can be defined the same as scanner rules. Any matches to your allowlist will not trigger a notification. Repositories inherit allowlists created at the project level.
If scanning and allowlist rules match, the allowlist rule takes precedence.
To customize allowlist rules:
From either the Project or Repository settings, select Secret scanning.
Select Allowlist rules tab.
Select Add to allowlist to add a rule pattern.
Exclude repositories from scanning
You can exclude specific repositories from scanning at the global or project level. Admins can also exclude all personal repositories at the global level. When excluded, Bitbucket won’t scan any new commits added to the repository.
To exclude repositories from scanning:
From either the System or Project settings, select Secret scanning.
Select Excluded repositories tab.
Select Exclude repositories to exclude specific repositories from scanning.
Select Exclude.
To remove a repository, select More actions … > Remove.
Resolve issues detected by secret scanning
Once a secret has been detected in a repository by the scanner, it is good practice to treat the secret as being compromised. Any secrets that are detected by the scanner should be invalidated in the tool they were created in (either through revoking, deleting, or rotating said secret) and new secrets should be generated in their place. Invalidating secrets may involve working with other teams in your organization such as DevOps or Security to make sure that existing systems and workflows are not impacted.
Removing the secret from Git history by force pushing does not guarantee that the commit is completely cleaned up. There are lots of edge cases (such as other branches, pull requests, forks or local copies) where the commit may still be referenced and so will never be completely removed from Git, even if it is not part of the main branch. Additionally, anyone with access to the repository may have already seen the secret and made a copy of it elsewhere. Therefore, we don’t recommend that you revoke the secret from your commit history as the only preventative measure. The secret must always be revoked in the tool they were created in too.
If the detected secret is a false positive, contact your admin and ask them to make modifications to the secret scanner to reduce the chance of a false positive. Here are some ways to narrow down false positives:
- Modify the regex in a secret scanning rule (sometimes the regex used may be too permissive).
- Provide a path pattern to limit the files and directories scanned.
Use the allowlists at the project and repository levels to specify patterns that aren’t secrets.
Exclude the repositories you don’t want to scan for secrets.