Secrets CLI (Beta)

The Sonar Secrets CLI integrates directly into your Git workflow. It analyzes your code for potential secrets to help you prevent pushing sensitive information to your repositories.

The Sonar Secrets CLI is in beta stage. For more information on release stages, see Product release lifecycle.

This page explains how to set up the Sonar Secrets CLI by installing the pre-commit framework and setting up a hook in your Git repository.

Installing the CLI

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.

The Sonar Secrets CLI cannot be set up 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 use the Sonar Secrets CLI, you need to authenticate to a SonarQube Server instance or to SonarQube Cloud by setting 2 environment variables.

SonarQube Server

• SONAR_SECRETS_AUTH_URL: The URL of your SonarQube instance (e.g., https://example.sonarqube.com).

• SONAR_SECRETS_TOKEN: A SonarQube Server token (requires using Developer Edition or above). Can be created in User > My Account > Security.

SonarQube Cloud

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 CLI - 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. You can also try using Renovate. The pre-commit support is currently a beta opt-in feature.

Using the Secrets CLI as a pre-push hook

It’s possible to use the Secrets CLI as 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, the Sonar Secrets CLI is still scanning all pushed commits, not just the latest one.

Feedback

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