Skip to content

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

    Release decisions

    View as Markdown

    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.

    • 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.
    Terminal window
    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.

    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/v1
    decisions:
    - 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
    Terminal window
    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/v1
    in_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.

    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:

    Terminal window
    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.

    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/v1
    suppress:
    - 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-31

    To turn legacy entries into answers:

    Terminal window
    keryn decide migrate .
    keryn decide migrate . --write
    keryn decide migrate . --write --remove-legacy

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

    Terminal window
    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.

    Terminal window
    keryn decide export . --github example/app --dry-run

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

    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.yml declares 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.yml and commit. The page does not sign. A signature is keryn decide sign in 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.sarif

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