Allow-listing Detected Secrets

Allow-listing false positives in your code

Allow-listing pragmas allow ignoring false positives when new code is committed to the repository. This workflow is suitable for developers who introduce a line which would be flagged by the security pre-receive hook, but they have verified that this finding would indeed be a false positive. Allow-listed lines are ignored by the security pre-receive hook as well as subsequent scans.

To mark findings as benign after they’ve been committed, without adding allowlist pragmas, see Hiding false positives, revoked credentials, etc..

List of supported pragmas

# pragma: allowlist-secret
// pragma: allowlist-secret
/* pragma: allowlist-secret */
' pragma: allowlist-secret

To construct an allowlist pragma, insert one of the above lines exactly as shown as part of a comment that resides on the same line as the false positive.

There must also be a space between the code and either side of the pragma.

For ease of use, the pragma delimiters are chosen to be comment delimiters for a wide variety of environments.

Python allow-listing example

CODE

API_KEY = "a0b1c2d3e4f5g6h7i8j9k0lMnOpQrStUvW" # pragma: allowlist-secret

Java allow-listing example

CODE

String myApprovedSecret = "ThisIsAnExampleSecret"; // pragma: allowlist-secret not actually a secret

C++ allow-listing example

CODE

int key = theSecretCredential; /* pragma: allowlist-secret */

HTML allow-listing example

CODE

<input type='hidden' name='key' value='theSecretCredential' /> <!-- pragma: allowlist-secret -->

MySQL allow-listing example

CODE

select * from users where cred='theSecretCredential'; -- # pragma: allowlist-secret

In this example, we’re using the # approved pragma delimiter but embedding it in a single-line SQL comment delimited by --, so that this line is still functional. (Note the space between the -- and the #.)

XML example with embedded character data representing an executable MySQL command

CODE

<sometext>
    <![CDATA[
        select * from salaries where salary < theSecretCredential; -- # pragma: allowlist-secret
    ]]>
</sometext>

Make sure that the allow-listing is inline! Multi-line allow-listing is not supported.

The allowlist pragma must be introduced in the same commit as the false positive

One thing to keep in mind is that if you’re pushing multiple commits, they will all be scanned individually, and one of the older commits you’re adding may be missing the allowlist pragma. For example,

git add proxy-password-file
git commit proxy-password-file -m “Update proxy settings”
git push => rejected due to embedded password
Update proxy-password-file to add # pragma: allowlist-secret
git commit proxy-password-file -m “Allowlist proxy settings”
git push

When step 6 executes, both the commits from step 2 and step 5 will be scanned. In the #2 commit there is a failure detected, but no allowlist pragma is present, so the commit is considered in violation. The #5 commit passes all checks, but since there is one failing commit in the push, the whole push is rejected.

The per-commit scanning ensures that if a secret was added in one commit and subsequently removed in another commit, it will still be found. It’s important to catch this situation, because the secret has not been properly cleaned from history.

Allow-listing specific files / paths (since version 1.10.0)

You can also specify a list of files / folders for which all found vulnerabilities should be marked as allow-listed for a specific repository.

Per-repository allowlist configuration

Allow-listed files can be also configured on a repository level in the soteri-security.yml file. Please refer to documentation for the allowlist_paths configuration option in Defining Repository-Level Detection Rules | Supported-Configuration

Please remember to use enable per-repository configuration in the global plugin settings – it is not enabled by default.

Skip-listing specific files / paths

You can also specify a list of files, or a regular expression for many paths, for which scanning should not be performed, and no findings, even allowlisted findings, should be generated. Please refer to the documentation for skip_file_paths and skip_file_patterns fields in Defining Repository-Level Detection Rules | Supported-Configuration.