# Configuration file (.keryn.yml)

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> Every key of .keryn.yml, generated from its JSON Schema.

Source: https://keryn.dev/docs/reference/config/

`keryn scan`, `bom`, `diff` and the editor integrations read `./.keryn.yml` when it exists (`--config <file>` picks another, `--no-config` ignores it). Command-line flags win over the file. `keryn init` writes a starting file.

Schema: [`https://keryn.dev/schemas/config/v1.json`](https://keryn.dev/schemas/config/v1.json) (JSON Schema draft-07). Point your editor's YAML plugin at it for completion and validation.

```yaml
# .keryn.yml
apiVersion: keryn.dev/config/v1
rules: ["bundled:all"]
policy: .keryn/policy.yml
exclude: ["vendor/**", "**/*.min.js"]
failOn: error
```

## Keys

| Key | Type | Required | Description |
|---|---|---|---|
| `apiVersion` | `"keryn.dev/config/v1"` | yes |  |
| `attribution` | object |  |  |
| `subject` | string |  | BOM subject name. |
| `revision` | string |  | BOM subject version, e.g. a commit SHA. |
| `rules` | array of string |  | Rule files, or bundled packs as "bundled:&lt;id>". Default: ["bundled:all"] for keryn scan (the whole canonical pack, AI-BOM inventory included), ["bundled:aibom"] for the other commands. |
| `policy` | string |  | Path to a policy YAML. |
| `include` | array of string |  |  |
| `exclude` | array of string |  |  |
| `base` | string |  | Git ref or CycloneDX file to diff against (keryn scan/diff --base; the language server diffs every scan against it and marks added findings [new]). |
| `failOn` | `error` · `warning` · `info` · `none` |  |  |
| `failOnUnsupported` | boolean |  |  |
| `advisoryMaxAge` | integer |  | Days the installed offline advisory snapshot (keryn sca db update) may be old. An older one still checks the dependencies but the run is incomplete (exit 3). Same as --advisory-max-age. |
| `requireAdvisories` | boolean |  | Exit 3 when the tree has lockfiles whose packages were not matched against vulnerability advisories (an offline scan): the CLI flag --require-advisories. |
| `exitWarn` | boolean |  |  |
| `maxFileSize` | integer |  | Bytes. |
| `maxFiles` | integer |  |  |
| `maxTotalSize` | integer |  | Bytes. |
| `timeout` | integer |  | Seconds. |
| `symlinks` | `skip` · `follow-confined` · `error` |  |  |
| `annotations` | `github` · `azure` · `gitlab` · `teamcity` |  |  |
| `ruleOverrides` | object |  | Noise controls applied after matching. (`rules` is taken by the rule-file list, so these live under ruleOverrides.) |
| `suppress` | array of object |  | Waivers: findings matching rule (+ optional path glob) are suppressed with a recorded reason until `expires` (UTC, end of day); expired entries do not suppress and are reported. |
| `secrets` | object |  | Secrets stage. Without this key (and without --secrets-config) a .gitleaks.toml at the scanned root is used when present; a .gitleaksignore at the root is always read. |
| `roles` | object |  | Code-role policy (path-based: application, library, framework, template, test, research, vendored, documentation, tooling, data; a Rust `#[cfg(test)]` item or `#[test]` function inside source is test). Vuln findings in a `suppress` role move to the suppressed list; audit and inventory findings never do. Default: suppress [test, research, vendored], label [template, library, tooling, data]. |
| `cloud` | object |  | Keryn Cloud. Nothing is uploaded unless you are signed in and have run an upload; this only narrows what an upload may contain. |
| `sbomFormat` | `cyclonedx` · `spdx` |  | Format of the dependency SBOM: CycloneDX 1.6 JSON (default) or SPDX 2.3 JSON. |
| `outputs` | object |  |  |
