Syntax Reference

About 870 wordsAbout 3 min

Syntax Reference is the complete field-level reference for code_scan_config.yml.

When to use: when you need the exact meaning or accepted values of a field, for example to confirm how paths matches, the scope of include, or how to write Beta rules. If you just want scanning to work, read Quick start first.

.scanignore, files referenced by ignoreFrom, and paths use gitignore-style path rules:

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

`.scanignore` and `ignoreFrom`

You can configure root .scanignore alone; its rules apply to all scan capabilities.
When a capability configures ignoreFrom, it uses the specified file; other capabilities continue to use root .scanignore.
The two ignore files are not merged. paths, include, and rules can be used at the same time.

Basic structure

.cnb/security/code_scan_config.yml
include:
  - .cnb/security/checks/extra.yml

secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/secrets
    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: .cnb/security/scanignore/sca

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

Tips

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)

Tips

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: .cnb/security/scanignore/common
    paths:
      - "!secret-files/keep.go"
      - "vendor/**"

Field	Type	Description
`ignoreFrom`	string	Gitignore-style ignore file path, relative to the repo root. Replaces the `.scanignore` default for this capability only
`paths`	string[]	Additional gitignore-style path rules (up to 100). Appended and deduplicated (see note)

Note: ignoreFrom — the engine skips paths matched by the ignore file. paths — 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.

When ignoreFrom is not configured, root .scanignore is used if present.

Tips

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 path-rule array (OR) matching the finding path. Must be an array, even with one pattern
`severity`	string[]	Severity array (OR). See values below. Must be an array, even with one value

Example: paths can be ["**/testdata/**", "vendor/**"] to ignore test data and vendor directories.

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.

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: .cnb/security/scanignore/secrets
    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: .cnb/security/scanignore/sca

Next steps

Return to Quick start for more examples, or see Configuration file for include details.