From abde3a74781369a7f903915027792afa7635a51b Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 03:04:10 +0200 Subject: [PATCH] refactor: expose readable root analyzer --- README.md | 2 +- analyse.sh | 129 ++++++++++++++++++++++++++++++++++++ docs/diagnostic-contract.md | 2 +- docs/standalone.md | 2 +- tests/test_analyse.py | 4 +- tests/test_shell_runtime.py | 2 +- tools/analyse-all.sh | 2 +- tools/analyse.sh | 25 ------- 8 files changed, 136 insertions(+), 32 deletions(-) create mode 100755 analyse.sh delete mode 100755 tools/analyse.sh diff --git a/README.md b/README.md index a8638a5..89547bc 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Win Diagnostics turns stored Windows captures into versioned, traceable ## Analyse one capture ```bash -bash tools/analyse.sh capture.json \ +./analyse.sh capture.json \ --evidence-root /path/to/evidence \ --output diagnostic.json \ --reference-time 2026-09-15T12:00:00Z \ diff --git a/analyse.sh b/analyse.sh new file mode 100755 index 0000000..3c55f82 --- /dev/null +++ b/analyse.sh @@ -0,0 +1,129 @@ +#!/usr/bin/env bash +set -euo pipefail + +root=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P) + +usage() { + cat >&2 <&2 + exit 1 +} + +sha256_file() { + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$1" | awk '{print $1}' + elif command -v sha256 >/dev/null 2>&1; then + sha256 -q "$1" + else + openssl dgst -sha256 "$1" | awk '{print $NF}' + fi +} + +require_value() { + (($# >= 2)) || usage +} + +input=${1:-} +[[ -n "$input" ]] || usage +shift + +evidence_root= +output= +reference_time= +producer_version= +force=false + +while (($#)); do + case $1 in + --evidence-root) + require_value "$@" + evidence_root=$2 + shift 2 + ;; + --output) + require_value "$@" + output=$2 + shift 2 + ;; + --reference-time) + require_value "$@" + reference_time=$2 + shift 2 + ;; + --producer-version) + require_value "$@" + producer_version=$2 + shift 2 + ;; + --force) + force=true + shift + ;; + *) + usage + ;; + esac +done + +for value in "$evidence_root" "$output" "$reference_time" "$producer_version"; do + [[ -n "$value" ]] || usage +done + +[[ ! -L "$input" ]] || fail "input symlinks are not supported" +input=$(realpath "$input") +evidence_root=$(realpath "$evidence_root") + +output_parent=$(dirname "$output") +mkdir -p "$output_parent" +output=$(cd "$output_parent" && pwd -P)/$(basename "$output") + +[[ "$input" == "$evidence_root"/* ]] || fail "input must be inside --evidence-root" +[[ "$input" != "$output" ]] || fail "input and output paths must differ" +[[ ! -e "$output" || "$force" == true ]] || fail "$output: output exists; use --force to replace it" + +artifact=${input#"$evidence_root/"} +artifact_hash=$(sha256_file "$input") +temporary=$(mktemp "$(dirname "$output")/.${output##*/}.XXXXXXXX") +stage=$(mktemp -d "${TMPDIR:-/tmp}/win-diagnostics.XXXXXXXX") +trap 'rm -f "$temporary"; rm -rf "$stage"' EXIT + +cp "$input" "$stage/capture.json" +cp "$root/rules/event-rules.json" "$stage/event-rules.json" +cp "$root/rules/watchlist.json" "$stage/watchlist.json" +cp "$root/tools/analyse.typ" "$stage/analyse.typ" + +typst query \ + --root "$stage" \ + --input capture=capture.json \ + --input rules=event-rules.json \ + --input watchlist=watchlist.json \ + --input "artifact=$artifact" \ + --input "artifact-hash=$artifact_hash" \ + --input "reference-time=$reference_time" \ + --input "producer-version=$producer_version" \ + "$stage/analyse.typ" \ + '' \ + --field value \ + --one >"$temporary" 2>/dev/null || fail "analysis failed" + +"$root/tools/validate.sh" "$temporary" \ + --evidence-root "$evidence_root" || fail "generated diagnostic is invalid" + +if [[ "$force" == true ]]; then + mv -f "$temporary" "$output" +else + ln "$temporary" "$output" +fi + +echo "Wrote validated diagnostic v1: $output" diff --git a/docs/diagnostic-contract.md b/docs/diagnostic-contract.md index 82910d2..e93e24c 100644 --- a/docs/diagnostic-contract.md +++ b/docs/diagnostic-contract.md @@ -86,7 +86,7 @@ pointer, compares raw values, and rejects paths whose symlinks escape the root. The first converter/analyser slice is available as: ```bash -bash tools/analyse.sh capture.json \ +./analyse.sh capture.json \ --evidence-root . \ --output diagnostic.json \ --reference-time 2026-09-15T12:00:00Z \ diff --git a/docs/standalone.md b/docs/standalone.md index fc64e53..9418219 100644 --- a/docs/standalone.md +++ b/docs/standalone.md @@ -12,7 +12,7 @@ dependencies. ``` ```bash -bash tools/analyse.sh capture.json \ +./analyse.sh capture.json \ --evidence-root . --output diagnostic.json \ --reference-time 2026-09-15T12:00:00Z \ --producer-version "$(git rev-parse HEAD)" diff --git a/tests/test_analyse.py b/tests/test_analyse.py index 73d2971..56dec5c 100644 --- a/tests/test_analyse.py +++ b/tests/test_analyse.py @@ -245,7 +245,7 @@ class AnalyseTests(unittest.TestCase): def test_cli_runs_outside_repository(self): output = self.work / "diagnostic.json" result = subprocess.run([ - "bash", str(ROOT / "tools" / "analyse.sh"), + "bash", str(ROOT / "analyse.sh"), str(FIXTURES / "windiagnostics-v1.json"), "--evidence-root", str(FIXTURES), "--output", str(output), "--reference-time", self.reference_time, "--producer-version", "test-revision", @@ -259,7 +259,7 @@ class AnalyseTests(unittest.TestCase): fixture = standalone / "tests" / "fixtures" / "legacy" / "windiagnostics-v1.json" output = self.work / "standalone-diagnostic.json" result = subprocess.run([ - "bash", str(standalone / "tools" / "analyse.sh"), str(fixture), + "bash", str(standalone / "analyse.sh"), str(fixture), "--evidence-root", str(fixture.parent), "--output", str(output), "--reference-time", self.reference_time, "--producer-version", "standalone-test", diff --git a/tests/test_shell_runtime.py b/tests/test_shell_runtime.py index 8c07a42..bb32d54 100644 --- a/tests/test_shell_runtime.py +++ b/tests/test_shell_runtime.py @@ -19,7 +19,7 @@ class ShellRuntimeTests(unittest.TestCase): with tempfile.TemporaryDirectory() as directory: for name, wanted in expected.items(): output = Path(directory) / name - result = subprocess.run(["bash", ROOT / "tools/analyse.sh", FIXTURES / name, + result = subprocess.run(["bash", ROOT / "analyse.sh", FIXTURES / name, "--evidence-root", FIXTURES, "--output", output, "--reference-time", "2026-09-15T12:00:00Z", "--producer-version", "test"], text=True, capture_output=True) diff --git a/tools/analyse-all.sh b/tools/analyse-all.sh index b86047d..af6087f 100755 --- a/tools/analyse-all.sh +++ b/tools/analyse-all.sh @@ -16,7 +16,7 @@ while IFS= read -r -d '' input; do relative=${input#"$input_dir/"}; output="$output_dir/${relative%.json}.diagnostic.json" mkdir -p "$(dirname "$output")"; arguments=() [[ "$force" == false ]]||arguments+=(--force) - "$root/tools/analyse.sh" "$input" --evidence-root "$evidence_root" --output "$output" \ + "$root/analyse.sh" "$input" --evidence-root "$evidence_root" --output "$output" \ --reference-time "$reference_time" --producer-version "$producer_version" "${arguments[@]}" ((count+=1)) done < <(find "$input_dir" -type f -name '*.json' -print0 | sort -z) diff --git a/tools/analyse.sh b/tools/analyse.sh deleted file mode 100755 index 4f2789e..0000000 --- a/tools/analyse.sh +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail -root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P) -fail(){ echo "error: $*" >&2; exit 1; }; usage(){ echo "Usage: $0 INPUT --evidence-root DIR --output FILE --reference-time TIME --producer-version VERSION [--force]" >&2; exit 2; } -sha256_file(){ if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"|awk '{print $1}'; elif command -v sha256 >/dev/null 2>&1; then sha256 -q "$1"; else openssl dgst -sha256 "$1"|awk '{print $NF}'; fi; } -input=${1:-}; [[ -n "$input" ]] || usage; shift -evidence_root= output= reference_time= producer_version= force=false -while (($#)); do case $1 in --evidence-root) evidence_root=$2;shift 2;;--output) output=$2;shift 2;;--reference-time) reference_time=$2;shift 2;;--producer-version) producer_version=$2;shift 2;;--force) force=true;shift;;*) usage;;esac;done -for value in "$evidence_root" "$output" "$reference_time" "$producer_version"; do [[ -n "$value" ]]||usage; done -[[ ! -L "$input" ]] || fail "input symlinks are not supported" -input=$(realpath "$input"); evidence_root=$(realpath "$evidence_root") -output_parent=$(dirname "$output"); mkdir -p "$output_parent"; output=$(cd "$output_parent" && pwd -P)/$(basename "$output") -[[ "$input" == "$evidence_root"/* ]] || fail "input must be inside --evidence-root" -[[ "$input" != "$output" ]] || fail "input and output paths must differ" -[[ ! -e "$output" || "$force" == true ]] || fail "$output: output exists; use --force to replace it" -artifact=${input#"$evidence_root/"}; hash=$(sha256_file "$input") -temporary=$(mktemp "$(dirname "$output")/.${output##*/}.XXXXXXXX") -stage=$(mktemp -d "${TMPDIR:-/tmp}/win-diagnostics.XXXXXXXX"); trap 'rm -f "$temporary"; rm -rf "$stage"' EXIT -cp "$input" "$stage/capture.json"; cp "$root/rules/event-rules.json" "$stage/event-rules.json"; cp "$root/rules/watchlist.json" "$stage/watchlist.json"; cp "$root/tools/analyse.typ" "$stage/analyse.typ" -typst query --root "$stage" --input capture=capture.json --input rules=event-rules.json --input watchlist=watchlist.json \ - --input "artifact=$artifact" --input "artifact-hash=$hash" --input "reference-time=$reference_time" --input "producer-version=$producer_version" \ - "$stage/analyse.typ" '' --field value --one >"$temporary" 2>/dev/null || fail "analysis failed" -"$root/tools/validate.sh" "$temporary" --evidence-root "$evidence_root" || fail "generated diagnostic is invalid" -if [[ "$force" == true ]]; then mv -f "$temporary" "$output"; else ln "$temporary" "$output"; fi -echo "Wrote validated diagnostic v1: $output"