Suppressions with a justification
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.
Before you start
Section titled “Before you start”- 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 . --verboseprints 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 |
1. Suppress one finding in the code
Section titled “1. Suppress one finding in the code”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 subprocessfrom 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).stdoutkeryn scan . --verbose --no-cacheKeryn — 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 themAnalysis: complete · Dependency advisories: not checked (offline) · Policy: blocked · Approval: not recordedbase not recorded → analyzed 69a8fd978be3df6646542bac4cd38507eae55067-dirtyComparison: not compared: no finding baseline suppliedCases: 1 current = 0 new + 0 existing + 1 unclassified; unknown cleared from previous assessmentNewly 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 checksExceptions: 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 excludedCoverage · dataflow: executed; see the recorded cross-file analysis scopeCoverage · 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: 1counts: 23 rule matches · 22 findings · 17 excluding AI-BOM inventory · 1 blocking before answersrules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned fileserrors: 1 confirmed error · 0 unconfirmed (pattern match only)pattern findings: 2 confirmed by cross-file analysisThe 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:
git checkout -- agent.pyapiVersion: keryn.dev/config/v1suppress: - 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-31reason 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.
keryn scan . --no-cache --quiet --sarif keryn-out/keryn.sarifjq '[.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.
An expired entry fails the build
Section titled “An expired entry fails the build”Change expires to a past date and scan again:
sed 's/expires: 2028-01-31/expires: 2026-01-31/' .keryn.yml > expired.ymlkeryn 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.)
3. Waive a policy rule
Section titled “3. Waive a policy rule”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/v1name: openai-onlyrules: - 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]}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:1Waive that one component, with the details a reviewer needs:
apiVersion: keryn.dev/policy/v1name: openai-onlyrules: - 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-31keryn policy lint .keryn/policy.ymlkeryn scan . --no-config --rules bundled:aibom --policy .keryn/policy.yml --markdown keryn-out/summary.md --quiet || truegrep -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: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 thisroles: suppress: [test, research, vendored] # vuln findings in these code roles move to the suppressed listUse 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.
What you just proved
Section titled “What you just proved”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).
- Answer findings one by one, by fingerprint, and turn the scan into Go, Go with accepted risk or Hold: release decisions (
keryn decide migratemoves these entries over). - Show the accepted risks to an auditor: evidence for auditors.
- Fail only on what a change adds: baselines and deltas.
- Every key of the file: configuration and policy.