---
url: /en/security/syntax-reference.md
description: >
  Complete field-level reference for code_scan_config.yml, including top-level
  fields, include, scan configuration, and Beta rules syntax.
---
This chapter is the complete field-level reference for `code_scan_config.yml`. For first-time configuration,
read [Quick start](./quickstart.md) first.

All paths use **gitignore-style glob syntax** by default:

* `**` crosses multiple directory levels
* The `!` prefix indicates negation, meaning forced inclusion

## Basic structure

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - .cnb/security/checks/extra.yml

secrets:
  scan:
    ignoreFrom: .scanignore
    paths:
      - "!secret-files/keep.go"
  rules:
    - name: ignore-test-noise
      when:
        paths: ["**/testdata/**"]
        severity: ["low", "medium"]
      then:
        ignore: true
        reason: "Ignore low/medium-severity findings under the testdata directory"

software-composition-analysis:
  scan:
    ignoreFrom: .scanignore
```

## Top-level fields

| Field | Type | Description |
|---|---|---|
| `include` | Array | Introduces subfiles. See [include field](#include-field) |
| `secrets` | Security capability | Secret scanning configuration |
| `software-composition-analysis` | Security capability | Open source component scanning configuration |

> The table above lists the currently public top-level fields. Unknown keys are treated as errors. Use the `validate`
> result as the source of truth.

## include field

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - <string path>
  - path: <string path>
    ignoreError: <true|false> # default false
```

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | string | ✅ | Subfile path relative to the repository root |
| `ignoreError` | bool | | If `true`, missing files do not report errors. Other errors are still reported |

For more semantics, including merge rules and security restrictions, see
[Configuration file · include](./config-file.md).

## Security capability

Each capability block supports the following child keys:

```yaml
<capability>:
  scan: { ... } # scan configuration
  rules: [...] # handling rules (Beta)
```

> The table above lists the currently public child keys. Unknown keys are treated as errors. Use the `validate` result
> as the source of truth.

### scan configuration

```yaml
<capability>:
  scan:
    ignoreFrom: .scanignore
    paths:
      - "!secret-files/keep.go"
      - "vendor/**"
```

| Field | Type | Description |
|---|---|---|
| `ignoreFrom` | string | Path to a gitignore-style ignore file, relative to the repository root. The engine skips paths matched by it. |
| `paths` | string\[] | Additional list of gitignore patterns. Up to **100** items. Appended and deduplicated across included files. |

**Relationship between `ignoreFrom` and `paths`**: both are eventually merged into one pattern set. Patterns in
`paths` that start with `!` can negate `ignoreFrom` and force certain paths back into scanning.

**Default behavior**: when `scan`, `ignoreFrom`, or `paths` is not explicitly configured, the corresponding capability
uses the platform built-in default scan scope. Configure `ignoreFrom` explicitly only when you need a custom
ignore file.

> **Tip**: once `ignoreFrom` is explicitly declared, the target file **must exist**, otherwise an error is reported.
> If you want to use it when it exists and skip it when it does not, split this part into an `include` file with
> `ignoreError: true`.

### rules (Beta)

> ⚠️ **Beta feature**: the `rules` block and its `when` / `then` fields are Beta. Field names and matching semantics
> may be adjusted in later versions. Use it cautiously in production configuration and follow the changelog.

Rules for handling a single scan result, or finding. When all conditions in `when` are satisfied, the action
specified by `then` is applied.

```yaml
<capability>:
  rules:
    - name: ignore-test-low-severity
      when:
        paths: ["**/test/**"]
        severity: ["low"]
      then:
        ignore: true
        reason: "Low-severity finding in test code, known not to reach production"
```

#### Rule structure

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | ✅ | Rule identifier, which appears in audit logs and decision results |
| `when` | object | ✅ | Match conditions |
| `then` | object | ✅ | Action after a match |

#### `when` match conditions

Multiple fields inside `when` have an **AND** relationship. All of them must be satisfied to match. At least one
condition is required.

| Field | Type | Description |
|---|---|---|
| `paths` | string\[] | Gitignore-style glob array (OR), matching the finding path, for example `["**/testdata/**", "vendor/**"]`. **Must be an array**, even with only one pattern |
| `severity` | string\[] | Severity array (OR). See allowed values below. **Must be an array**, even with only one value |

> Severity enum values vary by capability. By default, they include `low`, `medium`, and `high`. The SCA capability
> additionally supports `critical`.

#### `then` action

```yaml
then:
  ignore: true
  reason: "Reason description"
```

| Field | Type | Description |
|---|---|---|
| `ignore` | bool | Suppresses or ignores this finding when set to `true` |
| `reason` | string | Human-readable reason. **Required when `ignore: true`** |

#### Evaluation order for multiple rules

Multiple rules under the same capability are evaluated one by one in declaration order. **The first matched rule takes
effect**, and later rules are not evaluated.

> **Tip**: put more specific rules earlier and broader rules later.

## Complete example

```yaml title=".cnb/security/code_scan_config.yml"
include:
  - .cnb/security/checks/extra.yml
  - path: .cnb/security/checks/local.yml # optional local file
    ignoreError: true

secrets:
  scan:
    ignoreFrom: .scanignore
    paths:
      - "!secret-files/keep.go"
  rules:
    - name: ignore-test-noise # Beta
      when:
        paths: ["**/testdata/**"]
        severity: ["low", "medium"]
      then:
        ignore: true
        reason: "Ignore low/medium-severity findings under the testdata directory"

software-composition-analysis:
  scan:
    ignoreFrom: .scanignore
```

## Next steps

Return to [Quick start](./quickstart.md) for more examples, or see [Configuration file](./config-file.md) for include
details.