# Suppressions with a justification

> Accept a finding or a policy violation on purpose, with a reason, an owner and an expiry that fails the build when it lapses.

Source: https://keryn.dev/docs/guides/suppressions/

## Goal

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

- The Keryn CLI ([install](https://keryn.dev/docs/start/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](https://keryn.dev/docs/guides/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 |

## 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.

```python
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
```

```sh
keryn scan . --verbose --no-cache
```

```text
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.

> **Note: Ships in the next release**
> On main, `keryn-ignore` directives take a single full rule id and a required reason (`# keryn-ignore-next-line: <rule> -- <reason>`), cover Deep findings too, and take precedence over `nosemgrep` on the lines they cover. Keryn Web replaces "copy a nosemgrep line" with a **scoped suppression proposal**: a `.keryn.yml` entry tied to the file, the line and the exact source text. Every form, key and precedence rule: [suppressions reference](https://keryn.dev/docs/reference/suppressions/).

## 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:

```sh
git checkout -- agent.py
```

```yaml
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.

```sh
keryn scan . --no-cache --quiet --sarif keryn-out/keryn.sarif
```

```sh
jq '[.runs[0].results[] | select(.suppressions) | {ruleId, suppressions}]' keryn-out/keryn.sarif
```

```text
[]
```

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

Change `expires` to a past date and scan again:

```sh
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'
```

```text
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

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:

```yaml
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]}
```

```sh
keryn scan . --no-config --rules bundled:aibom --policy .keryn/policy.yml | grep -A1 "^AI-component constraints"
```

```text
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:

```yaml
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
```

```sh
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
```

```text
.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

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

```yaml
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.

## 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).

## Next

- Answer findings one by one, by fingerprint, and turn the scan into Go, Go with accepted risk or Hold: [release decisions](https://keryn.dev/docs/guides/release-decisions/) (`keryn decide migrate` moves these entries over).
- Show the accepted risks to an auditor: [evidence for auditors](https://keryn.dev/docs/guides/auditors/).
- Fail only on what a change adds: [baselines and deltas](https://keryn.dev/docs/guides/baselines/).
- Every key of the file: [configuration](https://keryn.dev/docs/reference/config/) and [policy](https://keryn.dev/docs/reference/policy/).
