# Suppressions

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> Every way to set a finding aside (keryn-ignore, nosemgrep, gitleaks:allow, .keryn.yml suppress entries including scoped ones, ruleOverrides, roles), their precedence, expiry, how suppressed findings are reported, and the scoped suppression proposal.

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

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](https://keryn.dev/docs/guides/release-decisions/) (`.keryn/decisions.yml`). The how-to is in [suppressions with a justification](https://keryn.dev/docs/guides/suppressions/).

> **Caution: Ships in the next release**
> `keryn-ignore` directives, scoped `suppress` entries (`exactPath`, `line`, `anchor`) and the proposal are on main and not in Keryn 0.5.2. So are: `gitleaks:allow` counted as a suppression and off under an enforced policy base; reasons in SARIF `inSource` suppressions; the Markdown audit trail; and scoped entries kept narrow by `decide migrate`. `nosemgrep`, `gitleaks:allow`, plain `suppress` entries, `ruleOverrides` and roles are in 0.5.2.

## Inline: `keryn-ignore`

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

## 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](https://keryn.dev/docs/guides/secrets/#your-own-rules-and-an-existing-gitleaks-setup).

A `keryn-ignore` directive takes precedence on the lines it covers, malformed ones included. A `nosemgrep` there cannot broaden it.

## `.keryn.yml`: `suppress`

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

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

## Precedence

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

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

`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

| 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

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.
