diff --git a/content/en/security/code_security/guides/configuration.md b/content/en/security/code_security/guides/configuration.md index 92d339973fb..cf24e9c8064 100644 --- a/content/en/security/code_security/guides/configuration.md +++ b/content/en/security/code_security/guides/configuration.md @@ -25,11 +25,14 @@ The configuration file must begin with a `schema-version` key, followed by top-l | `v1.0` | SAST | | `v1.1` | SAST, SCA | | `v1.2` | SAST, SCA, IaC Security | +| `v1.3` | SAST, SCA, IaC Security | + +Use `schema-version: v1.3` for all new configurations. It supports the same products as `v1.2` and adds IaC configuration options such as per-rule path scoping, per-rule severity overrides, and platform filters. See [Infrastructure as Code (IaC) Security Configuration][3] for IaC-specific fields. The following example shows the top-level structure: ```yaml -schema-version: v1.2 +schema-version: v1.3 sast: # Static Code Analysis (SAST) configuration sca: @@ -78,7 +81,7 @@ For each field in a configuration, merge behavior depends on the field type: | Field type | Merge behavior | Example fields | |---|---|---| -| Lists | Concatenated, with duplicates removed | `use-rulesets`, `ignore-rulesets`, `ignore-rules`, `ignore-paths`, `only-paths` | +| Lists | Concatenated, with duplicates removed | `use-rulesets`, `ignore-rulesets`, `ignore-rules`, `ignore-paths`, `only-paths`, `ignore-platforms`, `only-platforms` | | Scalar values (strings, numbers, booleans) | The value from the highest-precedence configuration is used | `use-default-rulesets`, `use-gitignore`, `max-file-size-kb`, `category` | | Maps | Recursively merged | `ruleset-configs`, `rule-configs`, `arguments` | @@ -89,7 +92,7 @@ The following example shows how configurations are merged: #### Org-level ```yaml -schema-version: v1.2 +schema-version: v1.3 sast: use-default-rulesets: false use-rulesets: @@ -116,7 +119,7 @@ iac: #### Repo-level ```yaml -schema-version: v1.2 +schema-version: v1.3 sast: use-rulesets: - B @@ -145,7 +148,7 @@ iac: #### Merged result ```yaml -schema-version: v1.2 +schema-version: v1.3 sast: use-default-rulesets: false use-rulesets: diff --git a/content/en/security/code_security/iac_security/configuration.md b/content/en/security/code_security/iac_security/configuration.md index 2a1c7f70597..c0c5609b3b1 100644 --- a/content/en/security/code_security/iac_security/configuration.md +++ b/content/en/security/code_security/iac_security/configuration.md @@ -33,10 +33,12 @@ You can configure IaC Security using: The following configuration format applies to all configuration locations: org-level, repository-level, and repository-level (file). -The configuration file must begin with `schema-version: v1.2`, followed by an `iac` key containing the analysis configuration. The full structure is as follows: +The configuration file must begin with `schema-version: v1.3`, followed by an `iac` key containing the analysis configuration. + +The full structure is as follows: {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: # Do not run these rules. ignore-rules: @@ -68,6 +70,22 @@ iac: # Report only findings in these categories. only-categories: - "Encryption" + # Do not run rules from these platforms. + ignore-platforms: + - Dockerfile + # Only run rules from these platforms. + only-platforms: + - Terraform + - Kubernetes + # Per-rule configurations. + rule-configs: + terraform-aws-s3-bucket-without-encryption: + ignore-paths: + - "test/" + severity: low + kubernetes-deployment-without-resource-limits: + only-paths: + - "k8s/production/" {{< /code-block >}} The `iac` key supports the following fields: @@ -75,8 +93,9 @@ The `iac` key supports the following fields: | **Property** | **Type** | **Description** | | --- | --- | --- | | `ignore-rules` | Array | A list of rule IDs to ignore. | -| `use-rules` | Array | A list of rule IDs to run. If this field is set, rules not listed are ignored. | -| `global-config` | Object | Global settings for the repository. | +| `use-rules` | Array | A list of rule IDs to run. If specified, _only_ these rules run. `ignore-rules` takes precedence over `use-rules`: a rule in both arrays is ignored. | +| `global-config` | Object | Global settings for the IaC scanner. | +| `rule-configs` | Object | Per-rule configurations. Keys are rule IDs. | ## Rule configuration @@ -86,7 +105,7 @@ To modify which rules run: - **Disable specific rules**: List them under `ignore-rules` {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: ignore-rules: - A @@ -94,7 +113,7 @@ iac: {{< /code-block >}} {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: use-rules: - A @@ -110,10 +129,12 @@ The `global-config` object controls repository-wide settings: | --- | --- | --- | | `only-paths` | Array | File paths or glob patterns. Only matching files are analyzed. | | `ignore-paths` | Array | File paths or glob patterns to exclude. Matching files are not analyzed. | -| `only-severities` | Array | Severity levels to report. Findings with other severities are ignored. | +| `only-severities` | Array | Severity levels to report. Findings with other severities are not reported. | | `ignore-severities` | Array | Severity levels to ignore. | -| `only-categories` | Array | Categories to report. Findings in other categories are ignored. | +| `only-categories` | Array | Categories to report. Findings in other categories are not reported. | | `ignore-categories` | Array | Categories to ignore. | +| `ignore-platforms` | Array | Platforms to skip. Rules from these platforms are not applied. | +| `only-platforms` | Array | Platforms to scan. Rules from other platforms are not applied. | ### Severities @@ -128,7 +149,7 @@ Use `ignore-severities` to ignore findings based on severity level. Use `only-se - `info` {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: global-config: ignore-severities: @@ -141,7 +162,7 @@ iac: Use `ignore-paths` to exclude specific files or directories from scanning. Use `only-paths` to scan only specific files or directories. These options support glob patterns. {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: global-config: ignore-paths: @@ -172,7 +193,7 @@ Use `ignore-categories` to ignore findings in specific categories. Use `only-cat - `Supply-Chain` {{< code-block lang="yaml" >}} -schema-version: v1.2 +schema-version: v1.3 iac: global-config: ignore-categories: @@ -180,6 +201,75 @@ iac: - "Best Practices" {{< /code-block >}} +### Platforms + +Use `ignore-platforms` to skip specific platforms. Use `only-platforms` to restrict scanning to specific platforms. + +**Possible values:** + +- `Ansible` +- `CICD` +- `CloudFormation` +- `Dockerfile` +- `Kubernetes` +- `Terraform` + +{{< code-block lang="yaml" >}} +schema-version: v1.3 +iac: + global-config: + only-platforms: + - Terraform + - Kubernetes +{{< /code-block >}} + +## Per-rule configuration + +Use `rule-configs` to configure individual rules. + +Each key under `rule-configs` is a rule ID. The following properties are supported per rule: + +| **Property** | **Type** | **Description** | +| --- | --- | --- | +| `only-paths` | Array | File paths or glob patterns. The rule is applied only to files matching these patterns. | +| `ignore-paths` | Array | File paths or glob patterns to exclude. The rule is not applied to files matching these patterns. | +| `severity` | String | Overrides the severity of findings generated by this rule. Accepted values: `critical`, `high`, `medium`, `low`, `info`. | + +### Per-rule path scoping + +Exclude a rule from certain paths, or restrict it to specific paths: + +{{< code-block lang="yaml" >}} +schema-version: v1.3 +iac: + rule-configs: + terraform-aws-s3-bucket-without-encryption: + # Do not apply this rule in test directories. + ignore-paths: + - "test/" + - "**/testdata/" + kubernetes-deployment-without-resource-limits: + # Apply this rule only in production manifests. + only-paths: + - "k8s/production/" +{{< /code-block >}} + +Path patterns support glob syntax (`*`, `**`, `?`). Paths are relative to the repository root. + +### Per-rule severity override + +Change the severity of findings generated by a specific rule: + +{{< code-block lang="yaml" >}} +schema-version: v1.3 +iac: + rule-configs: + terraform-aws-s3-bucket-without-encryption: + severity: low +{{< /code-block >}} + +This severity applies to all findings generated by that rule. + ## Legacy configuration IaC Security previously used a different configuration file (`dd-iac-scan.config`) and schema. This schema is deprecated and does not receive new updates, but it is [documented][2] in the `datadog-iac-scanner` repository.