Release decisions
Answer one question for a change: can it go out, and on what terms? Keryn proposes one of three labels from the scan and from your repository’s own answers to its findings, and a person signs it.
| Label | When | Exit code |
|---|---|---|
| Hold | a finding at or above --fail-on has no live answer, is under investigation, is affected without acceptance, or its answer expired; or the policy is broken |
1 |
| Go with accepted risk | everything gating is answered, and at least one answer is an accepted risk (who, until when, the ticket) | 0 (10 with --exit-warn) |
| Go | nothing gating is open and no risk is accepted | 0 |
The codes are the ones keryn scan already uses, so a CI job does not change. Every decision also prints what the scan could not read: a Go with incomplete coverage says so on the same line. Keryn never says a release is fine to ship; it says what is open and what was accepted, by whom.
Before you start
Section titled “Before you start”- The Keryn CLI (install) and a repository with findings you have looked at. An answer records a decision about a finding; to work out whether a finding is real, read its attack chain first.
- Answers live in the repository, next to the code, and change through pull requests like the code does.
1. Ask for the decision
Section titled “1. Ask for the decision”keryn decide .With no answers yet, every gating finding is a Hold. Each Hold names the finding, the edge it sits on and its proof level. When the trust model places the file on a chain, the edge is that chain’s step, for example flow.user_input: User prompt -> agent.py agent (OpenAI SDK). Otherwise it is the finding’s file:line -> rule.
2. Answer the findings
Section titled “2. Answer the findings”Create .keryn/decisions.yml. Each entry answers one finding by its fingerprint (keryn scan --json lists them), or every finding of a rule in a path with match:
apiVersion: keryn.dev/decisions/v1decisions: - match: {rule: seceng/shell_exec, path: agent.py} status: affected accepted: true reason: Internal tool behind the VPN; the command allow-list ships with the agent rewrite. ticket: https://github.com/example/app/issues/142 expires: 2027-01-31 decided_by: dana@example.com decided_at: 2026-11-08 - match: {rule: python.code-execution.llm-output-to-subprocess, path: agent.py} status: under_investigation reason: Checking whether the prompt can carry user text. decided_by: dana@example.com decided_at: 2026-11-08| Field | Meaning |
|---|---|
status |
not_affected, affected, fixed or under_investigation (the OpenVEX statuses) |
justification |
required for not_affected: one of the OpenVEX justifications, such as vulnerable_code_not_in_execute_path |
accepted, expires |
an accepted risk is affected with accepted: true and an expiry date; after that date it is a Hold again |
reason, decided_by, decided_at |
required on every entry: why, who, when |
ticket, owner |
optional; keryn decide export fills ticket |
keryn decide .The accepted risks now print with who accepted them and until when. Whatever is still unanswered, or under investigation, stays a Hold. Answer the rest and the label becomes Go with accepted risk.
The files under .keryn/ (decisions.yml, scope.yml, releases.jsonl) are records, not code: a scan never reads them as source, and the coverage line counts them separately.
3. Say what is in scope and what is not covered
Section titled “3. Say what is in scope and what is not covered”.keryn/scope.yml states the scope and the coverage you declare. It prints on every decision and in the hand-off reports, so nobody reads a Go as “everything was checked”.
apiVersion: keryn.dev/scope/v1in_scope: - {path: "services/**", note: "customer-facing agents"}exclusions: - {path: "vendor/**", reason: "Third-party code, scanned upstream.", decided_by: dana@example.com, decided_at: 2026-11-08}coverage: - {area: python services, status: covered} - {area: runtime behaviour, status: not_covered, note: "Keryn reads code and config; nothing watches production."}Once either file exists, keryn scan prints the decision as well and carries it in --json as decision (label, holds, acceptedRisks, coverage, signed). A repository without them behaves exactly as before.
4. Sign it
Section titled “4. Sign it”A decision is proposed by Keryn and signed by a person. The example answers above still leave a Hold under investigation, so this command refuses to sign until it is resolved:
keryn decide sign .sign records git config user.email (shown before it writes; nobody can sign as another name) in .keryn/releases.jsonl, each record chained to the previous one by hash. It refuses a Hold, and it refuses to run when CI is set: a pipeline proposes, a person signs. To make a signature mandatory, set release: {require_signature: true} in the policy file; an unsigned Go then exits 1.
5. Move existing suppressions over
Section titled “5. Move existing suppressions over”suppress: entries in .keryn.yml and policy waivers keep working. For example, this legacy entry is tied to the reviewed finding in agent.py:
apiVersion: keryn.dev/config/v1suppress: - rule: seceng.llm05.python-subprocess-shell-true path: agent.py reason: Fixed command allow-list reviewed in SEC-123. owner: platform-security ticket: SEC-123 expires: 2028-01-31To turn legacy entries into answers:
keryn decide migrate .keryn decide migrate . --writekeryn decide migrate . --write --remove-legacyThe first command prints the decisions it would add, one per finding the old entry covers today. --write adds them to .keryn/decisions.yml and leaves the old entries; --remove-legacy removes only the old entries the file now covers. Entries nobody owned get decided_by: unknown, which the decision shows as needing a person. See Suppressions for the older forms.
6. Export OpenVEX
Section titled “6. Export OpenVEX”keryn export --vex vex.json .vex.json is an OpenVEX 0.2.0 document of your answers: the status and justification pass through, the reason becomes the impact or action statement, the rule id is the vulnerability name, and an accepted risk is affected with who accepted it and until when. The product is --product, else the git remote as a purl, else pkg:generic/<folder name>. The evidence pack carries the same file.
7. Open issues for what is held
Section titled “7. Open issues for what is held”keryn decide export . --github example/app --dry-rundecide export opens one issue per chain or chokepoint of the trust model (findings on no chain: one per rule and directory), listing the findings, the edge, the proof level, the coverage and each finding’s decision status. --dry-run prints the requests as JSON and uses no token and no network. A real run reads GITHUB_TOKEN or GITLAB_TOKEN from the environment (there is no flag for it), searches the tracker for each issue’s keryn:issue marker first, and creates nothing that already exists or that an answer already tickets. The new issue’s address becomes ticket on the answers; --record also adds under_investigation answers for findings without one, signed with your git email. Use --gitlab <group/project> for GitLab, --gitlab-url for a self-managed instance and --github-url for GitHub Enterprise.
Closing an issue never changes an answer. If per-finding alerts are all you need, use the SARIF file the scan writes instead: your pipeline’s own step can send it to code scanning (Keryn never uploads it; see the CI guide). Issues are for chains.
In Keryn Web
Section titled “In Keryn Web”After a scan, Release decision in the scan results opens the Decision Desk (#/decide). It computes the same label as keryn decide with the same function, and it pushes nothing.
- The label, then each Hold with its chain edge and proof level, and the accepted risks with who accepted them and until when.
- Proposed by triage: triage verdicts (upheld, refuted, needs context, unsupported, declined) waiting for a person. A verdict is a suggestion and changes nothing. Only Record decision turns it into an answer: the form asks for the answer, the reason, an optional ticket and Decided by, a name you type, and Add to decisions.yml puts it in this tab’s draft.
- Coverage and scope, as
.keryn/scope.ymldeclares them. - Export issues: one issue per chain of open Holds, in GitHub or GitLab. It shows the issues it would create before it sends anything, and sends only when you click, with the token of the connector you set up in Settings.
- Save and sign: Save decisions.yml downloads the file for you to copy to
.keryn/decisions.ymland commit. The page does not sign. A signature iskeryn decide signin the repository, which records the git identity, is refused in CI and cannot sign as another name.
A scan of a zip or a repository link has no folder to read .keryn/ files from, so Open .keryn files reads decisions.yml, scope.yml, releases.jsonl or policy.yml that you pick, in the tab. When the trust analysis cannot run, a Hold names its file and rule instead of a chain edge, and the page says so. The Reports menu’s hand-off reports read the same files; see controls, posture and hand-off reports.
- run: keryn scan . --fail-on error --sarif keryn.sarifNo change is needed: with .keryn/decisions.yml in the repository, the scan’s exit code follows the decision (Hold fails the job). The CI guide lists the exit codes.