Merge branch 'russell/split-customize-rulesets' into 'master'

Move SAST customize rulesets doc to its own page

See merge request !92881

doc/user/application_security/sast/analyzers.md

@@ -47,7 +47,7 @@ For an analyzer to be considered Generally Available, it is expected to minimall
 support the following features:
 
 - [Customizable configuration](index.md#available-cicd-variables)
-- [Customizable rulesets](index.md#customize-rulesets)
+- [Customizable rulesets](customize_rulesets.md#customize-rulesets)
 - [Scan projects](index.md#supported-languages-and-frameworks)
 - [Multi-project support](index.md#multi-project-support)
 - [Offline support](index.md#running-sast-in-an-offline-environment)

doc/user/application_security/sast/customize_rulesets.md

+---
+stage: Secure
+group: Static Analysis
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Customize rulesets **(ULTIMATE)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5.
+> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for
+>   passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6.
+> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8.
+
+You can customize the default scanning rules provided by our SAST analyzers.
+Ruleset customization supports the following that can be used
+simultaneously:
+
+- [Disabling predefined rules](#disable-predefined-analyzer-rules). Available for all analyzers.
+- [Overriding predefined rules](#override-predefined-analyzer-rules). Available for all analyzers.
+- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`.
+
+To customize the default scanning rules, create a file containing custom rules. These rules
+are passed through to the analyzer's underlying scanner tools.
+
+To create a custom ruleset:
+
+1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist.
+1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory.
+
+## Disable predefined analyzer rules
+
+To disable analyzer rules:
+
+1. Set the `disabled` flag to `true` in the context of a `ruleset` section
+
+1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has:
+
+- a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
+- a `value` field, to name the rule to be disabled.
+
+### Example: Disable predefined rules of SAST analyzers
+
+In the following example, the disabled rules are assigned to `eslint`
+and `sobelow` by matching the `type` and `value` of identifiers:
+
+```toml
+[eslint]
+  [[eslint.ruleset]]
+    disable = true
+    [eslint.ruleset.identifier]
+      type = "eslint_rule_id"
+      value = "security/detect-object-injection"
+
+  [[eslint.ruleset]]
+    disable = true
+    [eslint.ruleset.identifier]
+      type = "cwe"
+      value = "185"
+
+[sobelow]
+  [[sobelow.ruleset]]
+    disable = true
+    [sobelow.ruleset.identifier]
+      type = "sobelow_rule_id"
+      value = "sql_injection"
+```
+
+Those vulnerabilities containing the provided type and value are now disabled, meaning
+they won't be displayed in Merge Request nor the Vulnerability Report.
+
+## Override predefined analyzer rules
+
+To override analyzer rules:
+
+1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has:
+
+   - a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
+   - a `value` field, to name the rule to be overridden.
+
+1. In the `ruleset.override` context of a `ruleset` section,
+   provide the keys to override. Any combination of keys can be
+   overridden. Valid keys are:
+
+   - description
+   - message
+   - name
+   - severity (valid options are: Critical, High, Medium, Low, Unknown, Info)
+
+### Example: Override predefined rules of SAST analyzers
+
+Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](index.md#reports-json-format):
+
+```json
+"identifiers": [
+        {
+          "type": "gosec_rule_id",
+          "name": "Gosec Rule ID G307",
+          "value": "G307"
+        },
+        {
+          "type": "CWE",
+          "name": "CWE-703",
+          "value": "703",
+          "url": "https://cwe.mitre.org/data/definitions/703.html"
+        }
+      ]
+```
+
+In the following example, rules from `gosec` are matched by the `type`
+and `value` of identifiers and then overridden:
+
+```toml
+[gosec]
+  [[gosec.ruleset]]
+    [gosec.ruleset.identifier]
+        type = "CWE"
+        value = "703"
+    [gosec.ruleset.override]
+      severity = "Critical"
+```
+
+If a vulnerability is found with a type `CWE` with a value of `703` then
+the vulnerability severity is overwritten to `Critical`.
+
+## Synthesize a custom configuration
+
+To create a custom configuration, you can use passthrough chains.
+
+A passthrough is a single step in a passthrough chain. The passthrough is evaluated
+in a sequence to incrementally build a configuration. The configuration is then
+passed to the target analyzer.
+
+A configuration section for an analyzer has the following
+parameters:
+
+| Parameter     | Explanation |
+| ------------- | ------ |
+| `description` | Description about the analyzer configuration section. |
+| `targetdir`   | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. |
+| `validate`    | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. |
+| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. |
+| `timeout`     | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. |
+
+A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20.
+There are several types of passthroughs:
+
+| Type   | Description |
+| ------ | ------ |
+| `file` | Use a file that is already available in the Git repository. |
+| `raw`  | Provide the configuration inline. |
+| `git`  | Pull the configuration from a remote Git repository. |
+| `url`  | Fetch the analyzer configuration through HTTP. |
+
+If multiple passthrough sections are defined in a passthrough chain, their
+position in the chain defines the order in which they are evaluated.
+
+- Passthroughs listed later in the chain sequence have a higher precedence.
+- Passthroughs with a higher precedence overwrite (default) and append data
+  yielded by previous passthroughs. This is useful for cases where you need to
+  use or modify an existing configuration.
+
+Configure a passthrough these parameters:
+
+| Parameter     | Explanation |
+| ------------ | ----------- |
+| `type`       | One of `file`, `raw`, `git` or `url`. |
+| `target`     | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. |
+| `mode`       | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. |
+| `ref`        | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. |
+| `subdir`     | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. |
+| `value`      | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. |
+| `validator`  | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. |
+
+The amount of data generated by a single passthrough is limited to 1MB.
+
+## Passthrough configuration examples
+
+### Raw passthrough for nodejs-scan
+
+Define a custom analyzer configuration. In this example, customized rules are
+defined for the `nodejs-scan` scanner:
+
+```toml
+[nodejs-scan]
+  description = 'custom ruleset for nodejs-scan'
+
+  [[nodejs-scan.passthrough]]
+    type  = "raw"
+    value = '''
+- nodejs-extensions:
+  - .js
+
+  template-extensions:
+  - .new
+  - .hbs
+  - ''
+
+  ignore-filenames:
+- skip.js
+
+  ignore-paths:
+  - __MACOSX
+  - skip_dir
+  - node_modules
+
+  ignore-extensions:
+  - .hbs
+
+  ignore-rules:
+  - regex_injection_dos
+  - pug_jade_template
+  - express_xss
+
+'''
+```
+
+### File passthrough for Gosec
+
+Provide the name of the file containing a custom analyzer configuration. In
+this example, customized rules for the `gosec` scanner are contained in the
+file `gosec-config.json`:
+
+```toml
+[gosec]
+  description = 'custom ruleset for gosec'
+
+  [[gosec.passthrough]]
+    type  = "file"
+    value = "gosec-config.json"
+```
+
+### Passthrough chain for Semgrep
+
+In the below example, we generate a custom configuration under the `/sgrules`
+target directory with a total `timeout` of 60 seconds.
+
+Several passthrouh types generate a configuration for the target analyzer:
+
+- Two `git` passthrough sections pull the head of branch
+  `refs/remotes/origin/test` from the `myrules` Git repository, and revision
+  `97f7686` from the `sast-rules` Git repository. From the `sast-rules` Git
+  repository, only data from the `go` subdirectory is considered.
+  - The `sast-rules` entry has a higher precedence because it appears later in
+    the configuration.
+  - If there is a filename collision between files in both repositories, files
+    from the `sast` repository overwrite files from the `myrules` repository,
+    as `sast-rules` has higher precedence.
+- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The
+  full path is `/sgrules/insecure.yml`.
+- The `url` entry fetches a configuration made available through a URL and
+  stores it in the `/sgrules/gosec.yml` file.
+
+Afterwards, Semgrep is invoked with the final configuration located under
+`/sgrules`.
+
+```toml
+[semgrep]
+  description = 'semgrep custom rules configuration'
+  targetdir = "/sgrules"
+  timeout = 60
+
+  [[semgrep.passthrough]]
+    type  = "git"
+    value = "https://gitlab.com/user/myrules.git"
+    ref = "refs/remotes/origin/test"
+
+  [[semgrep.passthrough]]
+    type  = "git"
+    value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git"
+    ref = "97f7686db058e2141c0806a477c1e04835c4f395"
+    subdir = "go"
+
+  [[semgrep.passthrough]]
+    type  = "raw"
+    target = "insecure.yml"
+    value = """
+rules:
+- id: "insecure"
+  patterns:
+  - pattern: "func insecure() {...}"
+  message: |
+    Insecure function insecure detected
+  metadata:
+    cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor"
+  severity: "ERROR"
+  languages:
+  - "go"
+    """
+
+  [[semgrep.passthrough]]
+    type  = "url"
+    value = "https://semgrep.dev/c/p/gosec"
+    target = "gosec.yml"
+```
+
+### Interpolation
+
+The code snippet below shows an example configuration that uses an environment
+variable `$GITURL` to access a private repositories with a Git URL. The variable contains
+a username and token in the `value` field (for example `https://user:token@url`).
+It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution.
+
+```toml
+[semgrep]
+  description = 'semgrep custom rules configuration'
+  targetdir = "/sgrules"
+  interpolate = true
+
+  [[semgrep.passthrough]]
+    type  = "git"
+    value = "$GITURL"
+    ref = "refs/remotes/origin/main"
+```
+
+### Configure the append mode for passthroughs
+
+To append data to previous passthroughs, use the `append` mode for the
+passthrough types `file`, `url`, and `raw`.
+
+Passthroughs in `override` mode overwrite files
+created when preceding passthroughs in the chain find a naming
+collision. If `mode` is set to `append`, a passthrough appends data to the
+files created by its predecessors instead of overwriting.
+
+In the below Semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are:
+
+- `insecure`
+- `secret`
+
+These rules add a search pattern to the analyzer and extends Semgrep capabilities.
+
+For passthrough chains we recommend that you enable validation. To enable validation,
+you can either:
+
+- set `validate` to `true`
+
+- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`.
+
+```toml
+[semgrep]
+  description = 'semgrep custom rules configuration'
+  targetdir = "/sgrules"
+  validate = true
+
+  [[semgrep.passthrough]]
+    type  = "raw"
+    target = "insecure.yml"
+    value = """
+rules:
+- id: "insecure"
+  patterns:
+  - pattern: "func insecure() {...}"
+  message: |
+    Insecure function insecure detected
+  metadata:
+    cwe: "...
+  severity: "ERROR"
+  languages:
+  - "go"
+"""
+
+  [[semgrep.passthrough]]
+    type  = "raw"
+    mode  = "append"
+    target = "insecure.yml"
+    value = """
+- id: "secret"
+  patterns:
+  - pattern-either:
+    - pattern: "$MASK = \"...\""
+  - metavariable-regex:
+      metavariable: "$MASK"
+      regex: "(password|pass|passwd|pwd|secret|token)"
+  message: |
+    Use of Hard-coded Password
+    cwe: "..."
+  severity: "ERROR"
+  languages:
+  - "go"
+"""
+```

doc/user/application_security/sast/index.md

@@ -176,18 +176,18 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi
 Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/),
 as shown in the following table:
 
-| Capability                                                      | In Free & Premium   | In Ultimate        |
-|:----------------------------------------------------------------|:--------------------|:-------------------|
-| [Configure SAST scanners](#configuration)                       | **{check-circle}**  | **{check-circle}** |
-| [Customize SAST settings](#available-cicd-variables)            | **{check-circle}**  | **{check-circle}** |
-| Download [JSON Report](#reports-json-format)                    | **{check-circle}**  | **{check-circle}** |
-| See new findings in merge request widget                        | **{dotted-circle}** | **{check-circle}** |
-| [Manage vulnerabilities](../vulnerabilities/index.md)           | **{dotted-circle}** | **{check-circle}** |
-| [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** |
-| [Configure SAST in the UI](#configure-sast-in-the-ui)           | **{dotted-circle}** | **{check-circle}** |
-| [Customize SAST rulesets](#customize-rulesets)                  | **{dotted-circle}** | **{check-circle}** |
-| [Detect False Positives](#false-positive-detection)             | **{dotted-circle}** | **{check-circle}** |
-| [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** |
+| Capability                                                        | In Free & Premium   | In Ultimate        |
+|:---------------------------------------------------------------- -|:--------------------|:-------------------|
+| [Configure SAST scanners](#configuration)                         | **{check-circle}**  | **{check-circle}** |
+| [Customize SAST settings](#available-cicd-variables)              | **{check-circle}**  | **{check-circle}** |
+| Download [JSON Report](#reports-json-format)                      | **{check-circle}**  | **{check-circle}** |
+| See new findings in merge request widget                          | **{dotted-circle}** | **{check-circle}** |
+| [Manage vulnerabilities](../vulnerabilities/index.md)             | **{dotted-circle}** | **{check-circle}** |
+| [Access the Security Dashboard](../security_dashboard/index.md)   | **{dotted-circle}** | **{check-circle}** |
+| [Configure SAST in the UI](#configure-sast-in-the-ui)             | **{dotted-circle}** | **{check-circle}** |
+| [Customize SAST rulesets](customize_rulesets.md)                  | **{dotted-circle}** | **{check-circle}** |
+| [Detect False Positives](#false-positive-detection)               | **{dotted-circle}** | **{check-circle}** |
+| [Track moved vulnerabilities](#advanced-vulnerability-tracking)   | **{dotted-circle}** | **{check-circle}** |
 
 ## Contribute your scanner
 
@@ -320,382 +320,6 @@ brakeman-sast:
     SAST_ANALYZER_IMAGE_TAG: "2.21.1"
 ```
 
-### Customize rulesets **(ULTIMATE)**
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5.
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for
->   passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6.
-> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8.
-
-You can customize the default scanning rules provided by our SAST analyzers.
-Ruleset customization supports the following that can be used
-simultaneously:
-
-- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). Available for all analyzers.
-- [Overriding predefined rules](index.md#override-predefined-analyzer-rules). Available for all analyzers.
-- Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`.
-
-To customize the default scanning rules, create a file containing custom rules. These rules
-are passed through to the analyzer's underlying scanner tools.
-
-To create a custom ruleset:
-
-1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist.
-1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory.
-
-#### Disable predefined analyzer rules
-
-To disable analyzer rules:
-
-1. Set the `disabled` flag to `true` in the context of a `ruleset` section
-
-1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has:
-
-- a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
-- a `value` field, to name the rule to be disabled.
-
-##### Example: Disable predefined rules of SAST analyzers
-
-In the following example, the disabled rules are assigned to `eslint`
-and `sobelow` by matching the `type` and `value` of identifiers:
-
-```toml
-[eslint]
-  [[eslint.ruleset]]
-    disable = true
-    [eslint.ruleset.identifier]
-      type = "eslint_rule_id"
-      value = "security/detect-object-injection"
-
-  [[eslint.ruleset]]
-    disable = true
-    [eslint.ruleset.identifier]
-      type = "cwe"
-      value = "185"
-
-[sobelow]
-  [[sobelow.ruleset]]
-    disable = true
-    [sobelow.ruleset.identifier]
-      type = "sobelow_rule_id"
-      value = "sql_injection"
-```
-
-Those vulnerabilities containing the provided type and value are now disabled, meaning
-they won't be displayed in Merge Request nor the Vulnerability Report.
-
-#### Override predefined analyzer rules
-
-To override analyzer rules:
-
-1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has:
-
-   - a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
-   - a `value` field, to name the rule to be overridden.
-
-1. In the `ruleset.override` context of a `ruleset` section,
-   provide the keys to override. Any combination of keys can be
-   overridden. Valid keys are:
-
-   - description
-   - message
-   - name
-   - severity (valid options are: Critical, High, Medium, Low, Unknown, Info)
-
-##### Example: Override predefined rules of SAST analyzers
-
-Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](#reports-json-format):
-
-```json
-"identifiers": [
-        {
-          "type": "gosec_rule_id",
-          "name": "Gosec Rule ID G307",
-          "value": "G307"
-        },
-        {
-          "type": "CWE",
-          "name": "CWE-703",
-          "value": "703",
-          "url": "https://cwe.mitre.org/data/definitions/703.html"
-        }
-      ]
-```
-
-In the following example, rules from `gosec` are matched by the `type`
-and `value` of identifiers and then overridden:
-
-```toml
-[gosec]
-  [[gosec.ruleset]]
-    [gosec.ruleset.identifier]
-        type = "CWE"
-        value = "703"
-    [gosec.ruleset.override]
-      severity = "Critical"
-```
-
-If a vulnerability is found with a type `CWE` with a value of `703` then
-the vulnerability severity is overwritten to `Critical`.
-
-#### Synthesize a custom configuration
-
-To create a custom configuration, you can use passthrough chains.
-
-A passthrough is a single step in a passthrough chain. The passthrough is evaluated
-in a sequence to incrementally build a configuration. The configuration is then
-passed to the target analyzer.
-
-A configuration section for an analyzer has the following
-parameters:
-
-| Parameter     | Explanation |
-| ------------- | ------ |
-| `description` | Description about the analyzer configuration section. |
-| `targetdir`   | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. |
-| `validate`    | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. |
-| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. |
-| `timeout`     | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. |
-
-A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20.
-There are several types of passthroughs:
-
-| Type   | Description |
-| ------ | ------ |
-| `file` | Use a file that is already available in the Git repository. |
-| `raw`  | Provide the configuration inline. |
-| `git`  | Pull the configuration from a remote Git repository. |
-| `url`  | Fetch the analyzer configuration through HTTP. |
-
-If multiple passthrough sections are defined in a passthrough chain, their
-position in the chain defines the order in which they are evaluated.
-
-- Passthroughs listed later in the chain sequence have a higher precedence.
-- Passthroughs with a higher precedence overwrite (default) and append data
-  yielded by previous passthroughs. This is useful for cases where you need to
-  use or modify an existing configuration.
-
-Configure a passthrough these parameters:
-
-| Parameter     | Explanation |
-| ------------ | ----------- |
-| `type`       | One of `file`, `raw`, `git` or `url`. |
-| `target`     | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. |
-| `mode`       | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. |
-| `ref`        | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. |
-| `subdir`     | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. |
-| `value`      | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. |
-| `validator`  | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. |
-
-The amount of data generated by a single passthrough is limited to 1MB.
-
-#### Passthrough configuration examples
-
-##### Raw passthrough for nodejs-scan
-
-Define a custom analyzer configuration. In this example, customized rules are
-defined for the `nodejs-scan` scanner:
-
-```toml
-[nodejs-scan]
-  description = 'custom ruleset for nodejs-scan'
-
-  [[nodejs-scan.passthrough]]
-    type  = "raw"
-    value = '''
-- nodejs-extensions:
-  - .js
-
-  template-extensions:
-  - .new
-  - .hbs
-  - ''
-
-  ignore-filenames:
-- skip.js
-
-  ignore-paths:
-  - __MACOSX
-  - skip_dir
-  - node_modules
-
-  ignore-extensions:
-  - .hbs
-
-  ignore-rules:
-  - regex_injection_dos
-  - pug_jade_template
-  - express_xss
-
-'''
-```
-
-##### File passthrough for Gosec
-
-Provide the name of the file containing a custom analyzer configuration. In
-this example, customized rules for the `gosec` scanner are contained in the
-file `gosec-config.json`:
-
-```toml
-[gosec]
-  description = 'custom ruleset for gosec'
-
-  [[gosec.passthrough]]
-    type  = "file"
-    value = "gosec-config.json"
-```
-
-##### Passthrough chain for Semgrep
-
-In the below example, we generate a custom configuration under the `/sgrules`
-target directory with a total `timeout` of 60 seconds.
-
-Several passthrouh types generate a configuration for the target analyzer:
-
-- Two `git` passthrough sections pull the head of branch
-  `refs/remotes/origin/test` from the `myrules` Git repository, and revision
-  `97f7686` from the `sast-rules` Git repository. From the `sast-rules` Git
-  repository, only data from the `go` subdirectory is considered.
-  - The `sast-rules` entry has a higher precedence because it appears later in
-    the configuration.
-  - If there is a filename collision between files in both repositories, files
-    from the `sast` repository overwrite files from the `myrules` repository,
-    as `sast-rules` has higher precedence.
-- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The
-  full path is `/sgrules/insecure.yml`.
-- The `url` entry fetches a configuration made available through a URL and
-  stores it in the `/sgrules/gosec.yml` file.
-
-Afterwards, Semgrep is invoked with the final configuration located under
-`/sgrules`.
-
-```toml
-[semgrep]
-  description = 'semgrep custom rules configuration'
-  targetdir = "/sgrules"
-  timeout = 60
-
-  [[semgrep.passthrough]]
-    type  = "git"
-    value = "https://gitlab.com/user/myrules.git"
-    ref = "refs/remotes/origin/test"
-
-  [[semgrep.passthrough]]
-    type  = "git"
-    value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git"
-    ref = "97f7686db058e2141c0806a477c1e04835c4f395"
-    subdir = "go"
-
-  [[semgrep.passthrough]]
-    type  = "raw"
-    target = "insecure.yml"
-    value = """
-rules:
-- id: "insecure"
-  patterns:
-  - pattern: "func insecure() {...}"
-  message: |
-    Insecure function insecure detected
-  metadata:
-    cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor"
-  severity: "ERROR"
-  languages:
-  - "go"
-    """
-
-  [[semgrep.passthrough]]
-    type  = "url"
-    value = "https://semgrep.dev/c/p/gosec"
-    target = "gosec.yml"
-```
-
-##### Interpolation
-
-The code snippet below shows an example configuration that uses an environment
-variable `$GITURL` to access a private repositories with a Git URL. The variable contains
-a username and token in the `value` field (for example `https://user:token@url`).
-It does not explicitly store credentials in the configuration file. To reduce the risk of leaking secrets through created paths and files, use this feature with caution.
-
-```toml
-[semgrep]
-  description = 'semgrep custom rules configuration'
-  targetdir = "/sgrules"
-  interpolate = true
-
-  [[semgrep.passthrough]]
-    type  = "git"
-    value = "$GITURL"
-    ref = "refs/remotes/origin/main"
-```
-
-##### Configure the append mode for passthroughs
-
-To append data to previous passthroughs, use the `append` mode for the
-passthrough types `file`, `url`, and `raw`.
-
-Passthroughs in `override` mode overwrite files
-created when preceding passthroughs in the chain find a naming
-collision. If `mode` is set to `append`, a passthrough appends data to the
-files created by its predecessors instead of overwriting.
-
-In the below Semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are:
-
-- `insecure`
-- `secret`
-
-These rules add a search pattern to the analyzer and extends Semgrep capabilities.
-
-For passthrough chains we recommend that you enable validation. To enable validation,
-you can either:
-
-- set `validate` to `true`
-
-- set a passthrough `validator` to `xml`, `json`, `yaml`, or `toml`.
-
-```toml
-[semgrep]
-  description = 'semgrep custom rules configuration'
-  targetdir = "/sgrules"
-  validate = true
-
-  [[semgrep.passthrough]]
-    type  = "raw"
-    target = "insecure.yml"
-    value = """
-rules:
-- id: "insecure"
-  patterns:
-  - pattern: "func insecure() {...}"
-  message: |
-    Insecure function insecure detected
-  metadata:
-    cwe: "...
-  severity: "ERROR"
-  languages:
-  - "go"
-"""
-
-  [[semgrep.passthrough]]
-    type  = "raw"
-    mode  = "append"
-    target = "insecure.yml"
-    value = """
-- id: "secret"
-  patterns:
-  - pattern-either:
-    - pattern: "$MASK = \"...\""
-  - metavariable-regex:
-      metavariable: "$MASK"
-      regex: "(password|pass|passwd|pwd|secret|token)"
-  message: |
-    Use of Hard-coded Password
-    cwe: "..."
-  severity: "ERROR"
-  languages:
-  - "go"
-"""
-```
-
 ### False Positive Detection **(ULTIMATE)**
 
 > Introduced in GitLab 14.2.

doc/user/application_security/secret_detection/index.md

@@ -224,9 +224,9 @@ You can customize the default secret detection rules provided with GitLab.
 Ruleset customization supports the following capabilities that can be used
 simultaneously:
 
-- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules).
-- [Overriding predefined rules](index.md#override-predefined-analyzer-rules).
-- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration).
+- [Disabling predefined rules](#disable-predefined-analyzer-rules).
+- [Overriding predefined rules](#override-predefined-analyzer-rules).
+- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](#synthesize-a-custom-configuration).
 
 Customization allows replacing the default secret detection rules with rules that you define.
 
@@ -334,7 +334,7 @@ To create a custom configuration, you can use passthrough chains.
      ```
 
 Passthroughs can also be chained to build more complex configurations.
-For more details, see [SAST Customize ruleset section](../sast/index.md#customize-rulesets).
+For more details, see [SAST Customize ruleset section](../sast/customize_rulesets.md).
 
 ### Logging level