Customize rulesets

DETAILS: Tier: Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

• Enabled support for specifying ambiguous passthrough refs in GitLab 16.2.

You can customize the behavior of our SAST analyzers by defining a ruleset configuration file in the repository being scanned. There are two kinds of customization:

• Modifying the behavior of predefined rules. This includes:
  • Disabling predefined rules. Available for all analyzers.
  • Overriding metadata of predefined rules. Available for all analyzers.
• Replacing predefined rules by building a custom configuration using passthroughs. Available only for the Semgrep-based analyzer.

Advanced SAST supports only modifying the behavior of predefined rules, not replacing predefined rules.

Disable predefined rules

You can disable predefined rules for any SAST analyzer.

When you disable a rule:

• Most analyzers still scan for the vulnerability. The results are removed as a processing step after the scan completes, and they don't appear in the gl-sast-report.json artifact.
• Findings for the disabled rule no longer appear in the pipeline security tab.
• Existing findings for the disabled rule on the default branch are marked as No longer detected in the vulnerability report.

The Semgrep-based analyzer handles disabled rules differently:

• To improve performance, the Semgrep-based analyzer doesn't scan for disabled rules at all.
• If you disable a rule in the Semgrep-based analyzer, existing vulnerability findings for that rule are automatically resolved after you merge the sast-ruleset.toml file to the default branch.

See the Schema and Examples sections for information on how to configure this behavior.

Override metadata of predefined rules

You can override certain attributes of predefined rules for any SAST analyzer. This can be useful when adapting SAST to your existing workflow or tools. For example, you might want to override the severity of a vulnerability based on organizational policy, or choose a different message to display in the Vulnerability Report.

See the Schema and Examples sections for information on how to configure this behavior.

Build a custom configuration

You can replace the GitLab-maintained ruleset for the Semgrep-based analyzer with your own rules.

You provide your customizations via passthroughs, which are composed into a passthrough chain at runtime and evaluated to produce a complete configuration. The underlying scanner is then executed against this new configuration.

There are multiple passthrough types that let you provide configuration in different ways, such as using a file committed to your repository or inline in the ruleset configuration file. You can also choose how subsequent passthroughs in the chain are handled; they can overwrite or append to previous configuration.

See the Schema and Examples sections for information on how to configure this behavior.

Create the configuration file

To create the ruleset configuration file:

1. Create a .gitlab directory at the root of your project, if one doesn't already exist.
2. Create a file named sast-ruleset.toml in the .gitlab directory.

Specify a remote configuration file

• Introduced in 16.1.

You can set a CI/CD variable to use a ruleset configuration file that's stored outside of the current repository. This can help you apply the same rules across multiple projects.

The SAST_RULESET_GIT_REFERENCE variable uses a format similar to Git URLs for specifying a project URI, optional authentication, and optional Git SHA. The variable uses the following format:

[<AUTH_USER>[:<AUTH_PASSWORD>]@]<PROJECT_PATH>[@<GIT_SHA>]

NOTE: If a project has a .gitlab/sast-ruleset.toml file committed, that local configuration takes precedence and the file from SAST_RULESET_GIT_REFERENCE isn't used.

The following example enables SAST and uses a shared ruleset customization file. In this example, the file is committed on the default branch of example-ruleset-project at the path .gitlab/sast-ruleset.toml.

include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"

See specify a private remote configuration example for advanced usage.

Troubleshooting remote configuration files

If remote configuration file doesn't seem to be applying customizations correctly, the causes can be:

1. Your repository has a local .gitlab/sast-ruleset.toml file.
   • By default, a local file is used if it's present, even if a remote configuration is set as a variable.
   • You can set the SECURE_ENABLE_LOCAL_CONFIGURATION CI/CD variable to false to ignore the local configuration file.
2. There is a problem with authentication.
   • To check whether this is the cause of the problem, try referencing a configuration file from a repository location that doesn't require authentication.

Schema

The top-level section

The top-level section contains one or more configuration sections, defined as TOML tables.

Configuration example:

[semgrep]
...

Avoid creating configuration sections that modify existing rules and build a custom ruleset, as the latter replaces predefined rules completely.

The [$analyzer] configuration section

The [$analyzer] section lets you customize the behavior of an analyzer. Valid properties differ based on the kind of configuration you're making.

interpolate

WARNING: To reduce the risk of leaking secrets, use this feature with caution.

The example below shows a configuration that uses the $GITURL environment variable to access a private repository. The variable contains a username and token (for example https://user:token@url), so they're not explicitly stored in the configuration file.

[semgrep]
  description = "My private Semgrep ruleset"
  interpolate = true

  [[semgrep.passthrough]]
    type  = "git"
    value = "$GITURL"
    ref = "main"

The [[$analyzer.ruleset]] section

The [[$analyzer.ruleset]] section targets and modifies a single predefined rule. You can define one to many of these sections per analyzer.

Configuration example:

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    ...

The [$analyzer.ruleset.identifier] section

The [$analyzer.ruleset.identifier] section defines the identifiers of the predefined rule that you wish to modify.

You can look up the correct values for type and value by viewing the gl-sast-report.json produced by the analyzer. You can download this file as a job artifact from the analyzer's CI job.

For example, the snippet below shows a finding from a semgrep rule with three identifiers. The type and value keys in the JSON object correspond to the values you should provide in this section.

...
  "vulnerabilities": [
    {
      "id": "7331a4b7093875f6eb9f6eb1755b30cc792e9fb3a08c9ce673fb0d2207d7c9c9",
      "category": "sast",
      "message": "Key Exchange without Entity Authentication",
      "description": "Audit the use of ssh.InsecureIgnoreHostKey\n",
      ...
      "identifiers": [
        {
          "type": "semgrep_id",
          "name": "gosec.G106-1",
          "value": "gosec.G106-1"
        },
        {
          "type": "cwe",
          "name": "CWE-322",
          "value": "322",
          "url": "https://cwe.mitre.org/data/definitions/322.html"
        },
        {
          "type": "gosec_rule_id",
          "name": "Gosec Rule ID G106",
          "value": "G106"
        }
      ]
    }
    ...
  ]
...

Configuration example:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1
    ...

The [$analyzer.ruleset.override] section

The [$analyzer.ruleset.override] section allows you to override attributes of a predefined rule.

NOTE: While message is populated by the analyzers, it has been deprecated in favor of name and description.

Configuration example:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.override]
      severity = "Critical"
      name = "Command injection"
    ...

The [[$analyzer.passthrough]] section

NOTE: Passthrough configurations are available for the Semgrep-based analyzer only.

The [[$analyzer.passthrough]] section allows you to build a custom configuration for an analyzer. You can define up to 20 of these sections per analyzer. Passthroughs are composed into a passthrough chain that evaluates into a complete configuration that replaces the predefined rules of the analyzer.

Passthroughs are evaluated in order. Passthroughs listed later in the chain have a higher precedence and can overwrite or append to data yielded by previous passthroughs (depending on the mode). This is useful for cases where you need to use or modify an existing configuration.

The size of the configuration generated by a single passthrough is limited to 10 MB.

Passthrough types

WARNING: When using the raw passthrough with a YAML snippet, it's recommended to format all indentation in the sast-ruleset.toml file as spaces. The YAML specification mandates spaces over tabs, and the analyzer fails to parse your custom ruleset unless the indentation is represented accordingly.

Examples

Disable predefined Advanced SAST rules

You can disable Advanced SAST rules or edit their metadata. The following example disables rules based on different criteria:

• A CWE identifier, which identifies an entire class of vulnerabilities.
• An Advanced SAST rule ID, which identifies a specific detection strategy used in Advanced SAST.
• An associated Semgrep rule ID, which is included in Advanced SAST findings for compatibility. This additional metadata allows findings to be automatically transitioned when both analyzers create similar findings in the same location.

These identifiers are shown in the vulnerability details of each vulnerability. You can also see each identifier and its associated type in the downloadable SAST report artifact.

[gitlab-advanced-sast]
  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "cwe"
      value = "89"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "gitlab-advanced-sast_id"
      value = "java-spring-csrf-unrestricted-requestmapping-atomic"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "semgrep_id"
      value = "java_cookie_rule-CookieHTTPOnly"

Disable predefined rules of other SAST analyzers

With the following custom ruleset configuration, the following rules are omitted from the report:

• semgrep rules with a semgrep_id of gosec.G106-1 or a cwe of 322.
• sobelow rules with a sobelow_rule_id of sql_injection.
• flawfinder rules with a flawfinder_func_name of memcpy.

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1"

  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "cwe"
      value = "322"

[sobelow]
  [[sobelow.ruleset]]
    disable = true
    [sobelow.ruleset.identifier]
      type = "sobelow_rule_id"
      value = "sql_injection"

[flawfinder]
  [[flawfinder.ruleset]]
    disable = true
    [flawfinder.ruleset.identifier]
      type = "flawfinder_func_name"
      value = "memcpy"

Override predefined rule metadata

With the following custom ruleset configuration, vulnerabilities found with semgrep with a type CWE and a value 322 have their severity overridden to Critical.

include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```0

### Build a custom configuration using a file passthrough for `semgrep`

With the following custom ruleset configuration, the predefined ruleset
of the `semgrep` analyzer is replaced with a custom ruleset contained in
a file called `my-semgrep-rules.yaml` in the repository being scanned.

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```1

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```2

### Build a custom configuration using a passthrough chain for `semgrep`

With the following custom ruleset configuration, the predefined ruleset
of the `semgrep` analyzer is replaced with a custom ruleset produced by
evaluating a chain of four passthroughs. Each passthrough produces a file
that's written to the `/sgrules` directory within the container. A
`timeout` of 60 seconds is set in case any Git remotes are unresponsive.

Different passthrough types are demonstrated in this example:

- Two `git` passthroughs, the first pulling `develop` branch from the
  `myrules` Git repository, and the second pulling revision `97f7686`
  from the `sast-rules` repository, and considering only files in the
  `go` subdirectory.
  - The `sast-rules` entry has a higher precedence because it appears later in
    the configuration.
  - If there's a filename collision between the two checkouts, files
    from the `sast-rules` repository overwrite files from the
    `myrules` repository.
- A `raw` passthrough, which writes its `value` to `/sgrules/insecure.yml`.
- A `url` passthrough, which fetches a configuration hosted at a URL and
  writes it to `/sgrules/gosec.yml`.

Afterwards, Semgrep is invoked with the final configuration located under
`/sgrules`.

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```3

### Configure the mode for passthroughs in a chain

You can choose how to handle filename conflicts that occur between
passthroughs in a chain. The default behavior is to overwrite
existing files with the same name, but you can choose `mode = append`
instead to append the content of later files onto earlier ones.

You can use the `append` mode for the `file`, `url`, and `raw`
passthrough types only.

With the following custom ruleset configuration, two `raw` passthroughs
are used to iteratively assemble the `/sgrules/my-rules.yml` file, which
is then provided to Semgrep as the ruleset. Each passthrough appends a
single rule to the ruleset. The first passthrough is responsible for
initialising the top-level `rules` object, according to the
[Semgrep rule syntax](https://semgrep.dev/docs/writing-rules/rule-syntax).

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```4

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```5

### Specify a private remote configuration

The following example [enables SAST](index.md#configure-sast-in-your-cicd-yaml) and uses a shared ruleset customization file. The file is:

- Downloaded from a private project that requires authentication, by using a [Group Access Token](../../group/settings/group_access_tokens.md) securely stored within a CI variable.
- Checked out at a specific Git commit SHA instead of the default branch.

See [group access tokens](../../group/settings/group_access_tokens.md#bot-users-for-groups) for how to find the username associated with a group token.

```yaml
include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"
```6

### Demo Projects

There are [demonstration projects](https://gitlab.com/gitlab-org/security-products/demos/SAST-analyzer-configurations) that illustrate some of these configuration options.

Many of these projects illustrate using remote rulesets to override or disable rules and are grouped together by which analyzer they are for.

There are also some video demonstrations walking through setting up remote rulesets:

- [IaC analyzer with a remote ruleset](https://youtu.be/VzJFyaKpA-8)