> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/security-testing-orchestration/3.0/use-sto/sto-scanner-configuration/gitleaks-scanner-reference.md).

# Gitleaks step configuration

You can scan your code repositories using [Gitleaks](https://github.com/gitleaks) and ingest your results into Harness STO.

### Important notes <a href="#important-notes" id="important-notes"></a>

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

#### Update your allowlist with inactive secrets <a href="#update-your-allowlist-with-inactive-secrets" id="update-your-allowlist-with-inactive-secrets"></a>

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](https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml) and place it at the root of your repository.

{% hint style="info" %}
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.
{% endhint %}

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.

<details>

<summary>.gitleaks.toml example</summary>

```toml
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''',
]

```

</details>

#### Redact secrets <a href="#redact-secrets" id="redact-secrets"></a>

Harness recommends that you configure the Gitleaks step to [redact secrets in the log output](#additional-cli-flags).

#### Speed up your scans <a href="#speed-up-your-scans" id="speed-up-your-scans"></a>

To speed up your scan times, you can configure the Gitleaks step to [limit the number of commits to scan](#additional-cli-flags). By default, Gitleaks scans the entire commit history.

#### Write custom detection rules <a href="#write-custom-detection-rules" id="write-custom-detection-rules"></a>

You can also write your own [custom detection rules](https://github.com/gitleaks/gitleaks?tab=readme-ov-file#configuration).

* For examples, go to the [default Gitleaks config](https://github.com/zricethezav/gitleaks/blob/master/config/gitleaks.toml).
* If you want to contribute to the default configuration, go to the [Contributing guidelines](https://github.com/zricethezav/gitleaks/blob/master/README.md).
* For information about advanced configurations, go to [Stop leaking secrets - configuration](https://blog.gitleaks.io/stop-leaking-secrets-configuration-2-3-aeed293b1fbf).

#### For more information <a href="#for-more-information" id="for-more-information"></a>

### Gitleaks step settings for STO scans <a href="#gitleaks-step-settings-for-sto-scans" id="gitleaks-step-settings-for-sto-scans"></a>

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

#### Scan Mode <a href="#scan-mode" id="scan-mode"></a>

#### Scan Configuration <a href="#scan-configuration" id="scan-configuration"></a>

#### Target <a href="#target" id="target"></a>

**Type**

**Target and variant detection**

**Name**

**Variant**

**Workspace (*****repository*****)**

#### Ingestion File <a href="#ingestion-file" id="ingestion-file"></a>

#### Log Level <a href="#log-level" id="log-level"></a>

#### Additional CLI flags <a href="#additional-cli-flags" id="additional-cli-flags"></a>

Use this field to run the [`gitleaks`](https://github.com/gitleaks/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 <a href="#fail-on-severity" id="fail-on-severity"></a>

#### Settings <a href="#settings" id="settings"></a>

You can also use this field to [speed up your Gitleaks scans](#speeding-up-gitleaks-scans).

#### Additional Configuration <a href="#additional-configuration" id="additional-configuration"></a>

#### Advanced settings <a href="#advanced-settings" id="advanced-settings"></a>

### Configure GitLeaks as a Built-in Scanner <a href="#configure-gitleaks-as-a-built-in-scanner" id="configure-gitleaks-as-a-built-in-scanner"></a>

The GitLeaks scanner is available as a [built-in scanner](/security-testing-orchestration/3.0/use-sto/set-up-sto-scans/built-in-scanners.md) 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 <a href="#proxy-settings" id="proxy-settings"></a>

### Gitleaks step configuration example for STO <a href="#gitleaks-step-configuration-example-for-sto" id="gitleaks-step-configuration-example-for-sto"></a>

Here's an example of a configured Gitleaks step.

```yaml
- 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 <a href="#gitleaks-ingestion-pipeline-example-for-sto" id="gitleaks-ingestion-pipeline-example-for-sto"></a>

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](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md) 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.

```yaml

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 <a href="#gitleaks-orchestration-pipeline-example-for-sto" id="gitleaks-orchestration-pipeline-example-for-sto"></a>

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

```yaml

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
```