Skip to content

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

    Suppressions with a justification

    View as Markdown

    Make a finding you have decided to accept stop failing the gate, in a way a reviewer or an auditor can read later: who accepted it, why, until when. And make sure an old acceptance cannot stay forever.

    • The Keryn CLI (install) and a repository with a finding you have already investigated. A suppression records a decision. It is not how you find out whether the finding is real; for that, read the attack chain.
    • The rule id of the finding. keryn scan . --verbose prints it in brackets next to the location.

    Keryn has four kinds of suppression. Use the most specific one that fits.

    Kind Where Scope Carries a reason
    Inline nosemgrep comment the source line one place in code in the comment, if you write it
    suppress: entry .keryn.yml a rule, optionally limited to a path required, with owner, ticket and expiry
    Policy waiver the policy file one policy rule, optionally one component required, with owner, ticket and expiry
    ruleOverrides .keryn.yml a rule everywhere, or a confidence floor no: it is tuning, not a decision about one finding

    Put a nosemgrep comment on the line of the finding or the line above it. Name the rule so only that rule is silenced.

    import subprocess
    from openai import OpenAI
    client = OpenAI()
    def run_tool(prompt: str) -> str:
    reply = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": prompt}])
    cmd = reply.choices[0].message.content
    # nosemgrep: seceng.llm05.python-subprocess-shell-true -- the command text is checked against ALLOWED_COMMANDS first (SEC-123)
    return subprocess.run(cmd, shell=True, capture_output=True, text=True).stdout
    Terminal window
    keryn scan . --verbose --no-cache
    Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
    1 violation(s)/finding(s) at or above 'error'
    dependency advisories not checked (offline): 1 lockfile(s); keryn scan --online checks them
    Analysis: complete · Dependency advisories: not checked (offline) · Policy: blocked · Approval: not recorded
    base not recorded → analyzed 69a8fd978be3df6646542bac4cd38507eae55067-dirty
    Comparison: not compared: no finding baseline supplied
    Cases: 1 current = 0 new + 0 existing + 1 unclassified; unknown cleared from previous assessment
    Newly blocking: unknown (no complete base run to compare with)
    Cases: 1 of 1 shown (limit 20); 0 omitted by display limit
    [blocking; unclassified] Text returned by a language model is passed to subprocess with shell=True (or as the program to run). A prompt injection becomes OS command injection with the privileges of this process. Do not let the model compose shell commands. Expose a small set of fixed commands as tools, pass model-chosen values as separate list arguments without shell=True, validate them against an allowlist, and run with least privilege and a timeout.
    agent.py:10 · path-in-file · 6 contributing rule(s) · sha256:3e1d08bdf85a155a6b8f82814b37b6fc8a84657781efac57fd6ccd58b2481d16
    Within-file flow [proof 2]
    Accounting: 22 recorded rule hits; 21 non-case observations; 1 suppressed rule hits; 1 failed checks
    Exceptions: 0 expired suppression entries; changes since the base unknown (no base run with its exceptions)
    Coverage · source patterns: scanned 3 files; 1598/1598 requested rules; 0 skipped; 0 excluded
    Coverage · dataflow: executed; see the recorded cross-file analysis scope
    Coverage · dependency advisories: not checked (offline); 1 lockfile(s) (keryn scan --online checks them, sending package names and versions only)
    Coverage · known-fix matching: executed; see recorded known-fix scope
    Limitation: Semgrep-compatible SUBSET: no join, no metavariable-pattern/comparison, no cross-file or type inference, no language equivalences/constant propagation; taint is an approximation.
    Limitation: Structural matching uses the bundled language grammars, including Ruby. Unsupported rule/language combinations are listed in coverage; generic text also supports regex rules.
    Limitation: Parity is only claimed where proven by differential tests against native Semgrep CE (results: https://keryn.dev/evals/semgrep-ce/).
    Limitation: Deliberate divergence: each language is matched with its own grammar. Semgrep CE reuses the JavaScript parse of a pattern for every language of a rule that lists javascript, so its Python side never matches keyword arguments, dict literals or eval/require there (reported as a rule warning).
    Limitation: 1 package licence unknown: their lockfiles record none. keryn scan --online looks them up on deps.dev, sending package names and versions only.
    Limitation: 1 lockfile not checked against vulnerability advisories (offline). keryn scan --online checks them, sending package names and versions only.
    Limitation: Maintainer/install-hook transition not checked without --base evidence; a lockfile alone does not record authenticated maintainer history.
    Limitation: 1 npm or PyPI package checked against the shipped malicious-package table (OSV MAL records) and the popularity list; additional ecosystem signals depend on the available data and package contents.
    Limitation: Malicious-package data: PyPI; source date <time>; shipped. Published MAL records are not proof that unlisted packages are safe.
    Exit code: 1
    counts: 23 rule matches · 22 findings · 17 excluding AI-BOM inventory · 1 blocking before answers
    rules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned files
    errors: 1 confirmed error · 0 unconfirmed (pattern match only)
    pattern findings: 2 confirmed by cross-file analysis

    The warning from seceng.llm05.python-subprocess-shell-true is gone from the case list. Accounting records one suppressed rule hit; the other cases on the same call remain because the comment names one rule. A comment without ids silences every rule on that line, which is almost never what you want. The comment must be preceded by a space after the comment marker (# nosemgrep; #nosemgrep does not count).

    Editors offer this as a quick fix (Suppress with nosemgrep), and it writes the rule ids for you.

    2. Suppress a rule for a path, with a reason and an expiry

    Section titled “2. Suppress a rule for a path, with a reason and an expiry”

    An inline comment cannot say who accepted a risk or when to look again. A suppress: entry in .keryn.yml does. Take the comment out again (this restores the file from git) and write the entry instead:

    Terminal window
    git checkout -- agent.py
    apiVersion: keryn.dev/config/v1
    suppress:
    - rule: seceng.llm05.python-subprocess-shell-true
    path: agent.py
    reason: The command is chosen from a fixed allow-list in dispatch(); reviewed in SEC-123.
    owner: platform-security
    ticket: SEC-123
    expires: 2028-01-31

    reason is required; Keryn refuses a file without one. rule can also be a list. expires is a date, valid through the end of that day in UTC. Choose a short one: the date in this example is far out only so that this page keeps passing its own test.

    Terminal window
    keryn scan . --no-cache --quiet --sarif keryn-out/keryn.sarif
    Terminal window
    jq '[.runs[0].results[] | select(.suppressions) | {ruleId, suppressions}]' keryn-out/keryn.sarif
    []

    The suppressed finding is not dropped from the evidence. SARIF keeps it as a result with a suppressions record, so code scanning shows it as accepted and an auditor can see the justification and the owner next to it. The assessment accounting records suppressed rule hits separately from cases and expired suppression entries.

    Change expires to a past date and scan again:

    Terminal window
    sed 's/expires: 2028-01-31/expires: 2026-01-31/' .keryn.yml > expired.yml
    keryn scan . --config expired.yml --no-cache | sed -n '1,2p'
    Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
    1 expired suppression(s) in config: #0 seceng.llm05.python-subprocess-shell-true (expired 2026-01-31)

    An expired entry suppresses nothing and is itself a failure, with the entry named. That is the point: the acceptance has to be renewed by a person who looks at it again. (expired.yml is a throwaway copy; the real file is unchanged.)

    A policy violation is not a finding, so it has its own waiver, inside the policy file. This policy allows only openai, so the anthropic library fails it:

    apiVersion: keryn.dev/policy/v1
    name: openai-only
    rules:
    - id: approved-llm-providers
    description: Only approved model providers may be referenced
    severity: error
    match: {kind: library, category: llm-sdk}
    allowOnly: {field: name, values: [openai]}
    Terminal window
    keryn scan . --no-config --rules bundled:aibom --policy .keryn/policy.yml | grep -A1 "^AI-component constraints"
    AI-component constraints: violated (1 checks, 1 violations)
    [error] approved-llm-providers: Only approved model providers may be referenced: name 'anthropic' of 'anthropic' is not on the allow-list @ support.py:1

    Waive that one component, with the details a reviewer needs:

    apiVersion: keryn.dev/policy/v1
    name: openai-only
    rules:
    - id: approved-llm-providers
    description: Only approved model providers may be referenced
    severity: error
    match: {kind: library, category: llm-sdk}
    allowOnly: {field: name, values: [openai]}
    waivers:
    - rule: approved-llm-providers
    component: "library:anthropic"
    reason: Pilot of a second provider for the support desk, reviewed by the platform team.
    owner: platform-security
    ticket: SEC-231
    expires: 2028-01-31
    Terminal window
    keryn policy lint .keryn/policy.yml
    keryn scan . --no-config --rules bundled:aibom --policy .keryn/policy.yml --markdown keryn-out/summary.md --quiet || true
    grep -A4 "Waived" keryn-out/summary.md
    .keryn/policy.yml: valid (keryn.dev/policy/v1)
    ### Waived (audit trail)
    | Rule | Component | Owner | Ticket | Expires | Reason |
    |---|---|---|---|---|---|
    | approved-llm-providers | library&#58;anthropic | platform-security | SEC-231 | 2028-01-31 | Pilot of a second provider for the support desk, reviewed by the platform team. |

    The pull request comment and the CI job summary carry that table, so a waiver is visible in review, not buried in a file. A waiver without a reason, or past its date, does not suppress anything and is reported as a failure.

    4. Tune a rule, which is not a suppression

    Section titled “4. Tune a rule, which is not a suppression”

    ruleOverrides in .keryn.yml changes how a rule counts, for every finding of it:

    ruleOverrides:
    disable: [acme.noisy-rule] # dropped, and counted as suppressed
    severity: { acme.agent-without-max-turns: INFO }
    minConfidence: P1 # drop findings from rules less sure than this
    roles:
    suppress: [test, research, vendored] # vuln findings in these code roles move to the suppressed list

    Use it for your own rules and for the code roles you do not ship. For a risk you have looked at in one place, use steps 1 to 3, which keep a reason.

    A suppression is a recorded decision on one edge: this path, in this file, carries this risk, accepted by this person for this reason until this date. The three things the gate will not do for you are the ones this guide keeps in view: it never accepts a finding without a person naming a reason, it never keeps an acceptance past its date, and it never hides the accepted finding from the evidence (SARIF and the audit table keep it).