> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/languages/secrets.md).

# Secrets

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

This page explains how to configure the secret-specific parameters and to adjust the secret detection scope.

{% hint style="info" %}
SonarQube Community Build doesn’t support defining custom rules based on your own secret patterns to detect secrets that are specific to your company. See [Feature comparison table](/sonarqube-community-build/feature-comparison-table.md) to find out which SonarQube deployments support this feature.
{% endhint %}

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

Discover and update the secret-specific [Analysis parameters](/sonarqube-community-build/analyzing-source-code/analysis-parameters.md) in **Administration** > **Configuration** > **General Settings** > **Languages** > **Secrets**.

## How secrets detection works <a href="#how-secrets-detection-works" id="how-secrets-detection-works"></a>

Secrets detection is not a generic password scanner. It is a layered pipeline that intentionally filters aggressively to keep false-positive rates low. Each layer below is a potential reason why an apparent credential — for example a hardcoded `password = "mypassword"` in a `README.md` — does not produce an issue.

### Layer 1 — Which files are scanned

* **Binary file extensions (\~400) are blacklisted.** No content is ever read for these files. The list covers archives (`.zip`, `.tar`, `.7z`…), images (`.png`, `.jpg`…), compiled artifacts (`.class`, `.dll`, `.so`…), Office documents (`.docx`, `.xlsx`…), and many more. Files whose name looks like an MD5 or SHA hash (32–64 hex characters) are also silently skipped as binary-named cache files.
* **Documentation and template extensions are skipped by every secret rule.** This is the most common reason a hardcoded value in a Markdown file is not reported.

  | Extension                                      | Reason                                                    |
  | ---------------------------------------------- | --------------------------------------------------------- |
  | `.md` / `.mdx`                                 | Markdown documentation                                    |
  | `.html`                                        | HTML pages                                                |
  | `.adoc`                                        | AsciiDoc documentation                                    |
  | `.example` / `.sample` / `.template` / `.dist` | Template or example files not meant to carry real secrets |
* **Development environment and translation paths are rejected by every secret rule.** These paths typically hold fake or non-sensitive values:
  * .NET development profiles: `appsettings.Development*.json`, `appsettings.Local*.json`, `launchSettings.json`
  * Spring Boot dev profile: `application-dev.properties`
  * Dev or test `.env` files: `.env.dev*`, `.env.test*`
  * Docker Compose overrides: `docker-compose.override.yml`, `compose.override.yaml`, etc.
  * VS Code devcontainer: `.devcontainer/devcontainer.json`
  * DDEV local dev: `.ddev/**`
  * i18n / translation files: `**/locales/**/*.json`, `**/i18n/*.json`, `**/resources/messages*.properties`, etc.
* **Only files with an assigned language or matching `sonar.text.inclusions` are analyzed.** When `sonar.text.inclusions.activate` is true and git integration is available, files outside the inclusion patterns and without an assigned language (for example a plain `.txt` or a config with an unusual extension) are not scanned unless you extend the inclusions.
* **Automatically detected test files are filtered out.** Findings raised in those files are not reported by default. Use `sonar.secrets.disableTestFileDetection` to surface them as low-confidence instead. This has no effect on files explicitly declared as tests via the `sonar.tests` property. A file is treated as a test file when **any** of the following is true:
  * Filename signals: starts with `test` (e.g. `testConfig.properties`), contains `test.` or `tests.` (e.g. `myapp.test.env`), or ends with `.spec.js`, `.spec.ts`, `.spec.jsx`, `.spec.tsx`, `_spec.rb`, `_test.rb`, `.t`.
  * Directory signals (any segment in the path): named `test`, `tests`, `e2e`, `mock`, `mocks`, `__tests__`, `__fixtures__`, `testdata`, `fixtures`, `doc`, `docs`, or any segment ending in `test` or `tests` (e.g. `backend-test/`).

### Layer 2 — Entropy filter

After a regex pattern matches a candidate string, the candidate is checked for **Shannon entropy**, a measure of how random a string looks. Strings with many repeated or predictable characters score low and are silently dropped; only candidates above a minimum threshold are kept.

| Example value              | Result       |
| -------------------------- | ------------ |
| `password`                 | Filtered out |
| `Password123`              | Filtered out |
| `hunter2`                  | Filtered out |
| `abc123def`                | Filtered out |
| `ku71CpsLfn8NYhhforGzCRL0` | Passes       |
| `sk-proj-aB3dEf7GhI…`      | Passes       |

A hardcoded value like `password = "mypassword"` or `api_key = "123456789"` is never reported because the matched string has too little entropy. Use `sonar.secrets.disableEntropyFilter` to surface these as low-confidence findings instead.

### Layer 3 — Fake-password filter

Even when entropy is sufficient, regex-based post-filters reject values that look like well-known placeholder patterns. Individual rules add provider-specific entries on top of these shared placeholder patterns.

### Why an obvious "password" in a file is not reported

Working through the layers, common reasons include:

1. The file extension is in the shared rejected-extensions list (e.g. `.md`) — skipped by every rule. This is the most likely reason.
2. The value is a simple word (e.g. `password`, `mypassword`, `123456`) — rejected by the fake-password filter before entropy is even checked.
3. The value has low entropy (e.g. `letmein`, `abc123def`) — rejected by the entropy filter.
4. The file is in a `docs/` or `test/` directory — silently skipped by test-file detection.
5. The file extension is not in the inclusions list — never reached by the scanner at all.

All of these layers are intentional. The goal is to surface real, leaked credentials — not every string that looks vaguely secret-like. To deliberately raise low-confidence findings for tuning or evaluation, see [#surfacing-low-confidence-findings](#surfacing-low-confidence-findings "mention").

## 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 the [Defining matching patterns](/sonarqube-server/2025.4/project-administration/setting-analysis-scope/defining-matching-patterns.md) page).

Alternatively, configure the parameters listed below on the CI/CD host. See the [Analysis parameters](/sonarqube-server/2025.4/analyzing-source-code/analysis-parameters.md) page for more information about other parameters.

| **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>/</strong><em><strong>.sh,</strong>/.bash,\*\*/.zsh,<strong>/</strong></em><strong>.ksh,</strong>/<em>.ps1,<strong>/</strong></em><strong>.properties, /*.conf,/</strong><em><strong>.pem,</strong>/</em>.config,<strong>/*.env,.aws/config</strong></p><p><strong>The default pattern for <code>.env</code> files was extended from <code>.env</code> (root-only) to</strong> <code>/\*.env</code> (any depth). Files like <code>config/production.env</code> or <code>envs/staging.env</code> are now scanned without any configuration change.</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 the [Analysis parameters](/sonarqube-server/2025.4/analyzing-source-code/analysis-parameters.md) page for more information about other parameters.

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

## Surfacing low-confidence findings <a href="#surfacing-low-confidence-findings" id="surfacing-low-confidence-findings"></a>

For benchmarking, evaluation, or to investigate why an expected secret is not reported, you can disable the entropy filter and the automatic test-file detection. Matches that would normally be silently dropped are then reported as **low-confidence** issues, with the filter name appended to the issue message.

Configure these properties in **Administration** > **Configuration** > **General Settings** > **Languages** > **Secrets**, or pass them on the CI/CD host.

| **Property**                             | **Description**                                                                                                                                                                                                                                                                                                                                              | **Default** |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `sonar.secrets.disableEntropyFilter`     | When `true`, low-entropy matches (e.g. placeholder or example secrets) that would normally be silently dropped are reported as low-confidence issues, with the filter name appended to the issue message. Useful for benchmark or evaluation projects. UI name: **Disable the entropy filter for secret detection**.                                         | `false`     |
| `sonar.secrets.disableTestFileDetection` | When `true`, files automatically identified as test files are no longer filtered out. Findings in those files are reported but marked as low-confidence, with the filter name appended to the issue message. Has no effect on files explicitly declared as tests via `sonar.tests`. UI name: **Disable automatic test-file detection for secret detection**. | `false`     |

When either property is enabled, the sensor logs a single `INFO` line at analysis start listing the skipped filters:

```
The secret analysis will skip the following filters per user configuration: <filter names>
```

## 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](/sonarqube-community-build/extension-guide/adding-coding-rules.md)
* [Secrets](/sonarqube-community-build/analyzing-source-code/languages/secrets.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/languages/secrets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.