# Secrets

Secrets are pieces of user-specific or system-level credentials that should be protected and accessible to legitimate users only. SonarQube Server detects exposed Secrets in all files processed by the language analyzers and in all files configured through the `sonar.text.inclusions` property.

## Configuring secret-specific parameters (general procedure) <a href="#language-specific-properties" id="language-specific-properties"></a>

Discover and update the secret-specific [analysis-parameters](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/analysis-parameters "mention") by going to **Administration** > **Configuration** > **General Settings** > **Languages** > **Secrets**

## Adjusting the secret detection scope <a href="#detection-scope" id="detection-scope"></a>

By default, SonarQube Server and SonarQube Community Build detect exposed secrets in all files processed by the language analyzers. You can refine the scope of the secret detection by:

* Excluding hidden files from the analysis.
* Adding files based on path-matching patterns.
* Adjusting the binary file exclusion setup.

### Analysis of hidden files <a href="#analysis-of-hidden-files" id="analysis-of-hidden-files"></a>

Depending on which scanner is used, additional hidden files tracked by Git are included in the secrets analysis.

This behavior can be disabled by setting the `sonar.scanner.excludeHiddenFiles` analysis parameter to `true`.

{% hint style="warning" %}
Analyzing additional hidden files is currently only partially supported with the SonarScanner for Maven and Gradle. Additional hidden files are only analyzed if they’re inside the `src/main/java` or `src/test/java` folder in the root or module directories.

Analyzing additional hidden files is currently not supported with SonarScanner for .NET.
{% endhint %}

### Adding files based on path-matching patterns <a href="#adding-files-based-on-pathmatching-patterns" id="adding-files-based-on-pathmatching-patterns"></a>

If you’re using a git repository, you can add files to the secret detection scope by defining path-matching patterns: the files matching the patterns will be included **provided they are tracked by git**.

To add additional files to the secret detection:

1. In the SonarQube Server UI:
   * For a global configuration: go to **Administration** > **Configuration** > **General Settings** > **Languages** > **Secrets**
   * For a project-level configuration: open your project page and go to **Project Settings** > **General Settings** > **Languages** > **Secrets**
2. Enable the **Activate inclusion of custom file path patterns** option.
3. In the **List of file path patterns to include**, adjust the default path-matching patterns if necessary (see [defining-matching-patterns](https://docs.sonarsource.com/sonarqube-server/project-administration/adjusting-analysis/setting-analysis-scope/defining-matching-patterns "mention")).

Alternatively, configure the parameters listed below on the CI/CD host (see [analysis-parameters](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/analysis-parameters "mention") for more information).

| **Property**                     | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sonar.text.inclusions.activate` | Enables the inclusion of files to the secret detection according to the path-matching patterns defined in `sonar.text.inclusions`.                                                                                                                                                                                                                                                                                                                                                          |
| `sonar.text.inclusions`          | <p>Comma-separated list of path-matching patterns.</p><p><strong>Possible values:</strong> A path can be relative (to the <code>sonar.projectBaseDir</code> property, which is by default the directory from which the analysis was started) or absolute.</p><p><strong>Default value</strong>: <strong>/*.sh,</strong>/<em>.bash,\*\*/</em>.zsh,<strong>/*.ksh,</strong>/<em>.ps1,**/</em>.properties,<strong>/\*.conf,</strong>/<em>.pem,**/</em>.config,.env,.aws/config,\*\*/\*.key</p> |

### Adjusting the binary file exclusion setup <a href="#adjusting-the-binary-file-exclusion-setup" id="adjusting-the-binary-file-exclusion-setup"></a>

SonarQube Server and SonarQube Community Build exclude binary files from the analysis. In case binary file types are still included in your analysis, you can exclude these additional files.

To do so:

1. In the SonarQube Server and SonarQube Community Build UI,
   * For a global configuration: go to **Administration** > **Configuration** > **General Settings** > **Languages** > **Secrets**.
   * For a project-level configuration: open your project page and go to **Project Settings** > **General Settings** > **Languages** > **Secrets**.
2. In **Additional binary file suffixes**, enter the list of suffixes to be excluded.

Alternatively, configure the parameter below on the CI/CD host (see [analysis-parameters](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/analysis-parameters "mention") for more information).

| **Property**                        | **Description**                                                         |
| ----------------------------------- | ----------------------------------------------------------------------- |
| `sonar.text.excluded.file.suffixes` | Comma-separated list of additional binary file suffixes to be excluded. |

## Defining custom secret patterns <a href="#defining-custom-secret-patterns" id="defining-custom-secret-patterns"></a>

*The custom secret patterns feature is available starting in* [*Enterprise Edition*](https://www.sonarsource.com/plans-and-pricing/enterprise/)*.*

In order to detect secrets that are specific to your company, you can define custom rules based on your own secret patterns.

In a given custom rule, the secret detection is specified as follows:

* The secret patterns to detect are defined through regular expressions. A context can be added to restrict the matching.
* Specific files can be excluded from the secret detection based on the file name or content. This allows improving the detection accuracy and time.
* Obvious false-positive matches can be excluded from the detection results.

The main steps to create a custom rule are:

1. Define and test the regular expressions matching the secrets to detect.
2. Specify the rule’s secret detection in YAML format.
3. Create the corresponding secret detection rule in SonarQube Server and add it to your quality profile for secrets.

These steps are described below.

### Define the regular expressions matching the secrets to detect <a href="#define-the-regular-expressions-matching-the-secrets-to-detect" id="define-the-regular-expressions-matching-the-secrets-to-detect"></a>

Define and validate the regular expression(s) matching the secrets to be detected by your custom rule.

{% hint style="warning" %}
**Warning**: Because it’s easy to make a mistake while writing regular expressions, we strongly recommend you validate your regular expressions before deploying them at scale and impacting all your projects.
{% endhint %}

To build, test, and debug regular expressions, we recommend that you use <https://regex101.com/>.

In addition, you can apply the Sonar’s rules dedicated to regular expressions to your regular expressions to make sure there are no mistakes and no performance problems and possibly to find a simpler way to write the same regular expression. To do so, proceed as follows:

**Step 1:** Create a small Java project (since the secret detection feature uses Java) and put your regular expressions into it. In the project example below, replace `CustomRegExpExample` with your regular expression.

```css-79elbk
import java.util.regex.Pattern;

public class CustomSecretRegExpCheck {
    public static void main(String[] args) {
        CustomSecretRegExpCheck checker = new CustomSecretRegExpCheck();
        final String INPUT = "Hello, World!";

        System.out.println("Result: " + checker.isMatchingCustomRegExpExample(INPUT));
    }

    public boolean isMatchingCustomRegExpExample(String input) {
        Pattern pattern = Pattern.compile("CustomRegExpExample.*");
        return pattern.matcher(input).find();
    }
}
```

**Step 2:** Run a SonarQube Server analysis on your project. Note that if you use an IDE running SonarQube for IDE, you will get immediate feedback and this step is not necessary.

### Specify the rule’s secret detection in YAML format <a href="#specify-the-rules-secret-detection-in-yaml-format" id="specify-the-rules-secret-detection-in-yaml-format"></a>

You must specify the secret detection in YAML format according to the `Detection` section of this [schema](https://github.com/SonarSource/sonar-text/blob/master/sonar-text-plugin/src/main/resources/org/sonar/plugins/secrets/configuration/specifications/specification-json-schema.json#L74). This section consists of three subsections:

* `pre`: Defines the files to be excluded from the secret detection based on file name or content.
* `matching`: Contains the regular expressions used to detect the secrets.
* `post`: Defines the obvious false-positive to be excluded from the matching candidates.

{% hint style="info" %}
For examples of these three subsections, see configuration [YAML files](https://github.com/SonarSource/sonar-text/tree/master/sonar-text-plugin/src/main/resources/org/sonar/plugins/secrets/configuration) of over 25 secret detection rules provided out-of-the-box with SonarQube Server. To contribute, see [CONTRIBUTING.md](https://github.com/SonarSource/sonar-text/blob/master/CONTRIBUTING.md).
{% endhint %}

**Examples of the matching subsection**

To match a string corresponding to *MyCustomSecret\_123*, a minimal configuration would be *:*

```css-79elbk
matching:
  pattern: "MyCustomSecret_\\d{3}"
```

You can also restrict the detection to particular contexts. For example, if you want to detect *MyCustomSecret\_123* only if:

* either preceded by *beforeContext*
* or followed by *afterContext*

Then, you could use the following matching configuration:

```css-79elbk
matching:
  pattern: "MyCustomSecret_\\d{3}"
  context:
    matchEither:
      - patternBefore: "beforeContext"
      - patternAfter: "afterContext"
```

**Post filtering**

Starting with SonarQube Server version 2025.3, the `inputString` field for heuristic and statistical post filters has been discontinued. Previously, this field was used to apply post filters to the named capturing group specified within it. The functionality has been extended to allow applying post filters directly to named capturing groups using the following syntax:

```css-79elbk
post:
 groups:
    - name: "groupName"
      heuristicFilter:
        heuristics:
          - "uri"
      statisticalFilter:
        threshold: 4.2
```

## Create the corresponding secret detection rule in SonarQube Server <a href="#create-the-corresponding-secret-detection-rule-in-sonarqube-server" id="create-the-corresponding-secret-detection-rule-in-sonarqube-server"></a>

You can now create the corresponding custom rule in SonarQube Server. To do so, you’ll create an instance of the rule template **S6784**: *User-specified secrets should not be disclosed*.

Proceed as follows:

**Step 1:** In the top navigation bar of SonarQube Server, select **Rules**.

**Step 2:** Set the rule search filter as follows:

1. 1. In the **Language** option, select **Secrets**.
   2. In the **Template** option, select **Show Templates Only**.

**Step 3:** In the search results, select the **User-specified secrets should not be disclosed** rule.

**Step 4:** At the bottom of the rule page, in the **Custom Rules** section, select **Create**. The **Create Custom Rule** dialog opens.

**Step 5:** Fill in the rule parameter fields:

* * **Name**: Rule title.\
    We recommend making it very explicit about the service, department, and in-house application.\
    Example: *AppXZY tokens should not be disclosed*
  * **Key**: Unique identifier of the rule.\
    We recommend following a naming convention to make it easier to retrieve your custom secrets.
  * **Type**: Rule type. Default (recommended): **Vulnerability**.
  * **Severity**: Rule severity. Default (recommended): **Blocker**.
  * **Status**: Rule status. Default (recommended): **Ready**.
  * **Description**: Rule description. The description should be as detailed as possible in order to allow the developer to know what to do in case of a secret detection. In this field, you can describe the procedure to be followed in your company for such cases.
  * **DetectionSpecification:** Copy and paste into this field the specification you created in the **Specify the rule’s secret detection in YAML format** step as illustrated below.

![](https://content.gitbook.com/content/3VWSqvZ4eaBLWvA6epdv/blobs/vO1wt8tvHSqzyjHO5jwe/ca9e400939b3e9c411fb6453caf397a0b5203af0.png)

**Step 6:** Select **Create**. The dialog closes and the new rule is created.

**Step 7:** Add the new rule to the quality profile that you use for secrets: see [editing-a-custom-quality-profile](https://docs.sonarsource.com/sonarqube-server/quality-standards-administration/managing-quality-profiles/editing-a-custom-quality-profile "mention"). If you don’t already have a custom quality profile for secrets, you must create one; it’s strongly recommended that you extend the Sonar Way Quality Profile to make it your own.

## Parallel code scan <a href="#parallel-code-scan" id="parallel-code-scan"></a>

By default, the analyzer tries to parallelize the analysis of compilation units; it spawns as many jobs as logical CPUs available on the machine.

If required, it is possible to customize the number of scheduled parallel jobs by configuring the property `sonar.text.threads=n` at the scanner level, where `n` is an integer indicating the maximum number of parallel jobs.

You should consider setting the `sonar.text.threads` property only when the automatic detection of the number of logical CPUs cannot detect the desired number. A typical example is when the analysis should not consume all the available computing resources to leave room for other tasks running in parallel on the same machine.

When setting the `sonar.text.threads` property, you should set it to a value less or equal to the number of logical CPUs available. Over-committing doesn’t accelerate the analysis and can even slow it down.

## Analysis of files that don't contain code <a href="#analysis-of-files-that-dont-contain-code" id="analysis-of-files-that-dont-contain-code"></a>

Files that don’t contain code (for example, `build.gradle` and `sonar-project.properties`) are scanned durning analysis and displayed in the SonarQube Server UI after an issue is detected in them. If no secrets are detected in those files, they are not displayed in the UI.

## Deactivating secrets analysis <a href="#deactivating-secrets-analysis" id="deactivating-secrets-analysis"></a>

You can deactivate the analysis of secrets by setting the `sonar.text.activate` property to `false`.

## Related pages <a href="#related-pages" id="related-pages"></a>

* [adding-coding-rules](https://docs.sonarsource.com/sonarqube-server/extension-guide/adding-coding-rules "mention")
* [secrets](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/languages/secrets "mention")