This chapter is the complete field-level reference for code_scan_config.yml. For first-time configuration, read Quick start first.

All paths use gitignore-style glob syntax by default:

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

Basic structure

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

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

Security capability

Each capability block supports the following child keys:

<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

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

<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

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

.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 for more examples, or see Configuration file for include details.

Previous pageConfiguration File