Gitleaks step configuration

Scan code repositories with Gitleaks.

You can scan your code repositories using Gitleaks and ingest your results into Harness STO.

Important notes

This section describes recommended best practices and references to useful information.

Update your allowlist with inactive secrets

You can specify an allowlist of secrets that are inactive, rotated, deactivated, or false positives. Gitleaks ignores these secrets during a scan. Set up your allowlist in a .gitleaks.toml file and place it at the root of your repository.

It is best practice to update your allowlist with secrets that are inactive, rotated, deactivated, or false positives. Otherwise, Gitleaks will continue to detect these secrets in your commit history even after they have been updated in your code.

The following steps outline the recommended workflow:

1. Run a Gitleaks scan and review the detected passwords, tokens, and other secrets.

2. Rotate or deactivate all secrets that are currently active.

3. Compile a list of all secrets that are now inactive, rotated, deactivated, or false positives.

4. Update the allowlist in .gitleaks.toml to include these secrets.

Harness recommends that you add your secrets as plain text to the regexes array, as shown in this example. This is the most reliable method to ensure that Gitleaks detects only active secrets when you run another scan.

.gitleaks.toml example

title = "example gitleaks config"

[extend]
# useDefault will extend the base configuration with the default gitleaks config: <a href="#usedefault-will-extend-the-base-configuration-with-the-default-gitleaks-config" id="usedefault-will-extend-the-base-configuration-with-the-default-gitleaks-config"></a>
# https://github.com/zricethezav/gitleaks/blob/master/config/gitleaks.toml <a href="#httpsgithubcomzricethezavgitleaksblobmasterconfiggitleakstoml" id="httpsgithubcomzricethezavgitleaksblobmasterconfiggitleakstoml"></a>
useDefault = true

[allowlist]
# Recommended practice is to add your secrets to a regexes array, <a href="#recommended-practice-is-to-add-your-secrets-to-a-regexes-array" id="recommended-practice-is-to-add-your-secrets-to-a-regexes-array"></a>
# not to a commits array. <a href="#not-to-a-commits-array" id="not-to-a-commits-array"></a>
regexTarget = "match"
description = "whitelist public and test secrets"
regexes = [
  '''1234567890abcdef1234567890abcdef''',
  '''abcdef1234567890abcdef1234567890''',
]

Redact secrets

Harness recommends that you configure the Gitleaks step to redact secrets in the log output.

Speed up your scans

To speed up your scan times, you can configure the Gitleaks step to limit the number of commits to scan. By default, Gitleaks scans the entire commit history.

Write custom detection rules

You can also write your own custom detection rules.

• For examples, go to the default Gitleaks config.

• If you want to contribute to the default configuration, go to the Contributing guidelines.

• For information about advanced configurations, go to Stop leaking secrets - configuration.

For more information

Gitleaks step settings for STO scans

The recommended workflow is to add a GitLeaks step to a Security or Build stage and then configure it as described below.

Scan Mode

Scan Configuration

Target

Type

Target and variant detection

Name

Variant

Workspace (repository)

Ingestion File

Log Level

Additional CLI flags

Use this field to run the gitleaks scanner with additional CLI flags such as:

--redact --log-opts="-n 1000"

• --redact redacts secrets in the log output.

• --log-opts narrows the range of commits that Gitleaks scans in a Pull Request. For example, -n 1000 limits the scan to the last 1000 commits. You can also scan a range of commits using a command such as: tool_args : --log-opts=="--all commitA..commitF"

Fail on Severity

Settings

You can also use this field to speed up your Gitleaks scans.

Additional Configuration

Advanced settings

Configure GitLeaks as a Built-in Scanner

The GitLeaks scanner is available as a built-in scanner in STO. Configuring it as a built-in scanner enables the step to automatically perform scans using the free version without requiring any licenses. Follow these steps to set it up:

1. Search for Secret Detection in the step palette or navigate to the Built-in Scanners section and select the Secret Detection step.

2. Expand the Additional CLI Flags section if you want to configure optional CLI flags.

3. Click Add Scanner to save the configuration.

The scanner will automatically use the free version, detect scan targets, and can be further configured by clicking on the step whenever needed.

Proxy settings

Gitleaks step configuration example for STO

Here's an example of a configured Gitleaks step.

- step:
    type: Gitleaks
    name: gitleaks
    identifier: gitleaks
    spec:
      mode: ingestion
      config: default
      target:
        name: nodegoat
        type: repository
        variant: dev
      advanced:
        log:
          level: debug
      ingestion:
        file: /path/of/file.sarif
    description: gitleaks step

Gitleaks ingestion pipeline example for STO

The following pipeline shows an end-to-end ingestion workflow. The pipeline consists of a Build stage with two steps:

1. A Run step that sends a gitleaks detect command to the local Gitleaks container to scan the codebase specified for the pipeline. This command specifies the output file for the scan results: /shared/scan_results/sarif_simple.sarif.

2. A Gitleaks step that auto-detects the data file type (SARIF) and then ingests and normalizes the data from the output file.

pipeline:
  projectIdentifier: STO
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: gitleaks-build-stage
        identifier: gitleaksbuildstage
        type: CI
        spec:
          cloneCodebase: true
          execution:
            steps:
              - stepGroup:
                  name: Ingestion Workflow with a runs step
                  identifier: Generation
                  steps:
                    - step:
                        type: Run
                        name: gitleaks
                        identifier: Run_1
                        spec:
                          connectorRef: CONTAINER_IMAGE_REGISTRY_CONNECTOR
                          image: zricethezav/gitleaks:latest
                          shell: Sh
                          command: |
                            gitleaks detect --source /harness --report-path /shared/scan_results/ingest-data.sarif --report-format 'sarif' --exit-code 0 --redact -v
                          resources:
                            limits:
                              memory: 2048Mi
                              cpu: 2000m
                        when:
                          stageStatus: Success
                    - step:
                        type: Gitleaks
                        name: gitleaks_ingest
                        identifier: gitleaks_ingest
                        spec:
                          mode: ingestion
                          config: default
                          target:
                            name: gitleaks-example
                            type: repository
                            variant: master
                          advanced:
                            log:
                              level: info
                          ingestion:
                            file: /shared/scan_results/ingest-data.sarif
          sharedPaths:
            - /shared/scan_results
          caching:
            enabled: false
            paths: []
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: K8S_DELEGATE_CONNECTOR
              namespace: harness-delegate-ng
              automountServiceAccountToken: true
              nodeSelector: {}
              os: Linux
  properties:
    ci:
      codebase:
        connectorRef: CODEBASE_CONNECTOR
        repoName: dvpwa
        build: <+input>
  identifier: Gitleaks_docsexample_INGESTION
  name: Gitleaks_docsexample_INGESTION

Gitleaks orchestration pipeline example for STO

The following pipeline illustrates an orchestration workflow where the Gitleaks step scans the codebase and ingests the results in one step.

pipeline:
  projectIdentifier: STO
  orgIdentifier: default
  tags: {}
  stages:
    - stage:
        name: gitleaks-build-stage
        identifier: gitleaksbuildstage
        type: CI
        spec:
          cloneCodebase: true
          execution:
            steps:
              - stepGroup:
                  name: "STO Orchestration "
                  identifier: Orchestration
                  steps:
                    - step:
                        type: Gitleaks
                        name: gitleaks_orch
                        identifier: gitleaks_orch
                        spec:
                          mode: orchestration
                          config: default
                          target:
                            name: gitleaks-example
                            type: repository
                            variant: master
                          advanced:
                            log:
                              level: info
                          settings:
                            tool_args: "--log-opts=\"-n 1000\"`"
                          resources:
                            limits:
                              memory: 2048Mi
                              cpu: 2000m
          sharedPaths:
            - /shared/scan_results
          caching:
            enabled: false
            paths: []
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: K8S_DELEGATE_CONNECTOR
              namespace: harness-delegate-ng
              automountServiceAccountToken: true
              nodeSelector: \{}
              os: Linux
  properties:
    ci:
      codebase:
        connectorRef: CODEBASE_CONNECTOR
        repoName: dvpwa
        build: <+input>
  identifier: gitleaks_docs_example_ORCHESTRATION
  name: gitleaks_docs_example_ORCHESTRATION