The scan output JSON — shape of $FINDINGS
scripts/run.py --out "$FINDINGS" writes this file, and it is the
orchestrator's source of truth for every later phase of
SKILL.md. Never re-parse the markdown report to make a
decision the JSON can answer.
Contents
One finding object
findings is a list, one object per occurrence (occurrences are grouped by
pattern for rendering and dispatch, not stored grouped).
{
"id": "f1",
"pattern": "P14.9",
"severity": "HIGH",
"title": "Fork code executed with privileges in bench.yml",
"workflow_file": ".github/workflows/bench.yml",
"line": 8,
"affected_jobs": ["bench"],
"workflow_activity": {"runs_30d": 218, "last_run": "...", "dormant": false},
"evidence": " 8: job `bench` on `pull_request_target` checks out `${{ github.event.pull_request.head.sha }}` then executes from the tree <-- here",
"fix_strategy": "switch-to-pull-request-or-drop-head-checkout",
"fix_guidance": "Optional evidence-specific guidance when this occurrence needs a narrower fix than the catalog default.",
"fix_recipe_anchor": "p149--fork-code-executed-with-privileges"
}workflow_activity has three shapes, and they are not interchangeable.
The one above is the enriched success case. {} means no enrichment was
attempted — --repo was not passed. {"status": "unavailable", "reason": ...}
means enrichment WAS attempted and failed. The last one must never be read as
"active": the dormancy flag is simply absent, so a failed check looks identical
to a live workflow unless the distinction is kept. Dormancy drives a mandatory
note in the report and the all fix selection, so read the report's rendered
dormancy state rather than inferring one from a missing flag.
P14.18 findings only also carry actions_can_approve_prs: GitHub's
"Allow GitHub Actions to create and approve pull requests" repository setting
(can_approve_pull_request_reviews from
GET repos/{owner}/{repo}/actions/permissions/workflow), read once per scan
when a P14.18 finding exists. state is "true", "false" or "unread",
and detail says where the answer came from or why it could not be read (no
--repo, gh not signed in, an API error). It is never guessed: an unread
setting renders as "not checked" in the finding's reference block and as a
sentence under "What an attacker could do then".
"actions_can_approve_prs": {"state": "true", "detail": "read from the repository's Actions settings"}The attacker_scenario merged in at Phase 2.5
The one usually non-scripted field. Written once per
(pattern, severity, fix_strategy) profile and merged onto every member of
that profile, so a group that mixes a detector-lowered profile with the
catalog one gets one object per profile; the report shows the group's most
exposed profile. One field per plain section the report renders at the top
of the finding, in this order (rules per field:
scenario-authoring.md):
{
...,
"attacker_scenario": {
"what_it_does": "Runs the benchmark suite on every pull request and posts the timings as a comment.",
"why_flagged": "It is started by pull requests from forks, runs with this repo's write pass and secrets, and then runs the pull request's own code.",
"what_must_go_wrong": "Nothing hard:\n- anyone with a GitHub account can open a fork pull request;\n- the job checks out that pull request's code and runs its install step.\nNo prior access to the repo is needed.",
"attacker_could": "Their install step runs holding the repo's write pass and secrets, so they could push commits or read every secret the job has.",
"verdict": "High: any stranger can reach it today.",
"how_to_close": "1. Run the benchmark on `pull_request` instead, where fork runs get no secrets and a read-only pass.\n2. If the comment must stay, post it from a second workflow that never runs the pull request's code."
}
}A field may also be a list of strings (one line each). A single string —
from an older run, or supplied by the scanner itself (P14.18's MEDIUM
cosmetic profile) — is still accepted and renders under "What an attacker
could do then" alone; tests/verify_report.py then counts that finding as
not repo-specific, exactly like the catalog's generic stand-in. So Phase 2.5
keeps a scanner-supplied string's claim as that profile's attacker_could
and replaces the string with the full object.
Top-level blocks
gh_checks— per-network-gated-check status,P14.11above all:ran/partial/skippedplus the detail (pin counts, or the reason). An ABSENTP14.11key is the "not recorded" state — a coverage hole, never a pass.P14.24is present only when the scan reached a GitHub CLI extension pinned to a tag and then run: the release-immutability lookup'sran/partial/skippedstatus, e.g.ran: 2 tag-pinned GitHub CLI extension install(s) looked up, 1 immutable (not reported), 1 reported. This lookup can only remove a finding, so apartialorskippedone means some tag-pinned findings were kept without being checked, never that a finding is missing. Its absence means no such install was reached.gh_check_details— the per-check detail apartialstatus refers to, including the unresolved-pin list (forP14.24, eachowner/repo@tag (file:line) — reasonthat was not looked up).gh_checksgives the status word; this is where the specifics live.scan_incomplete— workflow files skipped or unreadable, with a reason each. Non-empty means coverage is PARTIAL.dropped_matchesandcoverage_notes— the other two coverage channels. Coverage iscompleteonly when all THREE ofscan_incomplete,dropped_matchesandcoverage_notesare empty (report.py's_coverage_is_complete). Readingscan_incompletealone will call a degraded run complete, which is the one thing the coverage rule forbids. The rendered report already applies all three, which is why Phase 3 copies itsCoverage:line rather than recomputing one.suppressed_findings— matches the engine deliberately withheld, with the reason each was withheld. Not a coverage gap, but not nothing either.parallel_steps—steps_scanned(steps read inside GitHub Actionsparallel:groups),control_steps(wait:/wait-all:/cancel:, which hold no code),background_steps(top-level steps written with anybackground:value but a literalfalse; a child of aparallel:group is counted insteps_scannedonly, background or not) and theworkflowsholding at least one of those counted steps. The key is always present (all zeros for a repository without the syntax). Informational, never a coverage gap: the leaf steps counted were scanned like any other; control steps hold no code. Aparallel:group or background step the walker cannot fully read as written lands incoverage_notesinstead, taggedscope: "parallel-group": a group whose value is not a list, nested past the depth cap, carryingrun:/uses:besideparallel:, holding an entry that is not a step, carrying a key the scan does not model (anything butparallel:,if:,name:,id:,continue-on-error:,background:), re-entering itself through a YAML alias, or past the walk's entry budget; abackground:value chosen at run time; or a job whose concurrent steps' source lines could not be found. Its file is not listed inworkflowsunless it also holds counted steps. Parallel steps are a github.com / GitHub Enterprise Cloud feature; the scan reads the syntax wherever it appears.action_lockfile— the GitHub Actions workflow lockfile (.github/workflows/actions.lock):path(a case variant such asActions.lockis named as it is on disk),state(absent,valid, orinvalidfor a file that is not exactly that name, a symbolic link, unreadable, unparseable, a format version the scan does not recognize, or holding any malformed entry — invalid credits nothing),covered_references(step-leveluses:occurrences not pinned to a full commit, in scanned workflows the lockfile lists, that it locks to a commit; repeats count, and a reusable-workflow call is never counted because the lockfile does not pin one) andcovered_workflows. The key is always present. Informational, never a coverage gap: GitHub verifies each locked commit at run time, and P14.11 checks only commit pins written inuses:, so these are the references P14.11 leaves to GitHub. The report states them on its Action lockfile row.security_score— present in the JSON and never rendered. Phase 3 forbids a score, ratio orN/100anywhere the user sees. It is listed here so it is recognized as out of bounds rather than mistaken for a summary worth surfacing. Itsfactsrows ARE rendered (the hygiene table), and so is one unscored key inside it,security_score.push_access, which the report shows under "If a push credential leaks":status—measured/unmeasured(the environment list could not be read) /not_checked(no repository, no token, or the settings or verdicts could not be computed at all), withreason; in the shape a crashed facts layer leaves,token_noteis absent.environments— one object per environment:name,managed(GitHub-managedgithub-pages/copilot),branch_checkandbranch_check_why(pass/fail/unmeasured, orinfofor a managed environment that is not judged),approval_checkandapproval_check_why(pass/fail/not_applicable/info),reviewers(count),has_rules(a branch policy or required reviewers exist) andadmins_can_bypass(information only, never part of a verdict; the report notes it only wherehas_rulesis true, on an environment that is not GitHub-managed).inventory— the secret list behind thesec.secrets.environment-scopedrow:status(measured/partial/unmeasured/not_checked),repo_secretsandorg_secrets(lists of secret NAMES, ornullwhen that list could not be read —nullis never "none"),high_value(a sort hint, not a severity) andreason.tier1_gapandcredential_note— the two sentences every run states when this layer completes (empty when it crashed): what is not checked yet, and the OIDC exposure.token_note— one sentence linking GitHub's docs on which credentials can add or change workflow files. The three facts themselves aresec.environments.branch-restricted,sec.environments.approval-holdsandsec.secrets.environment-scopedinfacts, like any other.
timings— script-owned spans. Asrun.py --outwrites them at Phase 2:run_start_epoch,activity_enrich_s,scan_total_s,scripted_end_epoch,scripted_total_s.total_run_sis NOT there yet —report.pycomputes and writes it back at Phase 3, which is why Phase 6 composes itsTiming:line from THIS block only after the render has happened. There is noTiming:line in the rendered report to copy; the only such string in the scripts is a stderr debug log.record_timing.pyappends the orchestrator-measuredfixes_s.- Provenance, also top-level:
commit_sha,repo_tree_dirty,skill_commit_sha,skill_tree_dirtyandcatalog_patterns_evaluated.