zizmor

name	zizmor
description	Audit GitHub Actions workflows with zizmor and explain reported hits using bundled trust-boundary references.
license	MIT
compatibility	Requires `zizmor` (https://github.com/zizmorcore/zizmor) and `python3` on PATH. Reads bundled GitHub Actions security references from `./references`; no external network access is needed.
metadata	{"scrutineer.version":1,"scrutineer.output_file":"report.json","scrutineer.output_kind":"findings","scrutineer.model":"mid"}

zizmor

Run zizmor against ./src/.github/workflows, then explain each reported issue from the surrounding workflow and its effective trust boundary. The converter decides which findings exist; the reference pack helps make their exploit chain, impact, and remediation precise.

Workspace

• ./src — the cloned repository
• ./scripts/scan.py — the wrapper
• ./references — GitHub Actions attack-pattern and false-positive guidance
• ./zizmor.json — intermediate findings emitted by the wrapper
• ./report.json — write the findings report here
• ./schema.json — output shape

Available scripts

• scripts/scan.py — invokes zizmor --no-exit-codes --format json .github/workflows and converts the output. If the repo has no workflows directory, it writes an empty result so the scan succeeds cleanly. zizmor's severity values are mapped to scrutineer's: unknown/informational/low → Low, medium → Medium, high → High, critical → Critical.

References

Read only the files relevant to each hit:

• references/expression-injection.md for untrusted ${{ }} expressions in shell, script, workflow-command, manual-input, and reusable-workflow contexts.
• references/privileged-pr-context.md for pull_request_target and other privileged jobs that materialize pull-request content.
• references/comment-commands.md for chatops authorization and approval-to-checkout TOCTOU.
• references/reusable-and-indirect-flows.md for workflow_call, workflow_run, local actions, artifacts, and caches crossing trust boundaries.
• references/permissions-secrets-runners.md for token scopes, secrets, OIDC, ArtiPACKED, caches, and self-hosted runners.
• references/supply-chain.md for mutable third-party action or reusable-workflow references and runtime downloads.
• references/examples.md for positive and negative examples that help distinguish an exploitable chain from hardening advice.

The references are review guidance, not evidence that the target is vulnerable. A finding's evidence must come from files under ./src and the locations emitted by zizmor.

What to do

python3 scripts/scan.py > ./zizmor.json

The script handles missing workflows directories, a missing zizmor binary, and zizmor's non-zero "I found something" exit code gracefully — don't add retry or error handling on top.

If zizmor.json contains an error or has no findings, copy it unchanged to report.json and stop.

For every finding in zizmor.json:

1. Preserve its id, title, severity, location, locations, and zizmor documentation reference exactly. Do not add, remove, merge, or reclassify findings.
2. Read every cited workflow location plus enough surrounding YAML to identify the trigger, permissions, secrets, checkout ref, action inputs, and commands involved. Follow repository-local reusable workflows, composite actions, and scripts only when the reported path depends on them.
3. Load the relevant reference files listed above. Apply their false-positive controls as well as their attack patterns.
4. Replace trace with a concise, source-grounded explanation of the complete chain: attacker-controlled input or mutable dependency, the interpreter or trust-boundary crossing, the privileges or secrets exposed, and the resulting operation. State any unresolved link instead of assuming it.
5. Replace rating with a concise justification for the preserved severity, tied to the actual token permissions, secrets, OIDC rights, artifact visibility, runner trust, or write capability present in this repository. If impact depends on configuration outside the repository, say so explicitly.

Do not turn generic hardening advice into a vulnerability. In particular, do not claim exploitation from broad permissions, a mutable action tag, pull_request_target, workflow_run, a self-hosted runner, or interpolation alone unless the checked-in workflow establishes the corresponding untrusted path and meaningful impact. Do not invent cloud trust policies, repository settings, secret values, or caller behavior that is not visible in ./src.

Write the enriched object to ./report.json and validate it against ./schema.json using the validation endpoint described in the system prompt.