Configuration File

About 881 wordsAbout 3 min

Configuration File describes the overall structure of code_scan_config.yml, its file location, and how to split configuration with include.

When to use: when you need to adjust the platform's default scan scope — for example to give one capability its own ignore rules, split a long configuration into subfiles, or self-check it with validate before committing.

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`

Neither is required. If neither is configured, the platform uses its default scan scope.

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

Root .scanignore behaves as the default ignoreFrom for every 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

Tips

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: when both the local file and an included file define a scalar field, the local value wins.
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, and cross-repository references are not supported.
Symlinks are not allowed: an error is reported even if the target is inside the repository.
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

Use validate to self-check the configuration before committing it. Exit code 0 means the configuration is valid; a non-zero exit code means there is an issue, and the logs list each issue with 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 with 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

For a complete field reference, see Syntax Reference.