What is credentialscanner?

credentialscanner is a plugin for Bitbucket server that aims to protect against accidentally publishing security credentials such as private keys to Bitbucket repositories.

How does it work?

credentialscanner installs a Pre-receive Hook which scans incoming changes for credentials. Since pre-receive hooks run before changes are written to git, it can effectively veto a git push.

The scan itself involves checking the diff to the previous commit for lines added that match a list of patterns.

Features

  • Scan code sent to Bitbucket with git push for credentials, if suspect credentials found, fail the git push operation
  • Override credential detection by creating JIRA tickets
  • Built-in rules for common credentials
  • create your own rules
  • Scan report in every git push

What crededentialscanner is not

credentialscanner detects credentials based on patterns. There will always be credentials patterns that it is either not aware of or not able to accurately detect without a lot of false positives. See accuracy for an in depth discussion of these limitations.

Users can easily bypass the detection patterns to force storage of real credentials (eg by splitting up text) and while doing so will be somewhat obvious from such contributions, credentials would still have been published. It is not the intention of credentialscanner to prevent this kind of behaviour which would be almost impossible to stop without revoking git push access altogether.

Instead, credentialscanner provides Redress Tickets as a way to capture discussions around why exceptions are required or how a false alarm should be dealt with.

Key Concepts

Rulesets

credentialscanner identifies credentials based on matching changes against a set of rules (ruleset) which describe:

  • What filenames to look at
  • What Filenames to skip
  • Search patterns (Regular Expressions) to look for inside files

When a search pattern matches a file of interest, credentialscanner reports a credential has been detected.

The complete ruleset is loaded from a single JSON file so while credentialscanner ships with a default ruleset, its also possible to use a custom ruleset instead.

Redress Tickets

When credentialscanner identifies a commit that looks like a credential or a bulk import, it will refuse the commit unless a ticket in Jira specifically authorises it.

These Jira tickets are referred to as Redress Tickets.

Redress Tickets capture the reasons credentialscanner was ignored and any discussions around them, eg:

  • False alarm
  • Accepted risk

The value of the resolution field is used to make the final decision around accepting or rejecting changes, as explained below.