Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/escript-soundness.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
70 changes: 69 additions & 1 deletion hypatia-cli.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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}" "$@"
Expand Down
Original file line number Diff line number Diff line change
@@ -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'.
3 changes: 3 additions & 0 deletions test/rules/ci_failure_triage_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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},
Expand Down
98 changes: 98 additions & 0 deletions tests/hypatia-cli-signal-test.sh
Original file line number Diff line number Diff line change
@@ -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}"
Loading