Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Suppressions

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    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.

    # keryn-ignore-next-line: python.example.rule -- fixture reviewed by security
    example()
    example() # keryn-ignore-line: python.example.rule -- fixture reviewed by security
    # keryn-ignore-start: python.example.rule -- reviewed generated section
    example()
    # 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 with TODO) 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-suppression finding at warning level.
    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.

    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.disable: [<rule>] turns a rule off. ruleOverrides.minConfidence: P1|P2 sets aside findings below that confidence. Both show as config suppressions. ruleOverrides.severity: {<rule>: ERROR|WARNING|INFO} re-levels findings that are kept.
    • roles.suppress (default test, research, vendored) sets aside vulnerability findings in code of those roles, with the reason role:<role>. A role cannot be both suppressed and labelled.
    1. Per file, inline: keryn-ignore, then nosemgrep; then keryn-ignore again over all findings, Deep included.
    2. Roles.
    3. .keryn.yml: ruleOverrides.disable, then minConfidence, then the first active suppress entry, in file order.
    4. Fingerprints are computed for the findings that remain.
    5. .keryn/decisions.yml is 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.)

    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.

    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.

    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.

    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 nosemgrep and gitleaks:allow quick fixes.