AI-BOM (CycloneDX 1.6), rule findings and policy gate for a repository, with SARIF upload and a step summary. Local, deterministic, no telemetry. A composite action (ts/clients/github-action/action.yml); the CI guide shows the other pipeline platforms.
Example
Section titled “Example”on: pull_requestpermissions: contents: read security-events: write # upload-sarif pull-requests: write # commentjobs: keryn: runs-on: ubuntu-24.04 steps: - uses: actions/checkout@<full-commit-sha> with: persist-credentials: false fetch-depth: 0 ref: ${{ github.event.pull_request.head.sha || github.sha }} - uses: <path or repository of the Keryn Action>@<full-commit-sha> with: tarball: vendor/keryn-cli-0.5.2.tgz tarball-sha256: <sha256 of that file> policy: .keryn/policy.yml comment: trueInputs
Section titled “Inputs”Set both tarball and tarball-sha256. The action rejects a nonempty version input.
| Input | Default | Description |
|---|---|---|
path |
. |
Directory to scan, relative to the workspace. |
rules |
empty | Rule files or bundled packs, comma-separated (keryn scan –rules). Empty keeps the CLI default (bundled:all, the whole library, with Deep); bundled:aibom for inventory only. |
policy |
empty | Policy-as-code YAML (keryn scan –policy). Empty means no policy. |
fail-on |
error |
Gate threshold (error | warning | info | none). |
fail-on-unsupported |
false |
Kept for compatibility. The CLI already exits 3 when rules were unsupported, partial or timed out, whatever this says; set allow-incomplete to accept incomplete coverage instead. |
allow-incomplete |
false |
Do not exit 3 when coverage is incomplete (keryn scan –allow-incomplete). The job then passes or fails on the findings alone; the report still says what was not covered. |
fail-on-added |
false |
With base-ref, exit 1 when components were added. |
exit-warn |
false |
Exit 10 for pass-with-warnings (mapped to a workflow warning, not a failure). |
base-ref |
${{ github.event.pull_request.base.sha }} |
Git ref to diff against (keryn scan –base). Defaults to the pull request base; empty disables the diff. Needs fetch-depth 0. |
new-only |
false |
Gate only new findings against the paired Git base. Requires a CLI release containing –new-only; incomplete comparisons fail closed. |
summary-by |
empty | Group findings by a framework taxonomy in the summary (owasp_llm | owasp_agentic | cwe | nist_ai_rmf | atlas); reference only. |
version |
empty | Not supported. The keryn CLI is not published to npm. Download keryn-cli-<version>.tgz from https://keryn.app/download after signing in and pass it as tarball with tarball-sha256. Giving version stops the action with that instruction. |
tarball |
empty | Path to a keryn-cli-<version>.tgz (npm pack of the CLI), absolute or relative to the workspace. Installed offline. |
tarball-sha256 |
empty | Expected SHA-256 of the tarball; the action stops before installing when it differs. |
token |
empty | A Keryn CI credential, from a secret. An organization administrator issues it as a service account in Account > Developers. The CLI reads it as KERYN_TOKEN, signs the run in without a browser, and never stores or prints it. Leave empty for a build of the CLI that needs no sign-in. |
server |
empty | The Keryn service the credential belongs to. Empty means api.keryn.app. |
require-token |
false |
Set to true when the CLI is a release build that scans only when signed in. Without a token the job then stops before installing anything, with the reason. A pull request from a fork never receives the secret, so its check fails and says a maintainer must run the scan; it is never skipped as passed. |
node-version |
24 |
Node.js version for the CLI. |
upload-sarif |
true |
Upload the SARIF to GitHub code scanning (needs security-events write). |
sarif-category |
keryn |
Code scanning category of the upload. |
upload-bom |
true |
Upload the AI-BOM, SARIF and JSON as a workflow artifact. |
step-summary |
true |
Append the markdown summary to the job summary. |
annotations |
true |
Emit GitHub annotations for findings (keryn scan –annotations github). |
attribution |
false |
Include PR attribution and evaluate the PR base’s .keryn.yml attribution gate and .keryn/policy.yml AI usage rules. Requires a CLI with attribution pr. |
output-dir |
empty | Where the outputs are written. Existing Keryn report files in this directory are refused. |
comment |
false |
On pull requests, post the markdown summary as a PR comment and update it in place on later pushes (needs pull-requests write). |
github-token |
empty | Token for the PR comment; defaults to the workflow token. Fork pull requests get a read-only token, so the comment is skipped with a warning. |
commit-status |
false |
Set a commit status keryn/<sarif-category> on the scanned commit from the CLI verdict (success on 0 and 10, failure on 1, error otherwise; needs statuses write). Idempotent per context. |
Outputs
Section titled “Outputs”A path output is set only when the file exists. Outputs are written before the step that fails the job.
| Output | Description |
|---|---|
exit-code |
The CLI’s exit code (0 pass, 1 violations, 2 usage, 3 coverage, 4 internal, 10 warnings). |
sarif |
Path of the SARIF 2.1.0 file. |
aibom |
Path of the CycloneDX 1.6 AI-BOM. |
json |
Path of the Keryn result JSON. |
markdown |
Path of the markdown summary. |
Permissions
Section titled “Permissions”| Permission | Needed for |
|---|---|
contents: read |
always |
security-events: write |
upload-sarif |
pull-requests: write |
comment |
statuses: write |
commit-status |
The action needs no secret: comment and commit-status use the workflow token (or github-token). The scan makes no network call; a tarball install is npm install --offline --ignore-scripts. The third-party actions it calls are pinned by full commit SHA.
Fork-safe model
Section titled “Fork-safe model”- Only
pull_requestruns.pull_request_targetis refused before anything is installed. - The scan refuses to run unless the checked-out HEAD is the pull request’s head commit.
- For a pull request from a fork, the comment, the commit status and the SARIF upload are skipped (no privileged token). The scan, annotations, the job summary, the artifact and the job’s exit code (the required check) still run.
- Pin the action by full commit SHA, check out with
persist-credentials: false, and protect the workflow and the base policy with rulesets or CODEOWNERS.
Exit codes
Section titled “Exit codes”The CLI’s code is the exit-code output; the last step turns it into the job’s result: 0 passes, 10 (pass with warnings, with exit-warn) passes with a workflow warning, anything else fails the job with that code (1 findings or policy, 2 usage or configuration, 3 coverage incomplete, 4 internal error). The final error or warning names the gate’s reasons; they are also in the job summary and the result JSON.
Incomplete coverage (an unsupported, partial or timed-out rule) exits 3 by default. Set allow-incomplete: true to pass or fail on the findings alone; the report still says what was not covered. fail-on-unsupported is kept for compatibility and changes nothing.
With commit-status, the status keryn/<sarif-category> is success for 0 and 10, failure for 1, error otherwise.
Annotations, comment, SARIF
Section titled “Annotations, comment, SARIF”- Annotations (
annotations): one per assessment case, not per rule hit:errorwhen the case blocks,warningotherwise, plus akeryn.coveragewarning when coverage is incomplete. - Sticky comment (
comment): one comment per pull request andsarif-category, marked<!-- keryn-comment:<category> -->and updated on every push. The comment is found by the login of the token that writes it, so a customgithub-tokenupdates its own comment too; nobody else’s comment is touched. Bodies over 60,000 bytes are cut with a pointer to the job summary. A failure to post is a warning and does not change the exit code. - SARIF (
upload-sarif): uploaded to code scanning undersarif-category, withbaselineState(new, unchanged) whenbase-refis set, and the repository and revision recorded. - Artifact (
upload-bom): the AI-BOM, SARIF and result JSON, kept 30 days.
New findings only
Section titled “New findings only”new-only: true scans base-ref with the same pipeline and gates only findings the base does not have. A comparison that is not like for like (different engine or rule versions, a different rule set or exclusions, incomplete coverage on either side, a finding without a fingerprint) exits 3: no passing delta gate is issued. The verdict reads New-findings checks passed (release approval not assessed): it is not a release decision, and .keryn/decisions.yml does not apply in this mode. fail-on-added with new-only is refused (exit 2).
Known gaps
Section titled “Known gaps”- On GitHub Enterprise Server without code scanning, set
upload-sarif: false; GHES has not been tested. - The reusable workflow (
.github/workflows/keryn-scan-reusable.yml,new-onlydefaulting to true) forwards onlyversion, which the action rejects. Use the composite action with a staged tarball as shown above.