Secrets

SonarQube Server detects exposed Secrets in your source code and language-agnostic config files, starting in the SonarQube Community Build.

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)

Discover and update the secret-specific Analysis parameters in Administration > Configuration > General Settings > Languages > Secrets

How secrets detection works

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 excluded from secret detection by default. This is the most common reason a hardcoded value in a Markdown file is not reported. The default excluded suffixes are:

  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

  You can customize this list with the sonar.secrets.excluded.file.suffixes property. See Adjusting the binary file exclusion setup.
• 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/).

  When automatic test-file detection skips at least one file, the sensor logs an additional INFO line after the source-file progress line: Skipped <N> file(s) in the secrets analysis due to automatic test file detection.

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 (for example repeated characters, placeholder tokens, or documentation example values). Individual rules add provider-specific entries on top of these shared placeholder patterns. Use sonar.secrets.disableKnownFakeSecretFilter to surface these as low-confidence findings instead.

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

Working through the layers, common reasons include:

1. The file extension is in the excluded-suffixes list (for example, .md), skipped by every rule. This is the most likely reason. Customize this list with sonar.secrets.excluded.file.suffixes.
2. The value is a simple word or matches a known fake-secret pattern (for example, password, mypassword, 123456), rejected by the fake-password filter before entropy is even checked. Use sonar.secrets.disableKnownFakeSecretFilter to surface it as a low-confidence finding.
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.

Adjusting the secret detection scope

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

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.

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.

Adding files based on path-matching patterns

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).

Alternatively, configure the parameters listed below on the CI/CD host (see Analysis parameters 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	Comma-separated list of path-matching patterns. Possible values: A path can be relative (to the sonar.projectBaseDir property, which is by default the directory from which the analysis was started) or absolute. Default value: /*.sh,/.bash,**/.zsh,/*.ksh,/.ps1,**/.properties,/*.conf,/.pem,**/.config,/*.env,.aws/config,/.key The default pattern for .env files was extended from .env (root-only) to **/.env (any depth). Files like config/production.env or envs/staging.env are now scanned without any configuration change.

Adjusting the binary file exclusion setup

SonarQube Server and SonarQube Community Build exclude binary files, and a default set of documentation and template file suffixes, from secret detection. If additional file types are still included in your analysis, you can exclude them.

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 Secrets analysis excluded file suffixes, enter the list of suffixes to be excluded from secret detection.

Alternatively, configure the parameter below on the CI/CD host (see Analysis parameters for more information).

Property	Description	Default
sonar.secrets.excluded.file.suffixes	Comma-separated list of file suffixes excluded from secret detection. An entry that starts with a single dot and contains no other dot (for example, .md) is matched as a file extension. Any other entry is matched as a literal filename suffix.	.adoc,.md,.mdx,.dist,.html,.example,.sample,.template

sonar.text.excluded.file.suffixes is deprecated. Values set on it are still honored alongside sonar.secrets.excluded.file.suffixes, but new configuration should use sonar.secrets.excluded.file.suffixes. In the UI, the deprecated property now appears as (Deprecated) Additional binary file suffixes.

Surfacing low-confidence findings

For benchmarking, evaluation, or to investigate why an expected secret is not reported, you can disable the entropy filter, the automatic test-file detection, and the known fake secret filter. 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
sonar.secrets.disableKnownFakeSecretFilter	When true, candidates matching a rule's curated fake-secret exclusion list (for example, repeated characters, placeholder tokens, or documentation example values) are reported as low-confidence issues instead of being dropped. Useful for benchmark or evaluation projects. UI name: Disable the known fake secret filter for secret detection.	false

When any of these properties 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>

Defining custom secret patterns

The custom secret patterns feature is available starting in Enterprise Edition.

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

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

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.

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.

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

You must specify the secret detection in YAML format according to the Detection section of this schema. 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.

For examples of these three subsections, see configuration YAML files of over 25 secret detection rules provided out-of-the-box with SonarQube Server. To contribute, see CONTRIBUTING.md.

Examples of the matching subsection

To match a string corresponding to MyCustomSecret_123, a minimal configuration would be :

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:

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:

post:
 groups:
    - name: "groupName"
      heuristicFilter:
        heuristics:
          - "uri"
      statisticalFilter:
        threshold: 4.2

Create the corresponding secret detection rule in SonarQube Server

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.
  • issueMessage (optional): Custom issue message displayed on findings raised by this rule instance. When left blank or at its default, the built-in message is used. Overriding it makes it easier to communicate context-specific remediation guidance to developers. Default: User-specified secrets should not be disclosed.

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 quality profile. 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

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

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

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

Related pages

• Adding coding rules