Configuration File

About 844 wordsAbout 3 min

This chapter describes the overall structure, file location, and how to split configuration with include.

File location

File	Location	Required
`code_scan_config.yml`	`<repo-root>/.cnb/security/code_scan_config.yml`	No
`.scanignore`	Repository root	No
Ignore file referenced by `ignoreFrom`	Any path in the repository	No
`include` subfile	Any path in the repository	No

`.scanignore` and `ignoreFrom`

Both are optional. If neither is configured, the platform uses its default scan scope.

You can configure root .scanignore alone; its rules apply to all security scan capabilities.
When a capability configures scan.ignoreFrom, it uses the specified file; other capabilities continue to use root .scanignore.
The file specified by ignoreFrom is not merged with root .scanignore and must contain all rules required by that capability.
paths, include, and rules can be used together with .scanignore.

You can think of root .scanignore as the default ignoreFrom provided for every scan capability:

# Equivalent behavior; do not add this to code_scan_config.yml
<capability>:
  scan:
    ignoreFrom: .scanignore

Validation fails if configuration cannot be parsed, an include fails, or an effective ignore file cannot be read.

Top-level structure

.cnb/security/code_scan_config.yml
# 0~N subfiles, merged in order
include:
  - <relative path>
  - path: <relative path> # object form, tolerate missing
    ignoreError: true

# Capability blocks (any subset; undeclared capabilities use platform defaults)
secrets:
  # ...
software-composition-analysis:
  # ...

Each capability block has the same shape:

<capability>:
  scan: # scan scope
    ignoreFrom: <path>
    paths:
      - <gitignore-style path rule>
  rules: # finding handling rules (Beta)
    - name: <id>
      when:
        # ...
      then:
        # ...

Important: common top-level keys are include, secrets, and software-composition-analysis. Unknown keys are treated as errors. Use the validate result as the source of truth.

include: split configuration for maintenance

Path resolution

All include paths are resolved relative to the repository root, whether they appear in code_scan_config.yml or in an included subfile:

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

.cnb/security/checks/secrets.yml
include:
  - .cnb/security/checks/secrets-extra.yml # ✅ still relative to repo root

Tolerate optional subfiles

In string form, a missing subfile causes an error. If you want to load the file when it exists and skip it when it is missing, use object form and set ignoreError: true:

.cnb/security/code_scan_config.yml
include:
  - { path: .cnb/security/checks/local-overrides.yml, ignoreError: true }

Tip: ignoreError only ignores missing files. Parsing errors, circular references, and paths escaping the repository still cause errors.

Merge rules

code_scan_config.yml and all included subfiles are eventually merged into one configuration. Different capabilities are independent. Fields under the same capability are merged as follows:

Field type	Merge behavior
Scalar (`ignoreFrom`)	A later value overwrites an earlier value
Array (`paths`, `rules`)	Appended and merged, in order from low to high priority

Priority, from low to high:

include[0] < include[1] < ... < include[N-1] < local code_scan_config.yml

Local values override include values: if both the local file and an included file define a scalar field, the local value takes effect.
Order within include: earlier includes have lower priority, and later values overwrite earlier ones.

Note the overwrite behavior of arrays: array fields are not overwritten. Elements from all sources are appended in low-to-high priority order. For path-rule negation, a local !pattern must come after included values to take effect.

Example

.cnb/security/code_scan_config.yml
# Local configuration, highest priority
include:
  - .cnb/security/checks/secrets.yml
secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/local # local scalar
    paths: ["!keep-local.go"] # local array

.cnb/security/checks/secrets.yml
secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/included
    paths: ["vendor/**"]

Merged result:

secrets:
  scan:
    ignoreFrom: .cnb/security/scanignore/local # local wins
    paths: ["vendor/**", "!keep-local.go"] # appended, local at end

Security restrictions

include paths must be relative and must not escape the repository root. ../.. is not allowed.
Absolute paths and URLs are not allowed. Cross-repository references are not supported.
Symlinks are not allowed. Even if the target is inside the repository, an error is reported.
A single parse supports at most 50 files, including recursive includes.
Circular includes are not allowed. For example, A → B → A reports an error.

Self-check with the validate plugin

validate is used to confirm that the configuration is correct before submission. Exit code 0 means the configuration is valid. A non-zero exit code means there is an issue, and the logs list each issue and its line number.

Call it in a CNB pipeline, recommended

Add a plugin task in the repository's .cnb.yml to block invalid configuration at the PR stage:

.cnb.yml
main:
  pull_request:
    - stages:
        - name: validate code scan config
          image: cnbcool/code-security-config
          args:
            - validate

args are appended to the plugin image entry command, equivalent to running code-security-config validate.
By default, it reads .cnb/security/code_scan_config.yml.
If the configuration is in another location, use args: [validate, --config, <repository-relative path>].
When validation fails, the task exits with a non-zero exit code. The pipeline fails, and the logs show each issue and its line number.

Call it locally

code-security-config validate                              # reads .cnb/security/code_scan_config.yml
code-security-config validate --config path/to/code_scan_config.yml

Next steps

Syntax reference — complete field-level reference.