Secrets scanning

Prevent secrets from leaking through your AI agent with Sonar’s Secrets scanning features.

This feature is in Beta stage. See the SonarQube Server Product release lifecycle or the SonarQube Cloud Product release lifecycle pages for more information on release stages.

This page explains how to set up secrets scanning covering three use cases:

• You want to make sure your commits do not contain any leaking secrets.

• You want to make sure Claude cannot read a file containing a secrets.

• You want to prevent secrets from leaking in your interactions with Claude.

Claude Code hook

Check out the example in the Quickstart secrets detection guide to set up SonarQube CLI and the Claude Code hook.

Git repository hook

Installing the pre-commit framework

First, install the pre-commit framework, a tool that manages and runs pre-commit hooks:

1. Run the command to install the framework:

PIP

pip install pre-commit

BREW

1. Validate that the pre-commit is properly installed:

pre-commit -V

Creating the configuration file

1. Create a configuration file named .pre-commit-config.yaml in the root directory of your Git repository and provide the following information. This file tells the pre-commit framework which hooks to run:

repos:
-   repo: https://github.com/SonarSource/sonar-secrets-pre-commit
    rev: v2.38.0.10279
    hooks:
    -   id: sonar-secrets
        stages: [pre-commit]

1. Run pre-commit autoupdate to make sure you are using the latest version, then commit this file to your repository to share the configuration with the other contributors.

2. Add this file to every repository you want to protect.

This setup cannot be configured to analyze all your repositories automatically. Due to how Git hooks are designed, setting global pre-commit hooks comes with major drawbacks (e.g., overriding all project-specific pre-commit hooks).

Installing the hook in your Git repository

With the pre-commit framework installed and the configuration file created, you can now install the hook in your Git repository. In your terminal, navigate to the root directory of your repository and run:

pre-commit uninstall  
pre-commit clean  
pre-commit install

This command sets up the pre-commit hook in your .git/hooks directory.

Every contributor has to run these commands locally on every repository to initialize the pre-commit framework.

Setting up authentication

To start scanning for secrets, you need to authenticate to a SonarQube Server instance or to SonarQube Cloud by setting 2 environment variables.

SONARQUBE CLOUD

• SONAR_SECRETS_AUTH_URL: The URL of SonarQube Cloud (either https://sonarcloud.io or https://sonarqube.us).

• SONAR_SECRETS_TOKEN: A SonarQube Cloud user token. Can be created in User > My Account > Security.

User tokens are required when authenticating your SonarQube CLI with SonarQube Cloud or SonarQube Server. Note that the CLI will not function properly if project tokens, global tokens, or scoped organization tokens are used during the setup process.

SONARQUBE SERVER

If needed, you can also set the following optional environment variables:

• SONAR_SECRETS_AUTH_CERT_FILE: the path to the PEM certificate file used for the authentication request

• SONAR_SECRETS_AUTH_PROXY: the proxy URL used for the authentication request

The authentication process will be re-triggered every 7 days, so these environment variables should be safely persisted for easier usage.

Testing the hook

Now that the hook and authentication are active, you can check that everything works by committing a file that contains a potential secret:

1. Create a file named secrets.js with a fake API key.

const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";

1. Commit the file to your repository:

git add secrets.js  
git commit -m "Add a test file with a secret"  

The pre-commit hook will run, detect the "secret" string, and block the commit. The commit will fail, preventing you from accidentally pushing the secret.

Sonar Secrets............................................................Failed
- hook id: sonar-secrets
- exit code: 1
Sonar Secrets - BETA (2.38.0.10279)
Running analysis...
Found 1 secret
SonarQube Token
File: secrets.js
Location: [1:17-1:61]

You will need to remove or redact the secret before you can successfully commit.

Skipping the pre-commit check

Sometimes, the CLI may raise false positives: it flags a string that isn't actually a secret. In such cases, and only when you're certain the code is safe, you can temporarily bypass the pre-commit checks. Please report any false positives or feedback here.

To skip the secrets pre-commit hook for a single commit, use SKIP=sonar-secrets with the git commit command:

SKIP=sonar-secrets git commit

This tells Git to bypass the pre-commit hook entirely, allowing the commit to proceed. Use this option with caution and only when you're confident that the files do not contain any real secrets.

Keeping the pre-commit up to date

You can update your hooks to the latest version automatically by running pre-commit autoupdate. By default, this will bring the hooks to the latest tag on the default branch. The pre-commit support is currently a beta opt-in feature.

Using Secrets scanning as a pre-push hook

It’s possible to scan for secrets using a pre-push hook instead of a pre-commit hook, since they’re supported by the pre-commit framework

To achieve this, you need to modify the YAML config of the pre-commit hook created in Creating the configuration file.

# Needed, otherwise it will try to install it as a pre-commit hook, as the default value is "[pre-commit]" default_install_hook_types: [pre-push]
repos:
-   repo: https://github.com/SonarSource/sonar-secrets-pre-commit
    rev: v2.38.0.10279
    hooks:
    -   id: sonar-secrets
        stages: [pre-push] # From "pre-commit" to "pre-push"

With this configuration, you're still scanning all pushed commits, not just the latest one.

Feedback

If you have any feedback about these features (false positives, crashes, UX, or anything!), reach out to us on the community forum.