diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 82bf115..d7e97c8 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -28,3 +28,8 @@ permissions: jobs: hypatia: uses: metadatastician/standards/.github/workflows/hypatia-scan-reusable.yml@46ee18323305d5b36e2eef936e47dd54c39ea736 + with: + # The scanner the verdict grid names (fork-governance.yml and + # verdict-grid-publish.yml, --hypatia-ref). Without it the reusable runs + # its own default (adb2f41 at 46ee183), not the commit the grid claims. + hypatia-ref: be98f74ce93df200752f3798efa1305bfa3e0e10 diff --git a/scripts/check-workflow-edges.sh b/scripts/check-workflow-edges.sh index 6ab1fa7..edd6596 100755 --- a/scripts/check-workflow-edges.sh +++ b/scripts/check-workflow-edges.sh @@ -21,6 +21,11 @@ # they are not. # * One tool pinned at two different commits in two workflows is a clash, not # a choice: whichever workflow ran last decides what the grid graded. +# * A producer may delegate its scan to a job-level reusable-workflow call. +# Then the artifact and the scanner pin live in the CALLED workflow, read +# here at the full SHA the call pins (network, or EDGES_REUSABLE_DIR), and +# the pin is the one the call passes (`with: hypatia-ref:`): a call that +# passes none runs the reusable's own default, not the verdict's pin. # # Every check here is a rule about the pipeline's shape, not about the code # under test, which is why it belongs beside `check-required-contexts.sh` in the @@ -29,7 +34,8 @@ # Exit contract (proven-tests-and-benches 3-outcome convention): # 0 = every edge resolves and no tool is pinned twice # 1 = a dead edge, an unproduced artifact, a stale pin, or a duplicate tool pin -# 2 = setup error (missing repo, workflows dir, or the reporter workflow) +# 2 = setup error (missing repo, workflows dir, or the reporter workflow; a +# reusable producer not pinned to a full SHA, or not readable) # # Deliberately NOT checked: that a producer's gate is "right". Gating is each # producer's own decision (see the header of fork-governance.yml); this script @@ -95,6 +101,59 @@ env_pin() { ' "$1" } + +# reusable_calls FILE — every job-level reusable-workflow call in FILE +# (`uses: OWNER/REPO/.github/workflows/X.yml@REF` outside every job's `steps:` +# block), one per line. A producer may delegate its scan to such a call, and +# the artifact it uploads and the scanner it pins then live in the called +# workflow, not in FILE. +reusable_calls() { + awk ' + BEGIN { stepind = -1 } + { line = $0; sub(/[[:space:]]+#.*$/, "", line) } + line ~ /[^[:space:]]/ { + match(line, /^[[:space:]]*/); ind = RLENGTH + if (stepind >= 0 && ind <= stepind) stepind = -1 + if (line ~ /^[[:space:]]*steps:/) stepind = ind + } + stepind < 0 && line ~ /^[[:space:]]+uses:[[:space:]]*["\047]?[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/\.github\/workflows\/[^[:space:]@]+\.ya?ml@/ { + sub(/^[[:space:]]*uses:[[:space:]]*/, "", line); gsub(/["\047]/, "", line); sub(/[[:space:]]+$/, "", line) + print line + } + ' "$1" +} + +# reusable_source CALL — prints the path of a local copy of the called +# workflow, read at the commit the call pins. Only a full 40-hex SHA is +# followed: a tag or branch could move between this check and the run. +# EDGES_REUSABLE_DIR (the tests) supplies copies offline as +# /OWNER/REPO/SHA/PATH; otherwise raw.githubusercontent.com serves them. +# A call that cannot be read is a setup error (exit 2), never a pass: the edge +# through it would be unverified. +reusable_cache="$(mktemp -d)" +reusable_source() { + local call="$1" spec ref owner repo path out + spec="${call%@*}"; ref="${call##*@}" + owner="${spec%%/*}"; spec="${spec#*/}"; repo="${spec%%/*}"; path="${spec#*/}" + if [[ ! "$ref" =~ ^[0-9a-f]{40}$ ]]; then + echo "check-workflow-edges: reusable call '${call}' is not pinned to a full commit SHA; what it uploads and pins cannot be checked" >&2 + return 2 + fi + out="$reusable_cache/$owner/$repo/$ref/$path" + if [ ! -f "$out" ]; then + mkdir -p "$(dirname "$out")" + if [ -n "${EDGES_REUSABLE_DIR:-}" ]; then + if ! cp "$EDGES_REUSABLE_DIR/$owner/$repo/$ref/$path" "$out" 2>/dev/null; then + echo "check-workflow-edges: reusable '${call}' is not in EDGES_REUSABLE_DIR" >&2 + return 2 + fi + elif ! curl -fsSL --retry 3 --max-time 30 "https://raw.githubusercontent.com/$owner/$repo/$ref/$path" -o "$out"; then + echo "check-workflow-edges: could not read reusable '${call}' at its pinned commit; the edge through it cannot be verified" >&2 + return 2 + fi + fi + printf '%s' "$out" +} # ── 1. workflow_run edges resolve to a workflow `name:` ───────────────────── # `workflow_run: workflows:` is a YAML list under the trigger. Read it as text: # the file is under this repository's control and a YAML parser is one more @@ -115,7 +174,7 @@ if [ -z "$edges" ]; then fi names_file="$(mktemp)" -trap 'rm -f "$names_file"' EXIT +trap 'rm -rf "$names_file" "$reusable_cache"' EXIT for wf in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do [ -e "$wf" ] || continue n="$(workflow_name "$wf")" @@ -157,7 +216,14 @@ while IFS= read -r src; do continue fi if ! produced_artifacts "$target" | grep -qxF "$artifact"; then - fail "evidence source '${wf_file}:${artifact}' names an artifact '${wf_file}' never uploads" + # The producer may delegate to a reusable workflow, which then uploads it. + via="" + while IFS= read -r call; do + [ -n "$call" ] || continue + src="$(reusable_source "$call")" || exit 2 + if produced_artifacts "$src" | grep -qxF "$artifact"; then via="$call"; break; fi + done <<< "$(reusable_calls "$target")" + [ -n "$via" ] || fail "evidence source '${wf_file}:${artifact}' names an artifact '${wf_file}' never uploads" fi if ! grep -Eq '^[[:space:]]+pull_request:' "$target"; then fail "'${wf_file}' does not run on pull_request, so its artifact exists only after a push" @@ -168,25 +234,35 @@ done <<< "$sources" # Tool pin in the reporter (grid identity) vs the pin in the workflow that # actually runs that tool. A mismatch makes the profile hash disagree with the # binary that produced the findings. -check_pin() { # check_pin REPORTER REPORT_FLAG PRODUCER VAR - local report="$1" flag="$2" producer="$3" var="$4" - local in_reporter in_producer +check_pin() { # check_pin REPORTER REPORT_FLAG PRODUCER VAR [INPUT] + # INPUT: when PRODUCER delegates to a reusable workflow, the input through + # which it passes the pin; the reusable's own default is not the verdict's. + local report="$1" flag="$2" producer="$3" var="$4" input="${5:-}" + local in_reporter in_producer pin_name="$var" in_reporter="$({ grep -o -- "${flag}[[:space:]]\\+[0-9a-f]\\{40\\}" "$report" || true; } | awk '{print $2}' | head -n1)" in_producer="$(env_pin "$WORKFLOWS_DIR/$producer" "$var" | head -n1)" if [ -z "$in_reporter" ]; then fail "$(basename "$report") names no ${flag}; its findings would carry no tool identity" return fi + if [ -z "$in_producer" ] && [ -n "$input" ] && [ -n "$(reusable_calls "$WORKFLOWS_DIR/$producer")" ]; then + in_producer="$(env_pin "$WORKFLOWS_DIR/$producer" "$input" | head -n1)" + pin_name="with: $input" + if [ -z "$in_producer" ]; then + fail "'${producer}' calls a reusable workflow without passing ${input}, so the scan runs that workflow's default, not the ${flag} ${in_reporter:0:12} the verdict claims; pass 'with: ${input}: '" + return + fi + fi if [ -z "$in_producer" ]; then fail "'${producer}' pins no ${var}, but the verdict claims ${flag} ${in_reporter:0:12}" return fi if [ "$in_reporter" != "$in_producer" ]; then - fail "${flag} in $(basename "$report") (${in_reporter:0:12}) does not match ${var} in ${producer} (${in_producer:0:12})" + fail "${flag} in $(basename "$report") (${in_reporter:0:12}) does not match ${pin_name} in ${producer} (${in_producer:0:12})" fi } for report in "$REPORTER" "$PUBLISHER"; do - check_pin "$report" --hypatia-ref hypatia-scan.yml HYPATIA_SHA + check_pin "$report" --hypatia-ref hypatia-scan.yml HYPATIA_SHA hypatia-ref check_pin "$report" --panic-ref static-analysis-gate.yml PANIC_ATTACK_SHA check_pin "$report" --pons-ref static-analysis-gate.yml PONS_SHA done @@ -196,7 +272,7 @@ done # pair must agree, which is why both use env.PANIC_ATTACK_SHA. A literal second # pin in another workflow is the clash this catches. pins_file="$(mktemp)" -trap 'rm -f "$names_file" "$pins_file"' EXIT +trap 'rm -rf "$names_file" "$pins_file" "$reusable_cache"' EXIT for wf in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do [ -e "$wf" ] || continue for var in HYPATIA_SHA HYPATIA_REF PANIC_ATTACK_SHA PONS_SHA; do @@ -207,6 +283,14 @@ for wf in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do esac printf '%s\t%s\t%s\n' "$var" "$v" "$(basename "$wf")" >> "$pins_file" done + # A reusable call's hypatia-ref input pins the same scanner as HYPATIA_SHA. + if [ -n "$(reusable_calls "$wf")" ]; then + v="$(env_pin "$wf" hypatia-ref | head -n1)" + case "$v" in + "" | *'${{'* | 'latest' | 'HEAD') ;; + *) printf '%s\t%s\t%s\n' HYPATIA_SHA "$v" "$(basename "$wf") (with: hypatia-ref)" >> "$pins_file" ;; + esac + fi done while IFS= read -r var; do [ -n "$var" ] || continue diff --git a/tests/workflows/workflow_edges_test.sh b/tests/workflows/workflow_edges_test.sh index f6ad127..c6370fc 100755 --- a/tests/workflows/workflow_edges_test.sh +++ b/tests/workflows/workflow_edges_test.sh @@ -158,8 +158,14 @@ says "the publisher-specific diagnostic explains the missing rows" "published gr fresh >/dev/null # A different step's name cannot stand in for an upload-artifact output name. -sed -i 's/name: hypatia-scan-findings$/name: hypatia-scan-findings-backup/' "$WORK/repo/.github/workflows/hypatia-scan.yml" -printf '\n - name: hypatia-scan-findings\n run: true\n' >> "$WORK/repo/.github/workflows/hypatia-scan.yml" +# The producer here is a local-upload job written by the test, so the control +# holds whatever shape this repository's hypatia-scan.yml has (a minted child +# may delegate its scan to a reusable workflow, section 10). +wf="$WORK/repo/.github/workflows/hypatia-scan.yml" +grid_pin="$(grep -o -- '--hypatia-ref [0-9a-f]\{40\}' "$WORK/repo/.github/workflows/fork-governance.yml" | head -n1 | awk '{print $2}')" +awk '/^jobs:/ { exit } { print }' "$wf" > "$wf.new" +printf 'jobs:\n scan:\n runs-on: ubuntu-latest\n env:\n HYPATIA_SHA: %s\n steps:\n - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9\n with:\n name: hypatia-scan-findings-backup\n path: out\n - name: hypatia-scan-findings\n run: true\n' "$grid_pin" >> "$wf.new" +mv "$wf.new" "$wf" expect_rc 1 "an artifact prefix or unrelated step name cannot satisfy the source edge" says "the diagnostic requires an actual artifact upload" "never uploads" @@ -173,6 +179,60 @@ rm "$WORK/repo/.github/workflows/verdict-grid-publish.yml" expect_rc 2 "a missing trusted publisher is a setup error" says "the missing publisher is named" "publisher workflow" + +echo "=== 10. A producer that delegates to a reusable workflow ===" +# Offline: the called workflow is served from EDGES_REUSABLE_DIR, never fetched. +HSHA="$(grep -o -- '--hypatia-ref [0-9a-f]\{40\}' "$REPO_DIR/.github/workflows/fork-governance.yml" | head -n1 | awk '{print $2}')" +RSHA=1111111111111111111111111111111111111111 +REUSABLES="$WORK/reusables" +# delegate [WITH] — replace hypatia-scan.yml's jobs with one reusable call. +delegate() { + local wf="$WORK/repo/.github/workflows/hypatia-scan.yml" ref="${2:-$RSHA}" + awk '/^jobs:/ { exit } { print }' "$wf" > "$wf.new" + printf 'jobs:\n hypatia:\n uses: owner/standards/.github/workflows/scan.yml@%s\n' "$ref" >> "$wf.new" + [ -z "${1:-}" ] || printf ' with:\n hypatia-ref: %s\n' "$1" >> "$wf.new" + mv "$wf.new" "$wf" +} +# reusable [ARTIFACT] — the called workflow at RSHA, uploading ARTIFACT. +reusable() { + local dir="$REUSABLES/owner/standards/$RSHA/.github/workflows" + rm -rf "$REUSABLES"; mkdir -p "$dir" + printf 'on:\n workflow_call:\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9\n with:\n name: %s\n path: out\n' "${1:-hypatia-scan-findings}" > "$dir/scan.yml" +} +export EDGES_REUSABLE_DIR="$REUSABLES" + +fresh >/dev/null; reusable; delegate "$HSHA" +expect_rc 0 "a reusable producer passing the verdict's pin resolves both edges" + +fresh >/dev/null; reusable; delegate +expect_rc 1 "a reusable producer that passes no hypatia-ref is caught" +says "the failure says the default runs instead" "without passing hypatia-ref" + +fresh >/dev/null; reusable; delegate 2222222222222222222222222222222222222222 +expect_rc 1 "a reusable producer passing a different pin is caught" +says "the mismatch names the input it read" "with: hypatia-ref" + +fresh >/dev/null; reusable other-artifact; delegate "$HSHA" +expect_rc 1 "a reusable that does not upload the evidence artifact is caught" +says "the failure names the missing artifact" "never uploads" + +fresh >/dev/null; reusable; delegate "$HSHA" v1 +expect_rc 2 "a reusable call pinned to a tag cannot be followed (setup error)" +says "the failure asks for a full SHA" "full commit SHA" + +fresh >/dev/null; rm -rf "$REUSABLES"; mkdir -p "$REUSABLES"; delegate "$HSHA" +expect_rc 2 "an unreadable reusable is a setup error, never a pass" +says "the failure names the unreadable call" "not in EDGES_REUSABLE_DIR" + +fresh >/dev/null; reusable; delegate "$HSHA" +cat >> "$WORK/repo/.github/workflows/hypatia-scan.yml" <<'YML' + local: + runs-on: ubuntu-latest + steps: + - uses: owner/standards/.github/workflows/scan.yml@2222222222222222222222222222222222222222 +YML +expect_rc 0 "a step action with a workflow-shaped path is not followed as a reusable call" +unset EDGES_REUSABLE_DIR echo "" if [ "$fail" -ne 0 ]; then echo "FAIL: workflow edges suite (${pass} passed, ${fail} failed)" >&2