Secret detection with Gitleaks

Available since 1.14.0 (EE), with the early access flag fe_security_scan_policies

Secret detection in Deckhouse Code looks for credentials committed to a project’s own source code. The scanner behind it is Gitleaks, and the scan is called gitleaks_secret_detection. The scan is mandated by a scan execution policy in a separate security policy project; the project’s own .gitlab-ci.yml does not add it. The policy decides what fails the pipeline, and the scanned project cannot override this from its own CI/CD settings.

What the scan does

The gitleaks_secret_detection action adds two jobs to the policy’s stage, fe-security-scanner unless the policy’s “CI stage” field names another. Each job is named with a trailing :<policy slug>-p<policy project id>, so a group policy and a project policy mandating the same scan get jobs of their own.

Both jobs upload artifacts with when: always, so a failed pipeline still carries the findings that failed it. gitleaks_secret_junit also keeps the findings in SARIF, security-reports/sarif/gitleaks.sarif, as a plain artifact for tools that read that format.

The scan reads the working copy of the commit being built. A commit that removes a secret clears its finding, but the secret stays in the repository history until the history is rewritten. The policy editor offers no other choice. A policy written by hand can set FE_SCANS_GITLEAKS_SCOPE: history among the action’s variables to read the whole history, and FE_SCANS_GITLEAKS_LOG_OPTS to narrow it to a range of commits in git log terms.

A file kept in Git LFS is scanned by its real content: the pointer that stands for it in the repository is not read. A submodule is not scanned: only what is checked out in the project itself is read.

The scanning job’s log states the Gitleaks version and, once the scan finishes, how many findings it made, listed by rule. A run that finds nothing still publishes a report, [].

Prerequisites

Before the scan can run, make sure that:

• an administrator has turned on the fe_security_scan_policies feature flag as described on the Early access page;
• a security policy project is linked to the project or to a group above it, or the policy editor creates and links one when you save the first policy by the steps in Turning the scan on;
• a runner that runs jobs in container images is available and can pull both images the scan uses:
  • the scanner image, chosen as Where the scanner image comes from describes; for an image in a private registry, the policy names the CI/CD variables that hold the login and the password in its registry variable fields;
  • the image of gitleaks_secret_junit, ruby:3.3.10-slim by default, redirected with the server environment variable FE_SCANS_REPORT_CONVERTER_IMAGE; the policy gives this job no registry credentials, so the runner pulls the image without them;
• a project that holds the configuration file or the ignore file named in the policy lets the scanned project’s jobs read it: in that project, “Settings” → “CI/CD” → “Job token permissions” lists the scanned project or its group.

Turning the scan on

To turn on the scan in the policy editor:

1. In the project or group, select “Secure” → “Policies”.
2. Click “New policy”.
3. On “Select a policy type”, click “Scan execution policy”.
4. Name the policy.
5. Under “Security scans”, expand “Secret Detection (embedded Gitleaks)” and tick “Enable this scanner”.
6. Set up the section’s groups as described in What the policy sets.
7. Click “Configure with a merge request”.

This opens a merge request in the security policy project. If no security policy project is linked yet, the editor creates and links one first. The policy applies once that merge request is merged.

While the policy cannot be saved, “Configure with a merge request” stays unavailable and the editor lists the reasons under it, after “Saving is unavailable:”. The list is shown in “.yaml mode” too.

Under “Configure with a merge request” the editor names the policy project the merge request goes to, or the path of the project that saving creates. When saving cannot create it, a warning says why instead:

• Only an Owner can create or link a policy project.
• A project with that path or name already exists; the warning links to the page where it can be linked.
• The administrator restricted the visibility level the project would get (the visibility of the group or project the policy belongs to).
• You have reached your personal projects limit.
• You cannot create projects in the group.
• The generated name or path is not valid; the warning adds the validation error.
• A policy project was linked after the page opened; reload the page to see it.

The button stays available while the warning is shown; the server refuses the save for the same reason.

Alternatively, add the action directly to .deckhouse_code/security-policies/policy.yml in the security policy project:

scan_execution_policy:
  - name: Secret detection everywhere
    enabled: true
    rules:
      - type: pipeline
        branches: ["*"]
    actions:
      - scan: gitleaks_secret_detection

A policy can have only one action per scanner: a policy with a second scan: gitleaks_secret_detection action cannot be saved. Put a second set of settings in a policy of its own.

What the policy sets

In the policy editor, gitleaks_secret_detection is the “Secret Detection (embedded Gitleaks)” section under “Security scans”. The section has one checkbox, “Enable this scanner”; once it is ticked, the section shows all its groups: the scanner image, whether a finding fails the pipeline, the configuration file, the ignore file and additional arguments. Below the groups is the runner tags field for the scan’s two jobs, with the placeholder “Runner tags, comma-separated”. A folded section shows “Scanner enabled” or “Scanner disabled” beside its heading.

Scanner image

Left empty, “Scanner image” means the image Deckhouse Code is configured for, shown greyed out as the field’s own placeholder; steps 2 and 3 of Where the scanner image comes from name that image. The registry host may be left out for an image on Docker Hub, as in zricethezav/gitleaks:v8.30.1. A reference that is not whole, such as zricethezav/gitleaks with no tag or digest, does not stop the policy from being saved: the scan job stops with this scan was not given what the policy asks for: scanner image: ….

The two variable fields are for an image in a private registry. The policy names the variables, never their values. In the policy file they are FE_SCANS_REGISTRY_LOGIN_VARIABLE and FE_SCANS_REGISTRY_PASSWORD_VARIABLE among the action’s variables. The policy is not saved when:

• only one of the two fields is filled;
• a value is not written as $NAME or ${NAME};
• a name starts with FE_, CI_ or GITLAB_.

To give the scan access to a private registry:

1. In the scanned project or its group, create two CI/CD variables of the type “Variable (default)”: one with the login, one with the password or token. Mask the password variable.
2. Enter their names in “Registry login variable” and “Registry password variable”.

The variables are read from the scanned side: a group policy relies on a group variable, and a project variable with the same name takes its place and makes the pull fail if its value is wrong. The credentials reach gitleaks_secret_scan only, and are not used for the image shipped with the product.

Fail on findings

A checkbox, ticked by default.

In the policy file the checkbox is FE_SECURITY_FAIL_ON: info when ticked, report_only when not.

Every finding is reported at severity CRITICAL, so there is no threshold to set between levels as in SAST scanning with Opengrep: a finding either fails the pipeline or it does not.

Configuration file

The file may carry an [extend] section, allowlists of single rules, and rules it switches off. The set built into the scanner image stays in force unless the file says otherwise; a file with no [extend] section is read as extending it. An [extend] section is accepted only with useDefault = true and, beside it, disabledRules. The job stops before scanning when the file carries anything else in [extend], a second [extend], a top-level allowlist, or disabledRules outside [extend].

The scan job reads the file with its own job token, so the project named in “Project” must give the scanned project the access described in Prerequisites.

The policy is saved with “Project” empty or naming the scanned project itself, and the scan job then stops before scanning. The scan never reads the scanned project’s own .gitleaks.toml, which stays in the checkout.

Ignore file

The scanned project’s own .gitleaksignore is removed from the checkout before the scan runs, so the file this field names is the only place a finding is suppressed. A gitleaks:allow comment on the line of a secret is not honored either: the scan passes --ignore-gitleaks-allow, so a comment committed beside a secret does not silence its own finding.

Additional arguments

A note beside the field says that what the scan reports is published as a security report, so it reaches the vulnerability report and whatever the administrator has connected to it.

Flags the job sets itself are refused, with the flag named: those that move or reshape the report, replace the configuration, suppress findings (--baseline-path, --ignore-gitleaks-allow, --enable-rule), set the exit code, redaction, banner, colors or diagnostics, name the commits to read (--log-opts), switch to another mode (--pre-commit, --staged), set the platform used for finding links (--platform), or print help instead of scanning. The log levels warn, error, fatal, panic and disabled stop the job, which reads the scanner’s own log back.

Where the scanner image comes from

The server resolves the image once, before the job starts, and writes it in as a literal value; the scanned project’s own CI/CD settings cannot redirect it. Resolution order:

1. The policy’s own “Scanner image” field, if it is a whole reference: a path and a tag, a digest, or both.
2. Otherwise, the image set in the FE_SCANS_GITLEAKS_IMAGE environment variable of the Deckhouse Code server.
3. Otherwise, the image this release pins, zricethezav/gitleaks:v8.30.1.

FE_SCANS_GITLEAKS_IMAGE is an environment variable of the server processes that render pipelines, the web server and Sidekiq; an administrator sets it in their environment. The same name among the CI/CD variables of a project or a group has no effect. In the policy file the “Scanner image” field is the FE_SCANS_GITLEAKS_IMAGE key of the action’s variables.

A filled field that is not a whole reference does not fall back to steps 2–3 for the scan: the job stops with this scan was not given what the policy asks for: scanner image: … before scanning. The job is still started in the image of step 2 or 3, so that image must be pullable.

An installation with no route to the internet mirrors this image into its own registry and names the mirrored reference in the server environment variable FE_SCANS_GITLEAKS_IMAGE or in the policy’s “Scanner image” field. If that registry asks for a login, fill the registry variable fields of the policy.

Where results appear

Each test case is named CRITICAL <rule> <description> [<file>:<line>]. The description is the one Gitleaks gives the rule; a rule without one is named by its identifier once. A repeated name gets a trailing #2, #3 and so on. The finding’s description ends with Gitleaks rule: <rule> on its own line.

A passing test case named gitleaks scan states what was scanned (the working copy of the commit, or the history), how many fingerprints the policy’s ignore file holds, and which additional arguments were passed, if any.

Job names carry the policy’s own slug and its policy project’s id; DefectDojo reconciles tests by that whole name. Renaming the policy, or moving it to another policy project, starts a new test in DefectDojo.

Troubleshooting

Additional resources

• SAST scanning with Opengrep
• Scanning with Trivy
• Vulnerability report
• Security scanner integrations