# This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 # This workflow is managed by gh actions-lock. # Hypatia Neurosymbolic CI/CD Security Scan — Reusable Workflow (DEPRECATED for new repos, comment only: the template runs this scan inline) name: Hypatia Reusable Scan on: workflow_call: inputs: block-on-high: description: Refuse current high or critical findings after validated baseline filtering; no baseline is required type: boolean required: false default: false block-on-critical: description: >- Refuse current critical findings only: Hypatia's, after the same baseline and scope filtering as block-on-high, and panic-attack's, where a scan that did not run cannot pass. For callers that block on critical today and are not yet ready to block on high. block-on-high takes precedence for Hypatia when both are set. type: boolean required: false default: false scope-excludes: description: >- Comma-separated path prefixes that are reported but NEVER graded, and whose SARIF is not uploaded: frozen history that cannot be edited without falsifying the record. Default 9-archive/ -- matching the CodeQL config, which already ignores the same tree. Set to an empty string to grade everything. type: string required: false default: "9-archive/" inherited-language-paths: description: >- For a real fork only. Path, in the caller's repository, of a list of exact file paths received from the fork's upstream (one per line, `#` comments allowed). The `cicd_rules/banned_language_file` finding on each listed path is reported but NEVER graded or gated, and its SARIF is not uploaded. Every other rule on those files is unchanged. Only TypeScript, JavaScript and ReScript paths are accepted; an unusable list fails the job. Empty (the default) excuses nothing. type: string required: false default: "" sarif-upload-on-pull-request: description: >- Upload the SARIF to code scanning on pull_request events. Default true. Set false where this lane is advisory on pull requests: an upload there creates a separate "Code scanning results" check that can block a merge while this job passes. Push and manual runs still upload. The findings artifact and the verdict grid are unchanged. type: boolean required: false default: true report-backs-artifact: description: >- Name of an artifact, uploaded earlier in the same run, holding the gitbot-fleet report-back envelopes (one .json each; produced by hyperpolymath/gitbot-fleet fleet-report-back-reusable.yml). It is downloaded into a fresh directory under the runner's temp directory, outside the checkout, before the verdict grid renders, so each enrolled member's row carries its evidence instead of "enrolled, but no report-back was received". A missing artifact is tolerated and leaves those rows orange. Set to an empty string to skip the download; the renderer then reads an empty directory, never the checkout. type: string required: false default: "fleet-report-backs" previous-grid-artifact: description: >- Optional trusted prior PR grid artifact, produced by a read-scoped caller job earlier in this same workflow run. No PR read permission is requested by this reusable; existing callers remain compatible. type: string required: false default: "" hypatia-ref: description: >- Hypatia commit to build the scanner from. Defaults to a vetted SHA so a bad hypatia main cannot turn every caller red at once (09-12..14 and 09-26..30 outages). Canary callers pass "HEAD" to trial the tip before the default is moved here. type: string required: false default: adb2f41db34156cf81b2508f6596a10c7f076098 panic-ref: description: panic-attack commit (40-hex SHA or HEAD for an explicit canary). type: string required: false default: cbf2b935ef4260cc3ae66010f4ffc91385ff8f8c pons-ref: description: pons asinorum commit (40-hex SHA or HEAD for an explicit canary). type: string required: false default: bca1ea289a4f8a86bac6212731e6f8ec15c67ad4 hypatia-advisory: description: >- Include below-threshold advisory findings (`advisory: true` at low or info: WF026, WF027, latent RE011) in the findings JSON, so the verdict grid lists them under "JSON-only below-threshold advisories". JSON only: the SARIF projection and both gates read medium and above and are unchanged. Default true (owner decision 2026-11-17), because a flag-only finding that no grid shows is not flagged. Set false to keep them out of the JSON. type: boolean required: false default: true secrets: HYPATIA_SCAN_PAT: description: >- Fine-grained read-only PAT used to read Dependabot, code-scanning and secret-scanning alerts; the scan falls back to the built-in GITHUB_TOKEN when it is not supplied. Declared explicitly so callers pass ONLY this secret instead of `secrets: inherit`, which forwarded every caller secret (standards#1108 §6b). required: false outputs: verdict: description: >- Overall state of the lane's verdict grid, computed over GATING rows only (docs/VERDICT-GRID-SPEC.adoc): purple, red, orange, yellow, blue, green or grey. Advisory rows are reported in the grid and in `advisory`, and never set this. value: ${{ jobs.scan.outputs.verdict }} advisory: description: >- Advisory rows in the report, as `::`, or `none` when the lane has no advisory reporter. Empty when the grid did not render. Callers show this beside the verdict so that an advisory critical is visible WITHOUT being able to grade the change. value: ${{ jobs.scan.outputs.advisory }} permissions: actions: read contents: read security-events: write jobs: scan: name: Hypatia Neurosymbolic Analysis runs-on: ubuntu-latest # 30 + 10 + 5: the panic-attack build is capped at 10 minutes and its scan # at 5, so a slow build or a hung scan records "not_run" or "error" instead # of timing out, and so failing, the whole job. timeout-minutes: 45 outputs: verdict: ${{ steps.grid.outputs.state }} advisory: ${{ steps.grid.outputs.advisory }} steps: - name: Checkout repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 persist-credentials: false - name: Setup Elixir for Hypatia scanner # OTP 28.x (28.1 to 28.5.0.8) segfaults the Hypatia scanner and oracle # in sweep_off_heap on some trees; OTP 27.3.4.19 is clean on all of them # (rsr-template-repo#333 and #339; hyperpolymath/hypatia#1061). uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1 with: elixir-version: '1.19.4' otp-version: '27.3.4.19' - name: Resolve Hypatia scanner commit id: hypatia-rev env: HYPATIA_REF: ${{ inputs.hypatia-ref }} run: | # The scanner is PINNED (input hypatia-ref, default a vetted SHA). Only # an explicit "HEAD" floats, for canary callers. Resolved before the # cache step because the cache key must hash the commit. if [ "$HYPATIA_REF" = "HEAD" ]; then sha=$(git ls-remote https://github.com/hyperpolymath/hypatia.git HEAD | cut -f1) else sha="$HYPATIA_REF" fi if [[ ! "$sha" =~ ^[0-9a-f]{40}$ ]]; then echo "ERROR: hypatia-ref must be a 40-hex commit SHA or HEAD (got: $HYPATIA_REF)" >&2 exit 1 fi echo "sha=$sha" >> "$GITHUB_OUTPUT" echo "Resolved Hypatia commit: $sha" - name: Resolve advisory scanner commits env: PANIC_REF: ${{ inputs.panic-ref }} PONS_REF: ${{ inputs.pons-ref }} run: | set -euo pipefail resolve() { local label="$1" ref="$2" url="$3" sha if [ "$ref" = HEAD ]; then sha=$(git ls-remote "$url" HEAD | cut -f1) else sha="$ref" fi if [[ ! "$sha" =~ ^[0-9a-f]{40}$ ]]; then echo "::error::$label must be a 40-hex commit SHA or HEAD" >&2 exit 1 fi printf '%s' "$sha" } panic=$(resolve panic-ref "$PANIC_REF" https://github.com/hyperpolymath/panic-attack.git) pons=$(resolve pons-ref "$PONS_REF" https://github.com/hyperpolymath/pons-asinorum.git) # The resolved commits, not HEAD or unvalidated input, key caches, # cargo installs, status envelopes, and the grid's profile. printf 'PANIC_ATTACK_SHA=%s\nPONS_SHA=%s\n' "$panic" "$pons" >> "$GITHUB_ENV" echo "Resolved panic-attack: $panic; pons: $pons" - name: Cache Hex/Mix and Scanner Build uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: | ~/.mix ~/.hex ~/hypatia # Source-pinned key: when Hypatia main advances, the SHA changes, the # cache misses, and the clone + escript build below re-run instead of # restoring a stale binary. The old keyless `...-build` key meant the # first scanner ever cached was reused forever, so scanner fixes (e.g. # SD022, hypatia#545) never reached CI. No restore-keys on purpose — # a partial restore would repopulate ~/hypatia and the guards below # would then skip the rebuild, reintroducing the staleness. key: hypatia-scanner-v4-${{ runner.os }}-otp27.3.4.19-${{ steps.hypatia-rev.outputs.sha }} - name: Check out resolved Hypatia commit env: HYPATIA_SHA: ${{ steps.hypatia-rev.outputs.sha }} run: | set -euo pipefail if [ ! -d "$HOME/hypatia" ]; then git init "$HOME/hypatia" git -C "$HOME/hypatia" remote add origin https://github.com/hyperpolymath/hypatia.git git -C "$HOME/hypatia" fetch --depth 1 origin "$HYPATIA_SHA" git -C "$HOME/hypatia" checkout --detach FETCH_HEAD fi # A cache is usable only when its source matches the key, including # on cache hits. v4 invalidates caches populated by the moving clone. ACTUAL_SHA=$(git -C "$HOME/hypatia" rev-parse HEAD) if [ "$ACTUAL_SHA" != "$HYPATIA_SHA" ]; then echo "::error::Hypatia cached source does not match the resolved commit" exit 1 fi - name: Build Hypatia scanner run: | set -euo pipefail cd "$HOME/hypatia" # JSON comes from the escript, but the single-scan SARIF projection # also needs the compiled upstream module. A partial cache with only # an executable cannot safely skip the Mix build. sarif_beam="_build/${MIX_ENV:-dev}/lib/hypatia/ebin/Elixir.Hypatia.SARIF.beam" if [ ! -x hypatia ] || [ ! -f "$sarif_beam" ]; then if ! (mix deps.get && mix escript.build); then echo "::error::Hypatia scanner build failed at commit $(git rev-parse HEAD) — see upstream hyperpolymath/hypatia" exit 1 fi fi if [ ! -x hypatia ] || [ ! -f "$sarif_beam" ]; then echo "::error::Hypatia scanner binary or compiled SARIF renderer is missing after build" exit 1 fi - name: Run Hypatia scan env: # The scanner reads a single env var, GITHUB_TOKEN, to pull Dependabot, # code-scanning and secret-scanning alerts (lib/rules/{dependabot, # code_scanning,secret_scanning}_alerts.ex). Without it those three # checks are skipped with "GITHUB_TOKEN not set" warnings. # # Prefer a fine-grained, read-only PAT (HYPATIA_SCAN_PAT, passed by # the caller as this reusable's one declared secret): the built-in # Actions token CANNOT read Dependabot alerts (no `dependabot` # permission exists for it). Fall back to the built-in token so # code-scanning still works in repos where the PAT isn't present yet. GITHUB_TOKEN: ${{ secrets.HYPATIA_SCAN_PAT || secrets.GITHUB_TOKEN }} HYPATIA_ADVISORY: ${{ inputs.hypatia-advisory }} run: | set -euo pipefail echo "Scanning repository: ${GITHUB_REPOSITORY:-}" # Collect once, including opt-in advisory JSON below the fixed medium # threshold. The alert APIs may change between scans; projecting one # captured list is the only way JSON and SARIF describe the same run. HYPATIA_FORMAT=json HYPATIA_SEVERITY=medium \ "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json if ! jq -se 'length == 1 and (.[0] | type == "array" and all(.[]; type == "object" and (.severity as $s | ["critical", "high", "medium", "warn", "low", "info", "informational"] | index($s) != null)))' \ hypatia-findings.json >/dev/null; then echo "::error::Hypatia did not produce one valid findings array" exit 2 fi # Use the scanner's OWN SARIF renderer (including its self-echo filter, # fingerprints and URI semantics), not a second implementation. JSON # advisory extras below medium are excluded from this projection, so # opt-in cannot alter uploads or either baseline gate. Attach original # severity/line/class as SARIF properties for truthful grid grading; # this does not change result level, fingerprint or gate semantics. export SCAN_ROOT="$PWD" FINDINGS_PATH="$PWD/hypatia-findings.json" ( cd "$HOME/hypatia" mix run --no-start --no-compile -e ' root = System.fetch_env!("SCAN_ROOT") findings = System.fetch_env!("FINDINGS_PATH") |> File.read!() |> Jason.decode!() gated = Enum.filter(findings, &(&1["severity"] in ["critical", "high", "medium", "warn"])) document = Hypatia.SARIF.from_findings(gated, root) run = hd(document["runs"]) # Ask the authoritative renderer which inputs it suppresses as # meta-findings. Verify correspondence before annotating; future # changes must fail, never zip unrelated findings together. pairs = Enum.flat_map(gated, fn finding -> case Hypatia.SARIF.from_findings([finding], root)["runs"] |> hd() |> Map.fetch!("results") do [] -> [] [result] -> [{result, finding}] _ -> raise "unexpected SARIF projection" end end) unless Enum.map(pairs, &elem(&1, 0)) == run["results"], do: raise "SARIF projection mismatch" results = Enum.map(pairs, fn {result, finding} -> # The pinned code_safety normalizer puts its CWE in a fixed # generated reason suffix rather than a structured field. # Only recognise that exact format; arbitrary prose is not # sufficient identity for cross-reporter corroboration. cwe_from_safety = if finding["rule_module"] == "code_safety" and is_binary(finding["reason"]) do case Regex.run(~r/\([0-9]+ occurrences, (CWE-[0-9]+), line [0-9, ]*\)$/, finding["reason"]) do [_, cwe] -> cwe _ -> nil end end properties = Map.merge(result["properties"] || %{}, %{ "hypatia.severity" => finding["severity"], "hypatia.originalLine" => finding["line"], "hypatia.originalFile" => finding["file"], "hypatia.class" => case finding["cwe"] || finding["cwe_id"] do n when is_integer(n) -> "CWE-#{n}" nil -> finding["class"] || cwe_from_safety || finding["type"] cwe -> cwe end }) Map.put(result, "properties", properties) end) IO.puts(Jason.encode!(Map.put(document, "runs", [Map.put(run, "results", results)]), pretty: true)) ' ) > hypatia.sarif if [ ! -s hypatia.sarif ]; then echo "::error::Hypatia did not produce hypatia.sarif" exit 2 fi - name: Validate findings and count severities id: scan run: | set -euo pipefail # Exactly one JSON array of findings, each with a recognised severity. # Missing/truncated/multi-document output is a scanner error and fails # closed; a single well-formed `[]` is a valid clean scan when the # scanner step succeeded (standards#1054). if [ ! -s hypatia-findings.json ] || ! jq -e -s ' length == 1 and (.[0] | type == "array" and all(.[]; type == "object" and (.severity as $s | ["critical", "high", "medium", "warn", "low", "info", "informational"] | index($s) != null))) ' hypatia-findings.json >/dev/null; then echo "::error::Hypatia did not produce one valid findings array" exit 2 fi FINDING_COUNT=$(jq '. | length' hypatia-findings.json) CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json) HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json) # Hypatia's research rules use "warn" at the same rank as "medium". MEDIUM=$(jq '[.[] | select(.severity == "medium" or .severity == "warn")] | length' hypatia-findings.json) { echo "findings_count=$FINDING_COUNT" echo "critical=$CRITICAL" echo "high=$HIGH" echo "medium=$MEDIUM" } >> "$GITHUB_OUTPUT" { echo "## Hypatia Scan Results" echo "" echo "| Severity | Count |" echo "|----------|-------|" echo "| Critical | $CRITICAL |" echo "| High | $HIGH |" echo "| Medium | $MEDIUM |" echo "| **Total**| $FINDING_COUNT |" } >> "$GITHUB_STEP_SUMMARY" - name: Relativize finding paths run: | # Hoisted out of the gate step so the SARIF filter and the gate share # ONE definition of a finding's path. code_safety / honest_completion # emit ABSOLUTE host paths in .file (Path.expand(repo)) while the # baseline uses repo-relative paths; without this they never match # (hypatia#566 stopgap). if [ -f hypatia-findings.json ]; then jq --arg root "$PWD" ' map(if (.file? // "") == $root then .file = "." elif (.file? // "") | startswith($root + "/") then .file = (.file | ltrimstr($root + "/")) else . end) ' hypatia-findings.json > hypatia-findings.relativized.json jq 'map(select(.severity == "critical" or .severity == "high" or .severity == "medium" or .severity == "warn"))' \ hypatia-findings.relativized.json > hypatia-findings.gating.json fi # panic-attack is ADVISORY: it never fails this job, because this # reusable is called estate-wide and the owner has not made it a gate. # It is never silent either. Until 2026-10 nothing installed it, so the # old step wrote a bare `[]` that read exactly like a clean scan (the CRG # "panic-attack assail passes" evidence). It runs before the standards # checkout below so that it scans the caller's tree, not # .standards-checkout/scripts. - name: Restore panic-attack build cache uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: ~/.panic-attack key: panic-attack-v1-${{ runner.os }}-${{ runner.arch }}-${{ env.PANIC_ATTACK_SHA }} - name: Install panic-attack (pinned source build) id: panic-attack-install run: | set -euo pipefail # Every failure path sets `reason` and exits 0; the next step turns # that into status "not_run" in panic-attack-findings.json. root="$HOME/.panic-attack" bin="$root/bin/panic-attack" reason="" # cargo records the installed source in .crates.toml as # "...?rev=#". Use a restored binary only when it names the # pinned commit; otherwise rebuild. if [ -x "$bin" ] && grep -qF "#$PANIC_ATTACK_SHA" "$root/.crates.toml" 2>/dev/null; then echo "panic-attack restored from cache at $PANIC_ATTACK_SHA" elif ! command -v cargo >/dev/null 2>&1; then reason="cargo is not available on this runner" elif ! timeout 600 cargo install --git https://github.com/hyperpolymath/panic-attack \ --rev "$PANIC_ATTACK_SHA" --locked --force --root "$root" panic-attack; then reason="source build at $PANIC_ATTACK_SHA failed or exceeded 10 minutes" elif [ ! -x "$bin" ]; then reason="no binary after the source build at $PANIC_ATTACK_SHA" fi if [ -n "$reason" ]; then # Leave nothing for the cache to save from a failed build. rm -rf "$root" echo "::warning title=panic-attack not installed::$reason" echo "reason=$reason" >> "$GITHUB_OUTPUT" else echo "bin=$bin" >> "$GITHUB_OUTPUT" fi - name: Run panic-attack assail id: panic-attack env: PA_BIN: ${{ steps.panic-attack-install.outputs.bin }} PA_INSTALL_REASON: ${{ steps.panic-attack-install.outputs.reason }} SCOPE_EXCLUDES: ${{ inputs.scope-excludes }} # Only the summary wording depends on this; the gate is its own step. PA_GATES: ${{ inputs.block-on-critical }} run: | set -euo pipefail # panic-attack-findings.json is a status ENVELOPE, never a bare array: # status "ran" | "not_run" | "error" # tool, ref "panic-attack" and the pinned commit # reason why it did not run or failed; null when it ran # exit_code the assail exit code; null when it never started # counts unsuppressed {critical, high, medium, low} outside the # scope-excludes prefixes; null unless ran # counts_excluded the same, for findings under those prefixes # (frozen history: reported, never counted; standards#1306) # report panic-attack's own AssailReport; null unless ran # Only status "ran" carries a result. Anything else is not a pass. out=panic-attack-findings.json marker() { jq -n --arg status "$1" --arg reason "$2" --argjson exit_code "$3" \ --arg ref "$PANIC_ATTACK_SHA" '{status: $status, tool: "panic-attack", ref: $ref, reason: $reason, exit_code: $exit_code, counts: null, counts_excluded: null, report: null}' > "$out" } status=ran reason="" if [ -z "${PA_BIN:-}" ] || [ ! -x "$PA_BIN" ]; then status=not_run reason="${PA_INSTALL_REASON:-panic-attack is not installed}" marker not_run "$reason" null else report=$(mktemp) log=$(mktemp) rc=0 # The report goes to --output; stdout carries only a banner. timeout 300 "$PA_BIN" assail . --output "$report" > "$log" 2>&1 || rc=$? if [ "$rc" -eq 124 ]; then status=error reason="panic-attack assail did not finish within 5 minutes" marker error "$reason" "$rc" elif [ "$rc" -ne 0 ]; then status=error reason="panic-attack assail exited $rc" marker error "$reason" "$rc" elif ! jq -e -s 'length == 1 and (.[0] | type == "object" and (.weak_points | type == "array") and all(.weak_points[]; type == "object" and (.severity as $s | ["Low", "Medium", "High", "Critical"] | index($s) != null)))' \ "$report" > /dev/null 2>&1; then status=error reason="panic-attack assail exited 0 without a valid report" marker error "$reason" 0 else # A finding under a scope-excludes prefix is reported, never # counted, as the verdict grid already treats it. Paths arrive # repository-relative; a leading ./ is ignored. jq --arg ref "$PANIC_ATTACK_SHA" --arg ex "${SCOPE_EXCLUDES:-}" ' def tally($s): {critical: ($s | map(select(. == "Critical")) | length), high: ($s | map(select(. == "High")) | length), medium: ($s | map(select(. == "Medium")) | length), low: ($s | map(select(. == "Low")) | length)}; ($ex | split(",") | map(select(length > 0))) as $prefixes | def excluded: ((.file // .location // "") | ltrimstr("./")) as $p | $p != "" and any($prefixes[]; . as $x | $p | startswith($x)); [.weak_points[] | select(.suppressed != true)] as $live | {status: "ran", tool: "panic-attack", ref: $ref, reason: null, exit_code: 0, counts: tally([$live[] | select(excluded | not) | .severity]), counts_excluded: tally([$live[] | select(excluded) | .severity]), report: .}' "$report" > "$out" fi if [ "$status" = error ]; then echo "::group::panic-attack output" cat "$log" echo "::endgroup::" fi fi echo "status=$status" >> "$GITHUB_OUTPUT" if [ "$status" = ran ]; then critical=$(jq '.counts.critical' "$out") high=$(jq '.counts.high' "$out") medium=$(jq '.counts.medium' "$out") low=$(jq '.counts.low' "$out") excluded=$(jq '.counts_excluded | add' "$out") { echo "critical=$critical" echo "high=$high" } >> "$GITHUB_OUTPUT" # Advisory wording is unchanged for existing callers; with # block-on-critical the critical count gates in its own step. if [ "${PA_GATES:-false}" = true ]; then title="panic-attack findings (critical blocks)" note="Critical findings block (block-on-critical); high and below are advisory" heading="critical findings block" else title="panic-attack findings (advisory)" note="This scan does not gate" heading="advisory, does not gate" fi if [ $((critical + high)) -gt 0 ]; then echo "::warning title=$title::$critical critical and $high high finding(s). $note; see panic-attack-findings.json in the hypatia-scan-findings artifact." fi { echo "## panic-attack assail ($heading)" echo "" echo "| Severity | Count |" echo "|----------|-------|" echo "| Critical | $critical |" echo "| High | $high |" echo "| Medium | $medium |" echo "| Low | $low |" echo "" echo "Built from hyperpolymath/panic-attack@$PANIC_ATTACK_SHA. Findings panic-attack suppresses as likely false positives are not counted." if [ "$excluded" -gt 0 ]; then echo "" echo "$excluded more finding(s) sit under \`${SCOPE_EXCLUDES:-}\` (frozen history). They are in \`counts_excluded\` and not counted above." fi } >> "$GITHUB_STEP_SUMMARY" else if [ "$status" = error ]; then label=ERROR; else label="NOT RUN"; fi echo "::warning title=panic-attack $label::$reason. panic-attack-findings.json records status $status, which is not a pass." { echo "## panic-attack assail: $label" echo "" echo "**Status \`$status\`:** $reason." echo "" echo "No scan result was produced, so this is **not** a pass." echo "\`panic-attack-findings.json\` records \`\"status\": \"$status\"\`." } >> "$GITHUB_STEP_SUMMARY" fi # pons asinorum is ADVISORY on the same terms as panic-attack: a status # envelope (ran | not_run | error) that is never a bare pass, built from # source at PONS_SHA and cached by that commit. - name: Restore pons build cache uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 with: path: ~/.pons key: pons-v1-${{ runner.os }}-${{ runner.arch }}-${{ env.PONS_SHA }} - name: Install pons asinorum (pinned source build) id: pons-install run: | set -euo pipefail root="$HOME/.pons" bin="$root/bin/pons" reason="" if [ -x "$bin" ] && grep -qF "#$PONS_SHA" "$root/.crates.toml" 2>/dev/null; then echo "pons restored from cache at $PONS_SHA" elif ! command -v cargo >/dev/null 2>&1; then reason="cargo is not available on this runner" elif ! timeout 600 cargo install --git https://github.com/hyperpolymath/pons-asinorum \ --rev "$PONS_SHA" --locked --force --root "$root" pons-cli; then reason="source build at $PONS_SHA failed or exceeded 10 minutes" elif [ ! -x "$bin" ]; then reason="no binary after the source build at $PONS_SHA" fi if [ -n "$reason" ]; then rm -rf "$root" echo "::warning title=pons not installed::$reason" echo "reason=$reason" >> "$GITHUB_OUTPUT" else echo "bin=$bin" >> "$GITHUB_OUTPUT" fi - name: Run pons asinorum scan id: pons env: PONS_BIN: ${{ steps.pons-install.outputs.bin }} PONS_INSTALL_REASON: ${{ steps.pons-install.outputs.reason }} run: | set -euo pipefail # pons-findings.json is the same status envelope as panic-attack's; # `report` is pons's own JSON envelope when status is "ran". out=pons-findings.json marker() { jq -n --arg status "$1" --arg reason "$2" --argjson exit_code "$3" \ --arg ref "$PONS_SHA" '{status: $status, tool: "pons-asinorum", ref: $ref, reason: $reason, exit_code: $exit_code, counts: null, report: null}' > "$out" } if [ -z "${PONS_BIN:-}" ] || [ ! -x "$PONS_BIN" ]; then marker not_run "${PONS_INSTALL_REASON:-pons is not installed}" null else report=$(mktemp) log=$(mktemp) rc=0 timeout 300 "$PONS_BIN" scan --format json . > "$report" 2> "$log" || rc=$? if [ "$rc" -eq 124 ]; then marker error "pons scan did not finish within 5 minutes" "$rc" elif [ "$rc" -ne 0 ]; then marker error "pons scan exited $rc" "$rc" elif ! jq -e -s 'length == 1 and (.[0] | type == "object" and (.findings | type) == "array" and all(.findings[]; type == "object" and ((.severity | ascii_upcase) as $s | ["INFO", "WARN", "ERROR"] | index($s) != null)))' \ "$report" > /dev/null 2>&1; then marker error "pons scan exited 0 without a valid report" 0 else jq --arg ref "$PONS_SHA" ' [.findings[].severity | ascii_upcase] as $s | {status: "ran", tool: "pons-asinorum", ref: $ref, reason: null, exit_code: 0, counts: {error: ($s | map(select(. == "ERROR")) | length), warn: ($s | map(select(. == "WARN")) | length), info: ($s | map(select(. == "INFO")) | length)}, report: .}' "$report" > "$out" fi if [ "$(jq -r .status "$out")" = error ]; then echo "::group::pons output" cat "$log" echo "::endgroup::" fi fi status=$(jq -r .status "$out") echo "status=$status" >> "$GITHUB_OUTPUT" if [ "$status" = ran ]; then { echo "## pons asinorum scan (advisory, does not gate)" echo "" echo "| Severity | Count |" echo "|----------|-------|" jq -r '"| ERROR | \(.counts.error) |", "| WARN | \(.counts.warn) |", "| INFO | \(.counts.info) |"' "$out" echo "" echo "Built from hyperpolymath/pons-asinorum@$PONS_SHA. Each finding carries its tier and evidence class; a heuristic is labelled as one." } >> "$GITHUB_STEP_SUMMARY" else echo "::warning title=pons $status::$(jq -r .reason "$out"). pons-findings.json records status $status, which is not a pass." fi - name: Check out standards for the SARIF baseline filter id: fetch_filter # ⚠ continue-on-error is on the CHECKOUT, never on the check. If the # fetch fails the next step still runs and says so; putting the flag on # the filter itself would produce exactly the fake gate this estate # keeps finding. job.workflow_sha is this reusable's own immutable # revision; github.workflow_sha would resolve to the caller's SHA. # advisory-by-design, not fail-closed: this checkout fails OPEN. # "Filter SARIF through the baseline before upload" below falls back # to uploading the SARIF UNFILTERED when the fetched filter script is # unavailable — an unfiltered upload can only show more alerts, never # hide real ones. # hypatia: allow research_extensions/RE005 -- advisory-by-design, fails OPEN; see comment above. continue-on-error: true uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: metadatastician/standards persist-credentials: false # Baseline filtering and grid grading must use helpers from the # same immutable revision as this workflow, never a stale helper. ref: ${{ job.workflow_sha }} path: .standards-checkout sparse-checkout: | scripts sparse-checkout-cone-mode: false - name: Filter SARIF through the baseline before upload id: filter_baseline run: | # ⚠ WITHOUT THIS, ACKNOWLEDGING A FINDING DOES NOT UNBLOCK ANYTHING. # A finding travelled two paths that never met: the gate filtered # findings.json through the baseline, while the SARIF went to code # scanning UNFILTERED. The `code_scanning` ruleset rule blocks on # those alerts and has no knowledge of the baseline, so a pull # request stayed BLOCKED with every required check green and nothing # to point at. # # Measured 2026-08-07: 147 open pull requests across 91 repositories # were held this way by 1,777 alerts, ZERO of which were introduced # by the pull request they blocked. # # The filter FAILS OPEN in every error path — an unfiltered upload is # a safe failure, a silently over-filtered one hides real alerts. if [ -f .standards-checkout/scripts/filter-sarif-by-baseline.sh ]; then FILTER=.standards-checkout/scripts/filter-sarif-by-baseline.sh else # A caller-local copy could be older and over-suppress colliding # findings. Unfiltered is safe; the strict gate will fail closed # if a committed baseline lacks a verified filtering result. echo "::warning::revision-matched filter unavailable — SARIF uploaded unfiltered"; exit 0 fi # Use the CALLER's apply-baseline.sh — the same copy the gate runs, # so the SARIF and the gate cannot disagree about what is acknowledged. APPLY_BASELINE=scripts/apply-baseline.sh \ bash "$FILTER" hypatia.sarif hypatia-findings.gating.json .hypatia-baseline.json # ── Scope: keep frozen history out of code scanning ─────────────────── # Runs AFTER the baseline filter, so the two cannot disagree about which # results survive: the baseline removes acknowledged results, this removes # a declared out-of-scope prefix. A finding that is both is removed once # and by the second pass, which is idempotent. # # Fails OPEN: an unfiltered upload shows more alerts, never fewer. - name: Filter SARIF by declared scope id: filter_scope env: SCOPE_EXCLUDES: ${{ inputs.scope-excludes }} run: | set -uo pipefail # Preserve the baseline-filtered projection for reporting excluded # findings. The gate/upload continue to use only hypatia.sarif. if [ -s hypatia.sarif ] && ! cp hypatia.sarif hypatia.pre-scope.sarif; then rm -f hypatia.pre-scope.sarif echo "::warning::could not preserve pre-scope SARIF for excluded-finding inventory" fi [ -z "$SCOPE_EXCLUDES" ] && { echo " no scope exclusions declared"; exit 0; } if [ -f .standards-checkout/scripts/filter-sarif-by-scope.sh ]; then FILTER=.standards-checkout/scripts/filter-sarif-by-scope.sh else # Never run a caller-local or older filter against the blocking # SARIF. More visible findings are safer than silent suppression. echo " ::warning::revision-matched scope filter unavailable — SARIF uploaded unfiltered" exit 0 fi IFS=',' read -r -a _prefixes <<< "$SCOPE_EXCLUDES" bash "$FILTER" hypatia.sarif hypatia.sarif "${_prefixes[@]}" # ── Inherited-language paths of a real fork ──────────────────────────── # Runs AFTER the scope filter, so hypatia.pre-scope.sarif still holds the # findings and the grid can report them as excluded. Takes ONE rule off # the EXACT paths the caller declares, in both gating projections, so # the SARIF gate and the baseline gate cannot disagree. # # The LIST fails closed: a list that was asked for and is unusable is a # configuration error. The FILTERS fail open, like the two above. - name: Apply the inherited-language paths id: inherited_language if: ${{ inputs.inherited-language-paths != '' }} env: INHERITED_LANGUAGE_PATHS: ${{ inputs.inherited-language-paths }} run: | set -uo pipefail helper=.standards-checkout/scripts/inherited-language.sh if [ ! -f "$helper" ]; then # Never run a caller-local or older helper against the gating # projections. More visible findings are safer than suppression. echo "::warning::revision-matched inherited-language helper unavailable; nothing is excused" exit 0 fi list="$RUNNER_TEMP/inherited-language-paths.txt" if ! bash "$helper" paths "$INHERITED_LANGUAGE_PATHS" > "$list"; then echo "::error::the inherited-language path list '$INHERITED_LANGUAGE_PATHS' is unusable; see the message above" exit 2 fi echo " $(wc -l < "$list") inherited-language path(s) declared in $INHERITED_LANGUAGE_PATHS" bash "$helper" sarif hypatia.sarif hypatia.sarif "$list" bash "$helper" findings hypatia-findings.gating.json hypatia-findings.gating.json "$list" echo "list=$list" >> "$GITHUB_OUTPUT" - name: Upload SARIF to code scanning # NOTE: this does NOT make under-permissioned callers "skip gracefully". # This workflow declares `security-events: write` at the top, so a # caller granting only `read` is rejected at startup and NO step of # this job ever executes — `continue-on-error` cannot rescue a job # that was never created. Callers MUST grant `security-events: write`. # This flag only tolerates a genuine upload failure (e.g. Advanced # Security disabled on a private repo) once the job is actually running. # # A caller whose lane is advisory on pull requests sets # sarif-upload-on-pull-request to false; push and manual runs upload. if: ${{ inputs.sarif-upload-on-pull-request || github.event_name != 'pull_request' }} continue-on-error: true uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100) with: sarif_file: hypatia.sarif category: hypatia - name: Upload findings artifacts uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: hypatia-scan-findings path: | hypatia-findings.json hypatia.sarif hypatia.pre-scope.sarif panic-attack-findings.json pons-findings.json retention-days: 90 # ── VERDICT GRID (docs/VERDICT-GRID-SPEC.adoc) ────────────────────── # One table for the lane: Hypatia, panic-attack, pons and every # gitbot-fleet report-back under .gitbot-fleet/, graded by the worst # finding present, with missing or unreadable evidence orange and # explicit exclusions grey. It lands in the job summary, in the # verdict-grid artifact (report.json, report.md, badge.json) and in the # `verdict` output. The PR comment is the CALLER's job: this reusable # declares only the permissions every existing caller already grants, # and a called workflow may not ask for more than its caller. - name: Check out the verdict grid renderer at this workflow's commit if: ${{ always() }} # continue-on-error on the CHECKOUT only: the render step below # reports a missing renderer as orange, never as a pass. continue-on-error: true uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: metadatastician/standards # `job.workflow_sha`: the commit of THIS reusable file, i.e. what the # caller pinned. See ci-pipeline.yml for why neither # github.workflow_sha nor github.job_workflow_sha is that. ref: ${{ job.workflow_sha }} path: .standards-grid persist-credentials: false sparse-checkout: | scripts/verdict-grid.sh scripts/lib/verdict-grid.jq sparse-checkout-cone-mode: false # ── Scope: what the grid is allowed to GRADE ────────────────────────── # Without this the grid grades the whole repository, so its verdict is a # property of the REPOSITORY and not of the pull request: every revision # scores the same, and a comment that never changes is not read. Delta # mode grades only findings in files the change touches; everything else # is still counted and named in the comment, never hidden. # # Falls back to whole-repository scope when the base commit cannot be # resolved (a push, a force-push, a shallow clone). A fallback that # silently NARROWED the scope would be the dangerous direction; this one # only ever widens it. - name: Compute the change scope id: scope env: BASE_SHA: ${{ github.event.pull_request.base.sha || '' }} HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} SCOPE_EXCLUDES: ${{ inputs.scope-excludes }} run: | set -uo pipefail : > "$RUNNER_TEMP/changed.txt" mode=whole-repo case "$BASE_SHA" in '') : ;; *) if git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null || git fetch --quiet origin "$BASE_SHA" 2>/dev/null; then base=$(git merge-base "$BASE_SHA" "$HEAD_SHA" 2>/dev/null) || base="$BASE_SHA" if git diff --name-only "$base" "$HEAD_SHA" > "$RUNNER_TEMP/changed.txt" 2>/dev/null; then mode=delta fi fi ;; esac n=$(grep -c . "$RUNNER_TEMP/changed.txt" 2>/dev/null || true) echo "mode=$mode" >> "$GITHUB_OUTPUT" echo "scope: $mode (${n:-0} changed file(s), excluded: ${SCOPE_EXCLUDES:-none})" # Reading previous PR comments happens in an optional caller job with # pull-requests: read. This reusable never escalates permission demands # on existing cross-repository callers. - name: Download the previous PR grid (if provided) if: ${{ always() && github.event_name == 'pull_request' && inputs.previous-grid-artifact != '' }} continue-on-error: true uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: name: ${{ inputs.previous-grid-artifact }} path: ${{ runner.temp }}/hypatia-pr-history - name: Prepare the prior PR baseline if: ${{ always() && github.event_name == 'pull_request' }} env: PREVIOUS_GRID_ARTIFACT: ${{ inputs.previous-grid-artifact }} run: | set -euo pipefail : > "$RUNNER_TEMP/grid-previous.md" candidate="$RUNNER_TEMP/hypatia-pr-history/grid-previous.md" if [ -s "$candidate" ]; then # The caller must have selected only its trusted bot's comment. if grep -Fq '' \ "🟠 indeterminate · $1; see the job log." > verdict-grid/report.md cat verdict-grid/report.md >> "$GITHUB_STEP_SUMMARY" echo "state=orange" >> "$GITHUB_OUTPUT" } if [ ! -f "$renderer" ]; then indeterminate 'the verdict grid renderer could not be checked out from metadatastician/standards' exit 0 fi findings=hypatia-findings.json [ -f hypatia-findings.relativized.json ] && findings=hypatia-findings.relativized.json enrolment="" [ -f .gitbot-fleet/enrolment.json ] && enrolment=.gitbot-fleet/enrolment.json # The renderer appends the grid to the step summary and writes # state= to GITHUB_OUTPUT itself; its exit code is 0 for any # rendered verdict and 2 only for a usage error. # Scope: delta when the change scope step resolved a base commit, # whole-repository otherwise. A missing changed.txt with mode=delta # is a usage error inside the renderer, not a silent fallback. scope_args=() [ "${SCOPE_MODE:-}" = "delta" ] && scope_args+=(--changed "$RUNNER_TEMP/changed.txt") if [ -f .hypatia-baseline.json ] && [ "${BASELINE_FILTERED:-}" != true ]; then scope_args+=(--hypatia-baseline-unverified) fi # Prefixes from the caller; empty means grade everything. When scope # excludes are used, report from the pre-scope projection as well; # it contributes excluded counts only, never gate/grade findings. if [ -n "${SCOPE_EXCLUDES:-}" ] || [ -n "${INHERITED_LANGUAGE_LIST:-}" ]; then scope_args+=(--hypatia-sarif-unscoped hypatia.pre-scope.sarif) fi # The same normalised list the gating filters used. if [ -n "${INHERITED_LANGUAGE_LIST:-}" ]; then scope_args+=(--inherited-language-paths "$INHERITED_LANGUAGE_LIST") fi IFS=',' read -r -a _ex <<< "${SCOPE_EXCLUDES:-}" for _p in "${_ex[@]}"; do [ -n "$_p" ] && scope_args+=(--exclude-prefix "$_p") done if ! bash "$renderer" render --out verdict-grid \ --hypatia "$findings" --hypatia-sarif hypatia.sarif --panic panic-attack-findings.json --pons pons-findings.json \ --report-backs "${REPORT_BACKS_DIR:-}" --enrolment "$enrolment" \ --previous "$RUNNER_TEMP/grid-previous.md" \ --sha "$HEAD_SHA" --run "$GITHUB_RUN_ID" \ --url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" \ --pr "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" \ --hypatia-ref "$HYPATIA_REF" --panic-ref "${PANIC_ATTACK_SHA:-}" --pons-ref "${PONS_SHA:-}" \ "${scope_args[@]}" > /dev/null; then indeterminate 'the verdict grid renderer failed' exit 0 fi # Advisory summary, for callers that show it beside the verdict. The # verdict output is written by the renderer and covers GATING rows # only; without this a caller would state "green" and omit the four # advisory criticals sitting directly beneath it. if [ ! -s verdict-grid/report.json ] || ! adv=$(jq -er ' if (.advisory | type) != "object" or (.advisory.rows | type) != "number" then error("missing advisory summary") elif .advisory.rows == 0 then "none" else "\(.advisory.state):\(.advisory.critical):\(.advisory.high)" end' verdict-grid/report.json); then indeterminate 'the verdict grid renderer produced no readable report' exit 0 fi echo "advisory=$adv" >> "$GITHUB_OUTPUT" - name: Upload the verdict grid if: ${{ always() }} uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: verdict-grid path: verdict-grid if-no-files-found: error retention-days: 90 - name: Gate on baseline (blocking when a baseline is committed) if: '!inputs.block-on-high && steps.scan.outputs.findings_count > 0' run: | # Wave-8 gate promotion: when the calling repo commits a # .hypatia-baseline.json (schema: .machine_readable/hypatia-baseline. # schema.json) AND ships scripts/apply-baseline.sh, findings are # filtered against the baseline and any UNBASELINED finding at or # above the blocking threshold FAILS this job. Repos without a # baseline keep the honest ADVISORY behaviour below — the gate arms # itself the moment a baseline lands (standards#399/#437/#446). if [ -f scripts/apply-baseline.sh ] && [ -f .hypatia-baseline.json ]; then echo "Baseline present — running BLOCKING gate (threshold: high)." # Paths were relativized in an earlier step so the SARIF filter and # this gate agree on what a finding's path is. Two definitions of # "the same finding" is how the baseline came to mean one thing to # the gate and nothing to the security tab. bash scripts/apply-baseline.sh hypatia-findings.gating.json .hypatia-baseline.json blocking else echo "No committed baseline — gate stays advisory (see next step)." fi - name: Block findings at the requested threshold id: blocking-findings if: inputs.block-on-high || inputs.block-on-critical env: HYPATIA_BASELINE_FILTERED: ${{ steps.filter_baseline.outputs.filtered }} BLOCK_THRESHOLD: ${{ inputs.block-on-high && 'high' || 'critical' }} run: | set -euo pipefail # high: every error-level result (SARIF folds high and critical into # "error"). critical: error-level results whose projected # hypatia.severity is critical, or is missing, since an unknown # severity must not slip under a critical-only gate. case "${BLOCK_THRESHOLD:-high}" in high) selector='.level == "error"' what="high or critical" ;; critical) selector='.level == "error" and ((.properties // {})["hypatia.severity"] // "") != "high"' what="critical" ;; *) echo "::error::Unknown blocking threshold '${BLOCK_THRESHOLD}'" exit 2 ;; esac # Use the scanner's authoritative SARIF projection, after the same # baseline filter used for the Security tab. Raw JSON also contains # code_scanning_alerts: historical GitHub alert summaries, including # alerts fixed by this PR that cannot close until it reaches main. # Hypatia already excludes those meta-rules in its SARIF renderer. # Counting them here creates a circular merge dependency. Raw JSON # remains in the artifact for the fleet's historical-debt review. # Validate a present baseline even when there are no current errors. # Advisory mode validates without gating historical meta-findings; # the final filtered SARIF below supplies the blocking decision. if [ -f .hypatia-baseline.json ]; then if [ ! -f scripts/apply-baseline.sh ]; then echo "::error::A committed baseline requires scripts/apply-baseline.sh" exit 2 fi bash scripts/apply-baseline.sh hypatia-findings.gating.json .hypatia-baseline.json advisory >/dev/null if [ "${HYPATIA_BASELINE_FILTERED:-}" != "true" ]; then echo "::error::Baseline validation passed but SARIF filtering did not complete" exit 2 fi fi # Missing/truncated output must never become a clean security gate. if ! jq -se ' length == 1 and (.[0] | .version == "2.1.0" and (.runs | type == "array" and length > 0) and all(.runs[]; .tool.driver.name == "Hypatia" and (.results | type == "array") and all(.results[]; type == "object" and (.ruleId | type == "string" and length > 0) and ((.properties | type) == "object" or .properties == null) and ((.locations | type) == "array" or .locations == null) and ((.message | type) == "object" or .message == null) and (try ((.locations[0].physicalLocation.artifactLocation.uri // "") | type == "string") catch false) and (try ((.message.text // "") | type == "string") catch false) and (.level as $level | ["error", "warning", "note", "none"] | index($level) != null)))) ' hypatia.sarif >/dev/null; then echo "::error::Hypatia did not produce one valid SARIF findings document" exit 2 fi count=$(jq "[.runs[].results[] | select($selector)] | length" hypatia.sarif) if [ "$count" -gt 0 ]; then echo "::error::Hypatia found $count current $what finding(s); see the SARIF artifact" exit 1 fi echo "Hypatia blocking gate: no current $what findings after baseline filtering" - name: Block panic-attack critical findings when requested id: blocking-panic if: inputs.block-on-critical env: PA_STATUS: ${{ steps.panic-attack.outputs.status }} PA_CRITICAL: ${{ steps.panic-attack.outputs.critical }} run: | set -euo pipefail # A blocking gate cannot pass on a scan that did not run: not_run and # error fail here, where the advisory mode only reports them. if [ "${PA_STATUS:-}" != ran ]; then echo "::error::panic-attack did not run (status ${PA_STATUS:-missing}); the critical gate cannot pass without its scan" exit 2 fi if ! [[ "${PA_CRITICAL:-}" =~ ^[0-9]+$ ]]; then echo "::error::panic-attack ran but reported no critical count" exit 2 fi if [ "$PA_CRITICAL" -gt 0 ]; then echo "::error::panic-attack found $PA_CRITICAL critical finding(s); see panic-attack-findings.json" exit 1 fi echo "panic-attack blocking gate: no critical findings" - name: Check for critical issues (ADVISORY — does not gate) if: '!inputs.block-on-high && !inputs.block-on-critical && steps.scan.outputs.critical > 0' run: | # This scan is ADVISORY / fix-forward WHEN NO BASELINE IS COMMITTED # (the step above becomes the blocking gate once .hypatia-baseline.json # lands). The label and summary state that explicitly so a green check # carrying critical findings is not mistaken for "no critical findings". echo "::warning title=Hypatia (ADVISORY, non-blocking)::${{ steps.scan.outputs.critical }} critical finding(s). This scan does not gate — review hypatia-findings.json and fix forward." { echo "### Hypatia scan — ADVISORY (does not gate)" echo "" echo "**${{ steps.scan.outputs.critical }} critical finding(s)** reported." echo "This scan is fix-forward and **never fails the build**; a green" echo "check here does not mean zero critical findings. See the" echo "\`hypatia-scan-findings\` artifact. Blocking promotion: standards#399/#437." } >> "$GITHUB_STEP_SUMMARY"