A suppression changes what is matched or counted. It is not accepted risk and does not approve a release. To record a decision about a real finding, use release decisions (.keryn/decisions.yml). The how-to is in suppressions with a justification.
Inline: keryn-ignore
Section titled “Inline: keryn-ignore”# keryn-ignore-next-line: python.example.rule -- fixture reviewed by securityexample()example() # keryn-ignore-line: python.example.rule -- fixture reviewed by security# keryn-ignore-start: python.example.rule -- reviewed generated sectionexample()# keryn-ignore-end: python.example.rule| Directive | Covers |
|---|---|
keryn-ignore-line: <rule> -- <reason> |
its own line |
keryn-ignore-next-line: <rule> -- <reason> |
the next line |
keryn-ignore-start: <rule> -- <reason> … keryn-ignore-end: <rule> |
the lines between them (not the comment lines) |
keryn-ignore: <rule> -- <reason> |
its own line after code; the next line when the comment stands alone |
- Rule id. One per directive, the full rule id exactly. A short or last-segment id does not match.
- Reason. Required after
--. A placeholder (<reason>,REPLACE_ME, or a reason starting withTODO) is refused. - Blocks. Must be bounded and not nested. The end names the same rule as the start.
- Comment syntax.
#in Python, Ruby, shell, YAML, TOML, R, Perl, PowerShell and Dockerfiles;--in SQL, Lua and Haskell;<!-- -->in HTML, XML, Markdown and SVG;//and/* */elsewhere. Text inside quotes is never a directive. - Scope. Applies to the pattern rules and to Deep findings.
- Invalid directives (malformed, missing reason, nested, unclosed, mismatched) suppress nothing. Each produces a
keryn.invalid-suppressionfinding at warning level.
Inline: nosemgrep and gitleaks:allow
Section titled “Inline: nosemgrep and gitleaks:allow”| Comment | Applies to | Matching |
|---|---|---|
nosemgrep / nosem, optionally : <ids> |
pattern-rule findings on that line or the line below the comment | no ids: every rule; with ids: the full id or its last dotted segment |
gitleaks:allow |
a secret on that line | the secret is still found, then set aside as an inline suppression with reason gitleaks:allow: counted, listed in suppressed[] and in SARIF. In 0.5.2 the secrets engine skips the line and nothing is counted. |
A .gitleaksignore file at the scanned root (on main, not in 0.5.2) works like gitleaks:allow for the findings it lists, one gitleaks fingerprint per line (file:rule:line, or commit:file:rule:line for a finding from --secrets-history): the secret is still found, then set aside as an inline suppression with reason gitleaksignore, and coverage states how many findings the file set aside. See the secrets guide.
A keryn-ignore directive takes precedence on the lines it covers, malformed ones included. A nosemgrep there cannot broaden it.
.keryn.yml: suppress
Section titled “.keryn.yml: suppress”suppress: - rule: python.flask.debug-enabled path: examples/** reason: demo apps only, never deployed expires: 2027-03-31 owner: platform-team - rule: [seceng.llm05.python-subprocess-shell-true] exactPath: tools/release.py line: 42 anchor: sha256:3e1d08bdf85a155a6b8f82814b37b6fc8a84657781efac57fd6ccd58b2481d16 reason: fixed command list, reviewed in SEC-118 owner: release-eng expires: 2027-01-31| Key | Required | Meaning |
|---|---|---|
rule |
yes | a rule id or a list; the full id exactly |
reason |
yes | why; shown with the suppressed finding (with (owner …) when owner is set) |
path |
no | a glob, as in include/exclude |
exactPath |
for a scoped entry | a literal repository-relative path |
line |
for a scoped entry | the evidence line, 1 or more |
anchor |
for a scoped entry | sha256: of the trimmed first non-blank cited line |
expires |
no | YYYY-MM-DD; valid through the end of that day, UTC |
owner, ticket |
no | who owns it; a tracking reference |
A scoped entry, one with any of exactPath, line or anchor, needs all three, plus a reason that is not a placeholder. It matches only that file, that line and that exact source text, so an edited or moved line stops matching. An entry that breaks the schema is a configuration error (exit 2).
ruleOverrides and roles
Section titled “ruleOverrides and roles”ruleOverrides.disable: [<rule>]turns a rule off.ruleOverrides.minConfidence: P1|P2sets aside findings below that confidence. Both show as config suppressions.ruleOverrides.severity: {<rule>: ERROR|WARNING|INFO}re-levels findings that are kept.roles.suppress(defaulttest,research,vendored) sets aside vulnerability findings in code of those roles, with the reasonrole:<role>. A role cannot be both suppressed and labelled.
Precedence
Section titled “Precedence”- Per file, inline:
keryn-ignore, thennosemgrep; thenkeryn-ignoreagain over all findings, Deep included. - Roles.
.keryn.yml:ruleOverrides.disable, thenminConfidence, then the first activesuppressentry, in file order.- Fingerprints are computed for the findings that remain.
.keryn/decisions.ymlis matched against the remaining findings only. A decision for a suppressed finding does not turn the suppression into accepted risk.
In a pull request checked under an enforced policy base, inline keryn-ignore, nosemgrep and gitleaks:allow cannot suppress gate findings, a .gitleaksignore is not honoured, the default secret detectors run beside a repository-supplied gitleaks config (so its allowlists and disabled rules hide nothing), and .keryn.yml is read from the trusted base. (In 0.5.2, gitleaks:allow still hides the secret there.)
Expiry
Section titled “Expiry”An expired suppress entry suppresses nothing, so its findings count again. Each expired entry also counts as a failure: the gate reason is N expired suppression(s) in config: #i rule (expired D), exit 1, unless --fail-on none. With a release decision, it is a Hold with cause suppression. The coverage statement and the console’s Exceptions line count expired entries.
Moving to release decisions
Section titled “Moving to release decisions”keryn decide migrate turns suppress entries into .keryn/decisions.yml entries. A plain entry becomes a fingerprint decision for each finding it matches today, or a match: entry (rule and path) when it matches none. A scoped entry becomes a fingerprint decision for the one finding at its exact path, line and source anchor. If that finding is gone, the entry is not migrated, and --remove-legacy keeps it, because a rule-wide decision would broaden it.
How suppressed findings are reported
Section titled “How suppressed findings are reported”| Output | What it shows |
|---|---|
| Result JSON | suppressed[]: each finding with suppressed: {kind: inline|config|role, reason?, ruleIds?}, plus owner, ticket and expires from a suppress entry; counts in coverage.suppressed (inline, config, role, expired[]) |
| SARIF | suppressed findings at gating levels, gating: false, with a SARIF suppressions entry: inSource for inline (with the keryn-ignore or gitleaks:allow reason as justification), external with the reason for config and roles |
| Console | the count of suppressed rule hits and the coverage statement (N inline by nosemgrep or keryn-ignore, N by config) |
| Markdown summary | the same count, and a Suppressed (audit trail) table: each suppression with a stated reason (rule, location, inline or .keryn.yml, owner, ticket, expiry, reason; up to 50 rows) and each expired entry |
| Decision view | suppressed — not accepted risk, for suppressed findings at or above --fail-on |
Suppressed findings never gate.
Scoped suppression proposal
Section titled “Scoped suppression proposal”In Keryn Web, a finding’s detail has Propose scoped suppression. Give a reason, an owner and a review date (today or later), then Generate suppression proposal and Download suppression proposal. The download is keryn-suppression-proposal.yml, holding one scoped suppress entry (rule ids, exactPath, line, anchor, reason, owner, expires). Merge it into your trusted .keryn.yml after review.
- Generating a proposal does not change the report.
- A finding without a source anchor gets no proposal; record a decision instead.
- The browser extensions offer Copy scoped suppression proposal.
- There is no CLI command for it.
- The editor extensions still offer
nosemgrepandgitleaks:allowquick fixes.