diff --git a/.github/workflows/escript-soundness.yml b/.github/workflows/escript-soundness.yml index 7753d630..ba93706f 100644 --- a/.github/workflows/escript-soundness.yml +++ b/.github/workflows/escript-soundness.yml @@ -163,6 +163,14 @@ jobs: fi echo "Consumer-shaped invocation produced $(jq 'length' consumer.json) findings." + # The wrapper the consumers call must stay as transparent as the `exec` + # it replaced (stdout, stdin, exit codes, forwarded SIGTERM, death by + # the child's signal), and must name an Erlang VM crash on stderr instead + # of leaving callers a bare "exit 139". Fake escripts, no build needed. + - name: hypatia-cli.sh passes exits through and names a VM crash + working-directory: source + run: bash tests/hypatia-cli-signal-test.sh + # HYP-01: every finding in CI output names its support. The schema's # self-test runs first, so a schema that accepts everything cannot # pass: it must refuse a pattern finding that claims "sound" (and six diff --git a/hypatia-cli.sh b/hypatia-cli.sh index 87e4470b..5f429bdd 100755 --- a/hypatia-cli.sh +++ b/hypatia-cli.sh @@ -94,11 +94,79 @@ elif escript_is_stale; then fi fi +# ─── Run the escript, naming a VM crash ──────────────────────────────── + +# A crash signal is the Erlang VM dying, not a scan result. Hypatia loads no +# NIFs, so a SIGSEGV here is the BEAM itself (the known case is the PinSites +# miscompile, #1062). Callers see only "exit 139", and that reads as a +# scanner fault or a finding about the scanned repository. +# report_vm_crash prints the signal and the OTP/erts version to stderr only +# (stdout carries the JSON/SARIF payload). +# otp_version prints the OTP release from the installation's OTP_VERSION +# file and the erts version from `erl +V`; neither starts a shell or +# evaluates code. +otp_version() { + local erl root otp erts + erl="$(command -v erl 2>/dev/null)" || { echo unknown; return 0; } + root="$(cd "$(dirname "$(readlink -f "${erl}")")/.." 2>/dev/null && pwd)" || root="" + otp="$(cat "${root}"/releases/*/OTP_VERSION 2>/dev/null | head -n 1)" || otp="" + erts="$(erl +V 2>&1 | sed -n 's/.*emulator version //p')" || erts="" + echo "${otp:-unknown} (erts ${erts:-unknown})" +} + +report_vm_crash() { + local status="$1" sig name otp + sig=$(( status - 128 )) + name="$(kill -l "${sig}" 2>/dev/null || echo "${sig}")" + otp="$(otp_version)" + { + echo "[hypatia] The Erlang VM running the scanner (beam.smp) was killed by SIG${name} (exit ${status}) on OTP ${otp}." + echo "[hypatia] This is a runtime crash: no scan result was produced, and it is not a finding about the scanned repository." + echo "[hypatia] Re-running on the same input and runtime crashes again. Report the OTP version above; see ci_failure_triage 'toolchain_segfault'." + } >&2 +} + +# run_escript runs the escript as a child so its exit can be read, and stays +# transparent to callers as `exec` was: stdin, stdout and stderr pass +# through, TERM/INT/HUP are forwarded, the exit code is returned unchanged, +# and a child killed by a signal ends this script by the same signal. The +# caller's shell therefore still reports "Segmentation fault … hypatia-cli.sh", +# which the `toolchain_segfault` triage rule matches. +run_escript() { + local child status=0 sig + "${ESCRIPT}" "$@" <&0 & + child=$! + trap 'kill -TERM "${child}" 2>/dev/null' TERM + trap 'kill -INT "${child}" 2>/dev/null' INT + trap 'kill -HUP "${child}" 2>/dev/null' HUP + # `wait` returns early (>128) when a forwarded signal interrupts it; wait + # again until the child has actually exited. + while :; do + status=0 + wait "${child}" || status=$? + kill -0 "${child}" 2>/dev/null || break + done + trap - TERM INT HUP + if (( status > 128 )); then + sig=$(( status - 128 )) + case "$(kill -l "${sig}" 2>/dev/null)" in + SEGV|BUS|ABRT|ILL) report_vm_crash "${status}" ;; + # TERM, INT, HUP, KILL and the rest end a run on purpose (CI + # cancellation, timeout): not a crash, so no report. + *) ;; + esac + trap - "${sig}" 2>/dev/null || true + kill -"${sig}" $$ + fi + return "${status}" +} + # ─── Forward arguments ───────────────────────────────────────────────── if [[ -x "${ESCRIPT}" ]]; then # Pass HYPATIA_FORMAT / HYPATIA_SEVERITY through the environment - exec "${ESCRIPT}" "$@" + run_escript "$@" + exit $? elif [[ -x "${BASH_FALLBACK}" ]]; then echo "[hypatia] Warning: escript not built, falling back to bash scanner." >&2 exec "${BASH_FALLBACK}" "$@" diff --git a/test/fixtures/ci_failure_triage/hypatia-cli-vm-crash-report.txt b/test/fixtures/ci_failure_triage/hypatia-cli-vm-crash-report.txt new file mode 100644 index 00000000..e6ada1a7 --- /dev/null +++ b/test/fixtures/ci_failure_triage/hypatia-cli-vm-crash-report.txt @@ -0,0 +1,3 @@ +[hypatia] The Erlang VM running the scanner (beam.smp) was killed by SIGSEGV (exit 139) on OTP 28.3.3 (erts 16.2.2). +[hypatia] This is a runtime crash: no scan result was produced, and it is not a finding about the scanned repository. +[hypatia] Re-running on the same input and runtime crashes again. Report the OTP version above; see ci_failure_triage 'toolchain_segfault'. diff --git a/test/rules/ci_failure_triage_test.exs b/test/rules/ci_failure_triage_test.exs index c222794d..11cdb041 100644 --- a/test/rules/ci_failure_triage_test.exs +++ b/test/rules/ci_failure_triage_test.exs @@ -41,6 +41,9 @@ defmodule Hypatia.Rules.CiFailureTriageTest do # missing a ref (this-ssg), canon lockstep (EpistemicTypes.jl, dictask), # stale REPOSITORY-MAP (dictask), superseded deed (rsr-template-repo#337). {"hypatia-cli-segfault.txt", "toolchain_segfault", :owner}, + # hypatia-cli.sh's own VM-crash report, without the caller shell's + # "Segmentation fault" line (tests/hypatia-cli-signal-test.sh). + {"hypatia-cli-vm-crash-report.txt", "toolchain_segfault", :owner}, {"hypatia-critical-findings.txt", "security_findings_reported", :owner}, {"lock-missing-ref.txt", "actions_lock_missing_ref", :fix}, {"lock-missing-pin.txt", "actions_lock_missing_ref", :fix}, diff --git a/tests/hypatia-cli-signal-test.sh b/tests/hypatia-cli-signal-test.sh new file mode 100755 index 00000000..340dd82e --- /dev/null +++ b/tests/hypatia-cli-signal-test.sh @@ -0,0 +1,98 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell +# +# Contract of hypatia-cli.sh around the escript it runs: callers see what +# `exec` used to give them, plus a named report when the Erlang VM crashes. +# +# 1. stdout and the exit code pass through unchanged (0 and 3), with no +# report on stderr; +# 2. stdin reaches the escript; +# 3. an escript killed by SIGSEGV: a report on stderr names the signal, +# stdout stays empty, and the wrapper itself dies by SIGSEGV (exit 139), +# so the caller's shell still prints "Segmentation fault … hypatia-cli.sh" +# for the `toolchain_segfault` triage rule; +# 4. SIGTERM sent to the wrapper reaches the escript, and the escript's +# own exit code comes back (no orphaned scan); +# 5. an escript killed by SIGTERM: the wrapper dies by SIGTERM (143), with +# no crash report. +# +# Each case runs a copy of hypatia-cli.sh next to a fake `hypatia` escript. +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +work="$(mktemp -d)" +trap 'rm -rf -- "${work}"' EXIT +fail=0 + +pass() { printf 'PASS: %s\n' "$1"; } +bad() { printf 'FAIL: %s\n' "$1" >&2; fail=1; } + +# setup_case NAME BODY: a directory holding hypatia-cli.sh and a fake escript +# whose script body is BODY. Prints the wrapper path. +setup_case() { + local dir="${work}/$1" + mkdir -p "${dir}" + cp "${root}/hypatia-cli.sh" "${dir}/hypatia-cli.sh" + printf '#!/usr/bin/env bash\n%s\n' "$2" > "${dir}/hypatia" + chmod +x "${dir}/hypatia-cli.sh" "${dir}/hypatia" + printf '%s\n' "${dir}/hypatia-cli.sh" +} + +export HYPATIA_NO_STALE_REBUILD=1 + +# 1. Pass-through of stdout and exit codes. +w="$(setup_case ok 'echo "[]"; exit 0')" +out="$("${w}" scan . 2>"${work}/ok.err")" && rc=0 || rc=$? +[[ "${rc}" == 0 && "${out}" == "[]" && ! -s "${work}/ok.err" ]] \ + && pass "exit 0 and stdout pass through, no report" \ + || bad "exit 0 case: rc=${rc} out=${out} err=$(cat "${work}/ok.err")" + +w="$(setup_case three 'exit 3')" +"${w}" secret-alerts >/dev/null 2>"${work}/three.err" && rc=0 || rc=$? +[[ "${rc}" == 3 && ! -s "${work}/three.err" ]] \ + && pass "exit 3 passes through, no report" \ + || bad "exit 3 case: rc=${rc} err=$(cat "${work}/three.err")" + +# 2. stdin reaches the escript. +w="$(setup_case stdin 'cat')" +out="$(printf 'hello\n' | "${w}")" +[[ "${out}" == "hello" ]] && pass "stdin reaches the escript" || bad "stdin case: out=${out}" + +# 3. A VM crash: named on stderr, and the wrapper dies by the same signal. +w="$(setup_case segv 'kill -SEGV $$')" +outer="$(bash -c '"$1" scan . > "$2" 2> "$3"; echo "rc=$?"' _ "${w}" "${work}/segv.out" "${work}/segv.err" 2>"${work}/segv.outer")" +if [[ "${outer}" == "rc=139" ]] \ + && grep -q 'beam.smp) was killed by SIGSEGV (exit 139)' "${work}/segv.err" \ + && [[ ! -s "${work}/segv.out" ]] \ + && grep -q 'Segmentation fault' "${work}/segv.outer"; then + pass "SIGSEGV: reported on stderr, stdout empty, wrapper dies by SIGSEGV (139)" +else + bad "SIGSEGV case: ${outer}; err=$(cat "${work}/segv.err"); outer stderr=$(cat "${work}/segv.outer")" +fi + +# 4. SIGTERM to the wrapper reaches the escript; its exit code comes back. +w="$(setup_case term_handled 'trap "exit 42" TERM; sleep 30 & wait')" +"${w}" scan . 2>"${work}/th.err" & wpid=$! +sleep 1 +kill -TERM "${wpid}" +wait "${wpid}" && rc=0 || rc=$? +if [[ "${rc}" == 42 ]] && ! pgrep -f "${work}/term_handled/hypatia" >/dev/null; then + pass "SIGTERM is forwarded; the escript's exit code (42) comes back" +else + bad "SIGTERM forwarding case: rc=${rc}" +fi + +# 5. An escript killed by SIGTERM: the wrapper dies by SIGTERM, no report. +w="$(setup_case term_default 'exec sleep 30')" +"${w}" scan . 2>"${work}/td.err" & wpid=$! +sleep 1 +kill -TERM "${wpid}" +wait "${wpid}" && rc=0 || rc=$? +if [[ "${rc}" == 143 && ! -s "${work}/td.err" ]] && ! pgrep -f "${work}/term_default" >/dev/null; then + pass "escript killed by SIGTERM: wrapper exits 143, no crash report" +else + bad "SIGTERM default case: rc=${rc} err=$(cat "${work}/td.err")" +fi + +exit "${fail}"