Skip to content

alexgreensh/repo-forensics / skills/repo-forensics

repo-forensics

Flagged

Security forensics for git repos, AI skills, and MCP servers. Audits dependencies, detects prompt injection, credential theft, runtime dynamism, manifest drift, known CVEs, CISA KEV (actively exploited) vulns, and 2026 attack patterns. Not for fixing vulnerabilities or pentesting.

FileKindSize
.gitignoreother193 B
SKILL.mdskill md43.4 KB
checksums.jsonconfig10.8 KB
checksums.json.sigother64 B
data/README.mdmarkdown1.3 KB
data/compromised_versions.jsonconfig188.3 KB
data/rule_ids.csvother35.3 KB
data/rulepacks/.gitkeepother221 B
data/rulepacks/dead_anchors.jsonconfig9.0 KB
data/rulepacks/mcp_security.jsonconfig31.2 KB
data/rulepacks/runtime_dynamism.jsonconfig46.7 KB
data/rulepacks/sast.jsonconfig107.6 KB
data/rulepacks/secrets.jsonconfig30.4 KB
data/rulepacks/shared.jsonconfig4.4 KB
data/rulepacks/skill_threats.jsonconfig95.4 KB
data/runtime_floors.jsonconfig2.3 KB
data/yara/cryptominers.yarother1.8 KB
data/yara/hacktools.yarother2.2 KB
data/yara/malware.yarother2.2 KB
data/yara/manifest.jsonconfig8.0 KB
data/yara/webshells.yarother2.5 KB
references/cursor-hook-contract.mdmarkdown5.6 KB
references/kernel_privesc_sandbox_pack.mdmarkdown5.0 KB
references/mcp-attack-patterns.mdmarkdown8.7 KB
references/research_sources.mdmarkdown8.0 KB
references/threat_patterns.mdmarkdown20.3 KB
scripts/_context_gate.pyscript21.7 KB
scripts/_ed25519.pyscript5.1 KB
scripts/_pyc_unmarshal.pyscript17.1 KB
scripts/_shared_patterns.pyscript4.8 KB
scripts/adjudication.pyscript16.4 KB
scripts/adjudication_bridge.pyscript1.0 KB
scripts/aggregate_json.pyscript69.2 KB
scripts/auto_scan.pyexecutablescript152.1 KB
scripts/corpus_sync.pyscript10.0 KB
scripts/cursor_pre_scan.pyscript22.5 KB
scripts/dast_sandbox.sbother1.6 KB
scripts/dead_anchors_extract.pyscript14.8 KB
scripts/dead_anchors_probe.pyscript27.1 KB
scripts/forensics_core.pyscript176.5 KB
scripts/gen_rule_ids.pyscript8.6 KB
scripts/hook_adapter.pyscript19.4 KB
scripts/ioc_manager.pyscript49.6 KB
scripts/parse_pnpm_lock.pyscript7.9 KB
scripts/pre_scan.pyscript143.5 KB
scripts/pypi_pins.pyscript8.1 KB
scripts/refresh_controller.pyexecutablescript48.4 KB
scripts/refresh_threat_dbs.pyexecutablescript19.4 KB
scripts/rule_loader.pyscript44.8 KB
scripts/rulepack_feed.pyscript26.4 KB
scripts/run_forensics.shexecutablescript20.3 KB
scripts/sarif_export.pyscript18.6 KB
scripts/scan_agent_skills.pyscript33.2 KB
scripts/scan_archive.pyscript29.1 KB
scripts/scan_ast.pyscript44.9 KB
scripts/scan_binary.pyscript10.9 KB
scripts/scan_bytecode.pyscript28.2 KB
scripts/scan_dast.pyscript28.8 KB
scripts/scan_dataflow.pyscript15.4 KB
scripts/scan_dead_anchors.pyscript15.9 KB
scripts/scan_decode.pyscript37.5 KB
scripts/scan_dependencies.pyscript124.5 KB
scripts/scan_devcontainer.pyscript8.5 KB
scripts/scan_entropy.pyscript15.6 KB
scripts/scan_entrypoint.pyscript34.3 KB
scripts/scan_git_config.pyscript96.3 KB
scripts/scan_git_forensics.pyscript24.1 KB
scripts/scan_history.pyscript14.5 KB
scripts/scan_infra.pyscript54.3 KB
scripts/scan_integrity.pyscript41.0 KB
scripts/scan_lifecycle.pyscript65.1 KB
scripts/scan_manifest_drift.pyscript47.0 KB
scripts/scan_mcp_security.pyscript42.3 KB
scripts/scan_oversize.pyscript11.7 KB
scripts/scan_post_incident.pyscript36.9 KB
scripts/scan_provenance.pyscript19.4 KB
scripts/scan_runtime_dynamism.pyscript23.5 KB
scripts/scan_runtime_floors.pyscript33.5 KB
scripts/scan_sast.pyscript59.1 KB
scripts/scan_secrets.pyscript11.9 KB
scripts/scan_skill_threats.pyscript102.4 KB
scripts/scan_splitstream.pyscript29.5 KB
scripts/scan_yara.pyscript19.7 KB
scripts/session_scan.pyscript54.1 KB
scripts/suppressions.pyscript15.4 KB
scripts/validate_manifests.pyscript13.7 KB
scripts/verify_install.pyscript26.2 KB
scripts/vuln_feed.pyscript31.1 KB
tests/conftest.pyscript13.4 KB
tests/corpus/DEAD_ANCHORS_CORPUS.mdmarkdown2.3 KB
tests/corpus/budgets.jsonconfig5.6 KB
tests/cursor_helpers.pyscript12.6 KB
tests/fixtures/legacy_main_blocks.jsonconfig10.3 KB
tests/fixtures/powershell_verdict_corpus.jsonconfig114.9 KB
tests/golden/parity_mcp_security.jsonconfig17.5 KB
tests/golden/parity_runtime_dynamism.jsonconfig31.7 KB
tests/golden/parity_sast.jsonconfig59.8 KB
tests/golden/parity_secrets.jsonconfig18.8 KB
tests/golden/parity_skill_threats.jsonconfig48.8 KB
tests/parity_corpus.pyscript6.3 KB
tests/powershell_hook.pyscript8.2 KB
tests/report_builders.pyscript5.0 KB
tests/schemas/sarif-schema-2.1.0.jsonconfig109.1 KB
tests/shell_compat.pyscript2.2 KB
tests/test_adjudication_bridge.pyscript832 B
tests/test_adjudication_containment.pyscript1.4 KB
tests/test_adjudication_output.pyscript20.0 KB
tests/test_adjudication_suppressions.pyscript18.7 KB
tests/test_advisory_adjudication.pyscript1.3 KB
tests/test_agent_relay_rules.pyscript7.8 KB
tests/test_aggregate_json.pyscript10.0 KB
tests/test_auto_scan_patterns.pyscript10.5 KB
tests/test_benign_corpus.pyscript16.4 KB
tests/test_benign_new_scanners.pyscript6.1 KB
tests/test_build_output_skip.pyscript10.6 KB
tests/test_capability_ledger.pyscript18.8 KB
tests/test_codex_install.pyscript10.0 KB
tests/test_codex_marketplace.pyscript3.3 KB
tests/test_comment_false_positives.pyscript2.2 KB
tests/test_composer_dependencies.pyscript4.0 KB
tests/test_compromised_versions.pyscript51.2 KB
tests/test_context_gate.pyscript32.4 KB
tests/test_coverage_status.pyscript7.6 KB
tests/test_css_compounding_shrink.pyscript20.8 KB
tests/test_cursor_adapter.pyscript7.8 KB
tests/test_cursor_benign.pyscript3.4 KB
tests/test_cursor_degrade.pyscript12.7 KB
tests/test_cursor_install.pyscript17.1 KB
tests/test_cursor_latency.pyscript7.2 KB
tests/test_cursor_parity.pyscript5.8 KB
tests/test_cursor_redteam_fn.pyscript4.9 KB
tests/test_cursor_tamper_modify.pyscript14.2 KB
tests/test_cursor_wiring.pyscript32.3 KB
tests/test_d1_yara_correlation.pyscript9.2 KB
tests/test_dead_anchors_extract.pyscript7.6 KB
tests/test_dead_anchors_probe.pyscript19.7 KB
tests/test_evidence_engine_parity.pyscript8.1 KB
tests/test_evidence_model.pyscript11.4 KB
tests/test_forensics_core.pyscript79.2 KB
tests/test_fp_hardening_r3.pyscript9.7 KB
tests/test_fp_hardening_r4.pyscript18.8 KB
tests/test_fp_regression_pairs.pyscript62.5 KB
tests/test_fp_structural.pyscript21.2 KB
tests/test_freshness.pyscript6.2 KB
tests/test_frontmatter_validity.pyscript7.0 KB
tests/test_gpg_rce_hotfix.pyscript4.8 KB
tests/test_hook_inert_data.pyscript6.1 KB
tests/test_hook_scripts.pyscript14.0 KB
tests/test_inspection_cpu_budget.pyscript11.6 KB
tests/test_ioc_manager.pyscript55.4 KB
tests/test_kernel_privesc_rules.pyscript27.8 KB
tests/test_legit_precision_regressions.pyscript6.8 KB
tests/test_lethal_trifecta.pyscript20.7 KB
tests/test_manifest_signature.pyscript1.5 KB
tests/test_manifest_validity.pyscript2.9 KB
tests/test_monotonic_trust_e2e.pyscript4.4 KB
tests/test_non_breaking_contract.pyscript22.7 KB
tests/test_openclaw_install.pyscript6.6 KB
tests/test_pack_parity.pyscript24.8 KB
tests/test_parse_pnpm_lock.pyscript10.7 KB
tests/test_plugin_checkout_provenance.pyscript11.1 KB
tests/test_powershell_hook_wire.pyscript10.6 KB
tests/test_powershell_verdict_corpus.pyscript6.2 KB
tests/test_pr44_hardening.pyscript6.5 KB
tests/test_pre_scan.pyscript19.6 KB
tests/test_pre_scan_composer.pyscript7.4 KB
tests/test_precondition_fields.pyscript4.6 KB
tests/test_provenance_offline.pyscript2.5 KB
tests/test_published_rulepack_feed_current.pyscript1.4 KB
tests/test_py38_compat.pyscript3.3 KB
tests/test_pypi_pinned_versions.pyscript19.3 KB
tests/test_pyproject_string_forms.pyscript2.2 KB
tests/test_redteam_fn_regression.pyscript32.5 KB
tests/test_reflective_fetch_execute.pyscript23.5 KB
tests/test_reflective_review_fixes.pyscript17.8 KB
tests/test_refresh_controller.pyscript19.9 KB
tests/test_refresh_rulepacks.pyscript12.4 KB
tests/test_review_gate_regressions.pyscript9.3 KB
tests/test_rule_loader.pyscript23.2 KB
tests/test_rulepack_feed.pyscript38.1 KB
tests/test_run_forensics_json.pyscript1012 B
tests/test_run_scanner_fail_loud.pyscript6.5 KB
tests/test_runtime_floors.pyscript19.8 KB
tests/test_sandbox_probing_rules.pyscript9.6 KB
tests/test_sarif_export.pyscript19.9 KB
tests/test_scan_agent_skills.pyscript31.3 KB
tests/test_scan_archive.pyscript11.6 KB
tests/test_scan_ast.pyscript12.8 KB
tests/test_scan_binary.pyscript15.3 KB
tests/test_scan_bytecode.pyscript21.5 KB
tests/test_scan_dast.pyscript32.1 KB
tests/test_scan_dataflow.pyscript7.1 KB
tests/test_scan_dead_anchors.pyscript11.5 KB
tests/test_scan_decode.pyscript28.0 KB
tests/test_scan_dependencies.pyscript37.8 KB
tests/test_scan_devcontainer.pyscript8.5 KB
tests/test_scan_entropy.pyscript11.2 KB
tests/test_scan_entrypoint.pyscript19.5 KB
tests/test_scan_git_config.pyscript58.5 KB
tests/test_scan_git_config_review_fixes.pyscript33.3 KB

scripts/run_forensics.sh

View on GitHub
#!/usr/bin/env bash

# Repo Forensics Suite Runner v2
# Created by Alex Greenshpun
# Usage: ./run_forensics.sh <repo_path> [--skill-scan] [--format text|json|summary]

set -euo pipefail

# Floor PATH with trusted system roots so this script's own utilities
# (dirname, realpath, date, ps, awk, mktemp) resolve when the caller's PATH
# is stripped (GUI hook environments) or the system is non-FHS — NixOS has
# no /usr/bin or /bin coreutils. Appended, never replacing the caller's
# PATH, so caller priority is preserved. Deliberately excludes ~/.local/bin:
# arbitrary user-installed binaries should not become this scanner's tools.
PATH="${PATH:-}:/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin:/run/current-system/sw/bin:/nix/var/nix/profiles/default/bin"
if [ -n "${HOME:-}" ]; then
    PATH="$PATH:$HOME/.nix-profile/bin"
fi
_rf_profile_user="${USER:-}"
if [ -z "$_rf_profile_user" ] && [ -n "${HOME:-}" ]; then
    _rf_profile_user="${HOME##*/}"
fi
if [ -n "$_rf_profile_user" ]; then
    PATH="$PATH:/etc/profiles/per-user/$_rf_profile_user/bin"
fi
unset _rf_profile_user
# Drop a leading ':' left by an empty caller PATH (empty segment = cwd).
PATH="${PATH#:}"
export PATH

# Focused (--skill-scan) scanner set, as "name:script" pairs. The printed
# scanner counts in usage and in the run banner are generated from this list,
# so the number can never drift from what actually launches.
FOCUSED_SCANNERS=(
    "skill_threats:scan_skill_threats.py"
    "secrets:scan_secrets.py"
    "dataflow:scan_dataflow.py"
    "sast:scan_sast.py"
    "lifecycle:scan_lifecycle.py"
    "mcp_security:scan_mcp_security.py"
    "runtime_dynamism:scan_runtime_dynamism.py"
    "manifest_drift:scan_manifest_drift.py"
    "agent_skills:scan_agent_skills.py"
    "devcontainer:scan_devcontainer.py"
    "oversize:scan_oversize.py"
    "bytecode:scan_bytecode.py"
    "archive:scan_archive.py"
    "splitstream:scan_splitstream.py"
    "git_forensics:scan_git_forensics.py"
    "provenance:scan_provenance.py"
    "dead_anchors:scan_dead_anchors.py"
    "yara:scan_yara.py"
    "git_config:scan_git_config.py"
)

# Full-audit (default mode) scanner set, same "name:script" shape and the
# same reason: the printed count is generated from what actually launches.
# integrity gets --watch appended when --watch is set.
FULL_SCANNERS=(
    "entropy:scan_entropy.py"
    "binary:scan_binary.py"
    "yara:scan_yara.py"
    "git_forensics:scan_git_forensics.py"
    "dependencies:scan_dependencies.py"
    "runtime_floors:scan_runtime_floors.py"
    "secrets:scan_secrets.py"
    "sast:scan_sast.py"
    "infra:scan_infra.py"
    "lifecycle:scan_lifecycle.py"
    "skill_threats:scan_skill_threats.py"
    "dataflow:scan_dataflow.py"
    "mcp_security:scan_mcp_security.py"
    "ast_analysis:scan_ast.py"
    "runtime_dynamism:scan_runtime_dynamism.py"
    "manifest_drift:scan_manifest_drift.py"
    "agent_skills:scan_agent_skills.py"
    "integrity:scan_integrity.py"
    "dast:scan_dast.py"
    "post_incident:scan_post_incident.py"
    "devcontainer:scan_devcontainer.py"
    "entrypoint:scan_entrypoint.py"
    "oversize:scan_oversize.py"
    "bytecode:scan_bytecode.py"
    "archive:scan_archive.py"
    "splitstream:scan_splitstream.py"
    "provenance:scan_provenance.py"
    "dead_anchors:scan_dead_anchors.py"
    "git_config:scan_git_config.py"
)

if [ -z "${1:-}" ]; then
    echo "Usage: $0 <repo_path> [options]"
    echo ""
    echo "Modes:"
    echo "  (default)              Full audit - all ${#FULL_SCANNERS[@]} scanners"
    echo "  --skill-scan           Focused on AI skill threats (${#FOCUSED_SCANNERS[@]} scanners, faster)"
    echo "  --inventory            Enumerate installed AI-agent stacks (zero-LLM, JSON output)"
    echo ""
    echo "Options:"
    echo "  --format text          Human-readable with severity colors (default)"
    echo "  --format json          Machine-readable JSON"
    echo "  --format summary       Counts only (for CI/CD)"
    echo "  --format sarif         SARIF 2.1.0 (GitHub code-scanning compatible)"
    echo "  --update-iocs          Pull latest IOC database before scanning"
    echo "  --update-vulns         Refresh CISA KEV catalog before scanning (CVE enrichment)"
    echo "  --no-vulns             Skip OSV + KEV vulnerability enrichment"
    echo "  --offline              No network fetches (use cached KEV/OSV data only)"
    echo "                         (refreshes are opt-in: a run without --update-iocs/--update-vulns does not refresh)"
    echo "  --watch                Enable file integrity baseline tracking"
    echo "  --history              Store a local content-addressed attestation"
    echo "  --package-list=FILE    Load user-supplied IOC list (absolute path, see docs)"
    echo "  --include-shadows      Include shadow surfaces in inventory (backups, caches)"
    echo "  --max-jobs=N           Max parallel scanners (default: clamp(ncpu, 4, 8), env: REPO_FORENSICS_MAX_JOBS)"
    exit 1
fi

# Resolve one working Python 3 interpreter for the whole run. Executing each
# candidate is intentional: Windows can expose zero-byte/App Execution Alias
# stubs named python or python3 that exist on PATH but are not interpreters.
#
# The probe requires the candidate to emit a unique sentinel ("PY3OK") via
# actual Python 3.8+ code. Exit status alone is insufficient: a zero-byte stub
# is treated by bash as an empty shell script (exit 0), and a non-Python binary
# can exit 0 without ever evaluating the -c argument. Only a real Python 3.8+
# interpreter can print the sentinel, so impostors are rejected.
#
# A 5-second timeout prevents a hanging candidate from blocking the CLI
# indefinitely. The timeout wrapper is selected in priority order:
#   1. timeout   (Linux, coreutils)
#   2. gtimeout  (macOS with Homebrew coreutils)
#   3. a Perl process-group supervisor (macOS ships /usr/bin/perl; the full Git
#      for Windows installer bundles perl, though minimal distributions such as
#      MinGit deliberately omit it)
# Only if NONE of these are available does the probe run unbounded — a residual
# risk on minimal environments (e.g. MinGit, which ships neither perl nor
# coreutils), where a hanging Store-alias stub could block the probe. Adding a
# bash-only timeout tier is tracked as follow-up.
#
# This resolver intentionally differs from hooks/python-launcher.sh, which runs
# in a stripped/untrusted GUI hook PATH (Codex, GUI-launched agent apps) and so
# uses a safe-prefix allowlist, size checks, WindowsApps timeouts, and
# direct-path fallbacks. This resolver instead relies on a bounded sentinel
# probe. Note run_forensics.sh is ALSO reachable from that hook PATH — session
# hook deep scans (session_scan.py) spawn it via subprocess without a sanitized
# env. The probe searches the caller's PATH plus the trusted system-root floor
# added at the top of this script (appended, so caller priority wins); the
# bounded sentinel + timeout remains the safety boundary here. Do not collapse
# the two resolvers without accounting for that environment.
_rf_bounded() {
    # Run "$@" with a 5-second alarm. Uses timeout/gtimeout/perl in priority order.
    # Returns the candidate's exit status (124 if timed out).
    if [ -n "$_RF_TIMEOUT_CMD" ]; then
        "$_RF_TIMEOUT_CMD" 5 "$@"
    elif [ -n "$_RF_USE_PERL" ]; then
        # Perl supervisor: fork child into its own process group, alarm in
        # parent, TERM then KILL the whole process group on timeout. This
        # kills the candidate AND any children it spawned (e.g. a shell stub
        # that runs sleep). Plain alarm+exec only kills the exec'd process,
        # leaving orphaned children holding the capture pipe open.
        perl -e '
use POSIX qw(setpgid);
my $s=shift; my $p=fork;
if(!defined $p){die"fork:$!"}
if($p==0){setpgid(0,0)||die"setpgid:$!";exec @ARGV or die"exec:$!"}
$SIG{ALRM}=sub{kill 15,-$p;select undef,undef,undef,0.5;kill 9,-$p;exit 124};
alarm $s;
waitpid($p,0);
alarm 0;
exit($?&127?128+($?&127):$?>>8)
' 5 "$@"
    else
        "$@"  # residual unbounded fallback (no timeout utility available)
    fi
}
_RF_TIMEOUT_CMD=""
if command -v timeout >/dev/null 2>&1; then
    _RF_TIMEOUT_CMD="timeout"
elif command -v gtimeout >/dev/null 2>&1; then
    _RF_TIMEOUT_CMD="gtimeout"
fi
_RF_USE_PERL=""
if [ -z "$_RF_TIMEOUT_CMD" ] && command -v perl >/dev/null 2>&1; then
    _RF_USE_PERL=1
fi
_PY_PROBE='import sys; print("PY3OK") if sys.version_info >= (3, 8) else print("NO")'
_py_check() {
    # $1 = candidate command (single word like python3)
    local out
    out=$(_rf_bounded "$1" -c "$_PY_PROBE" 2>/dev/null) || return 1
    [ "$out" = "PY3OK" ]
}
PYTHON=()
for candidate in python3 python; do
    if command -v "$candidate" >/dev/null 2>&1 && _py_check "$candidate"; then
        PYTHON=("$candidate")
        break
    fi
done
if [ ${#PYTHON[@]} -eq 0 ] && command -v py >/dev/null 2>&1; then
    if _rf_bounded py -3 -c "$_PY_PROBE" 2>/dev/null | grep -q '^PY3OK$'; then
        PYTHON=(py -3)
    fi
fi
if [ ${#PYTHON[@]} -eq 0 ]; then
    echo "[repo-forensics] ERROR: Python 3.8+ not found (tried python3, python, py -3)" >&2
    exit 127
fi

# Check for --inventory before consuming positional arg
if [ "$1" = "--inventory" ]; then
    shift
    INVENTORY_ARGS=()
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --target) INVENTORY_ARGS+=("--target" "$2"); shift 2 ;;
            --include-shadows) INVENTORY_ARGS+=("--include-shadows"); shift ;;
            --list-ecosystems) INVENTORY_ARGS+=("--list-ecosystems"); shift ;;
            *) echo "Unknown inventory arg: $1"; exit 1 ;;
        esac
    done
    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    FORENSIFY_DIR="$(cd "$SCRIPT_DIR/../../forensify/scripts" 2>/dev/null && pwd)" || {
        echo "Error: forensify scripts not found at $SCRIPT_DIR/../../forensify/scripts" >&2
        exit 1
    }
    exec "${PYTHON[@]}" "$FORENSIFY_DIR/build_inventory.py" "${INVENTORY_ARGS[@]}"
fi

REPO_PATH=$(realpath "$1")
shift

# Parse remaining args
SKILL_SCAN=false
FORMAT="text"
UPDATE_IOCS=false
UPDATE_VULNS=false
NO_VULNS=false
OFFLINE=false
WATCH_MODE=false
VERIFY_INSTALL=false
HISTORY=false
PACKAGE_LIST_FILE=""
while [[ $# -gt 0 ]]; do
    case "$1" in
        --skill-scan) SKILL_SCAN=true; shift ;;
        --format) [[ $# -ge 2 ]] || { echo "Error: --format requires a value"; exit 1; }; FORMAT="$2"; shift 2 ;;
        --update-iocs) UPDATE_IOCS=true; shift ;;
        --update-vulns) UPDATE_VULNS=true; shift ;;
        --no-vulns) NO_VULNS=true; shift ;;
        --offline) OFFLINE=true; shift ;;
        --watch) WATCH_MODE=true; shift ;;
        --verify-install) VERIFY_INSTALL=true; shift ;;
        --history) HISTORY=true; shift ;;
        --package-list=*) PACKAGE_LIST_FILE="${1#*=}"; shift ;;
        --package-list)
            [[ $# -ge 2 ]] || { echo "Error: --package-list requires a FILE argument"; exit 1; }
            PACKAGE_LIST_FILE="$2"; shift 2 ;;
        --max-jobs=*) MAX_JOBS="${1#*=}"; shift ;;
        --max-jobs)
            [[ $# -ge 2 ]] || { echo "Error: --max-jobs requires a number"; exit 1; }
            MAX_JOBS="$2"; shift 2 ;;
        *update*)
            echo "Unknown arg: $1"
            echo "Refreshes are opt-in (--update-iocs, --update-vulns); a default run does not fetch them. Use --offline to block all network fetches."
            exit 1 ;;
        *) echo "Unknown arg: $1"; exit 1 ;;
    esac
done

# Machine-readable formats suppress the human banner/progress/echo lines.
# json and sarif both suppress; text and summary print. Behavior for
# text|json|summary is provably identical to the prior `!= json` guards.
MACHINE_FORMAT=false
{ [ "$FORMAT" = "json" ] || [ "$FORMAT" = "sarif" ]; } && MACHINE_FORMAT=true

# Validate --package-list is an absolute path BEFORE passing to Python
if [ -n "$PACKAGE_LIST_FILE" ]; then
    case "$PACKAGE_LIST_FILE" in
        /*) : ;;  # absolute, OK
        *) echo "Error: --package-list must be an absolute path, got: $PACKAGE_LIST_FILE"; exit 1 ;;
    esac
    if [ ! -f "$PACKAGE_LIST_FILE" ]; then
        echo "Error: --package-list file not found: $PACKAGE_LIST_FILE"; exit 1
    fi
fi

SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"

# Stop orphaned scanners from previous runs: only processes whose parent is
# gone (PPID 1), that run THIS install's own scan_*.py, and that have outlived
# SCANNER_TIMEOUT. A scan running in another session still has a live parent
# and is left alone. Thanks to @ryanduguid for reporting the broad sweep.
# shellcheck disable=SC2009  # pgrep can't provide etime; we need ps output for age filtering
_stale_pids=$(ps ax -o pid=,ppid=,etime=,command= 2>/dev/null | awk -v dir="$SKILL_DIR/scan_" '
    $2 == 1 && index($0, dir) > 0 && $0 ~ /\.py/ {
        split($3, t, "[-:]"); n = length(t)
        secs = t[n]+0 + (t[n-1]+0)*60
        if (n >= 3) secs += (t[n-2]+0)*3600
        if (n >= 4) secs += (t[n-3]+0)*86400
        if (secs > 150) print $1
    }' || true)
if [ -n "$_stale_pids" ]; then
    echo "[repo-forensics] Stopping orphaned scanner processes from a previous run: $(echo $_stale_pids)" >&2
    echo "$_stale_pids" | xargs kill 2>/dev/null || true
fi

# Handle --verify-install (standalone, exits after)
if $VERIFY_INSTALL; then
    "${PYTHON[@]}" "$SKILL_DIR/verify_install.py" --verify
    exit $?
fi

# Handle --update-iocs before scanning
if $UPDATE_IOCS; then
    echo "[*] Updating IOC database..."
    "${PYTHON[@]}" "$SKILL_DIR/ioc_manager.py" --update || echo "[!] IOC update failed, scanning with cached data" >&2
fi

# Handle --update-vulns (CISA KEV) before scanning
if $UPDATE_VULNS && ! $OFFLINE; then
    echo "[*] Updating CISA KEV catalog..."
    "${PYTHON[@]}" "$SKILL_DIR/vuln_feed.py" --update || true
fi
TMPDIR=$(mktemp -d)
# shellcheck disable=SC2329  # invoked indirectly via trap
cleanup() { local _saved=$?; trap - EXIT INT TERM; set +e; jobs -p | xargs kill 2>/dev/null; wait 2>/dev/null; exec 3>&- 2>/dev/null; rm -rf "$TMPDIR"; exit "$_saved"; }
trap cleanup EXIT INT TERM

if ! $MACHINE_FORMAT; then
    echo "=========================================="
    echo "  REPO FORENSICS v2"
    echo "  Target: $REPO_PATH"
    echo "  Mode: $(if $SKILL_SCAN; then echo 'Skill Scan (focused)'; else echo 'Full Audit'; fi)"
    echo "  Format: $FORMAT"
    echo "  Date: $(date)"
    echo "=========================================="
fi

SCANNER_TIMEOUT=120

# Concurrency limiter: cap parallel scanners to avoid CPU storms
# Priority: --max-jobs flag > REPO_FORENSICS_MAX_JOBS env > auto-detect
MAX_JOBS=${MAX_JOBS:-${REPO_FORENSICS_MAX_JOBS:-0}}
if [ -n "$MAX_JOBS" ] && ! [[ "$MAX_JOBS" =~ ^[0-9]+$ ]]; then
    echo "Error: --max-jobs must be a positive integer, got: $MAX_JOBS" >&2
    exit 1
fi
if [ "$MAX_JOBS" -le 0 ] 2>/dev/null; then
    MAX_JOBS=$(sysctl -n hw.ncpu 2>/dev/null || nproc 2>/dev/null || echo 4)
    [ "$MAX_JOBS" -gt 8 ] && MAX_JOBS=8
    [ "$MAX_JOBS" -lt 4 ] && MAX_JOBS=4
fi
[ "$MAX_JOBS" -gt 20 ] && MAX_JOBS=20

# FIFO semaphore: N tokens pre-fill the pipe. throttled_run blocks on
# read until a token is available, returns it after the job completes.
SEMAPHORE_FIFO="$TMPDIR/.job_semaphore"
mkfifo -m 600 "$SEMAPHORE_FIFO"
exec 3<>"$SEMAPHORE_FIFO"
for ((i=0; i<MAX_JOBS; i++)); do echo >&3; done

throttled_run() {
    read -r -u 3
    trap 'echo >&3' RETURN
    local _rc=0
    "$@" || _rc=$?
    return $_rc
}

# Portable timeout (macOS lacks GNU timeout)
TIMEOUT_CMD=""
if command -v timeout >/dev/null 2>&1; then
    TIMEOUT_CMD="timeout"
elif command -v gtimeout >/dev/null 2>&1; then
    TIMEOUT_CMD="gtimeout"
fi

# TTY autodetect for per-scanner progress lines
PROGRESS=false
if [ -t 2 ] && ! $MACHINE_FORMAT; then
    PROGRESS=true
fi

# Staleness detection for Path B (git-clone) users
STALENESS_DAYS=30
if [ -d "$SKILL_DIR/.git" ] || [ -f "$SKILL_DIR/../../.git" ] || [ -f "$SKILL_DIR/../../../.git" ]; then
    LAST_COMMIT_DATE=$(git -C "$SKILL_DIR" log -1 --format=%ct 2>/dev/null || echo "0")
    NOW=$(date +%s)
    if [ "$LAST_COMMIT_DATE" -gt 0 ]; then
        AGE_DAYS=$(( (NOW - LAST_COMMIT_DATE) / 86400 ))
        if [ "$AGE_DAYS" -ge "$STALENESS_DAYS" ]; then
            echo "[repo-forensics] Install is ${AGE_DAYS} days old. Run 'git pull' for latest IOCs and detection rules." >&2
        fi
    fi
fi

# shellcheck disable=SC2329  # invoked indirectly via throttled_run
run_scanner() {
    local name="$1"
    local script="$2"
    local extra_args="${3:-}"
    local output_file="$TMPDIR/$name.out"
    local exit_file="$TMPDIR/$name.exit"
    local error_file="$TMPDIR/$name.err"
    local start_time
    start_time=$(date +%s)

    local internal_format="json"

    local -a scanner_args=()
    [ -n "$extra_args" ] && scanner_args+=("$extra_args")

    if [ "$name" = "dependencies" ]; then
        [ -n "$PACKAGE_LIST_FILE" ] && scanner_args+=("--package-list=$PACKAGE_LIST_FILE")
        $NO_VULNS && scanner_args+=("--no-vulns")
        $OFFLINE && scanner_args+=("--offline")
    fi

    # dead_anchors is network-touching; honor the global --offline flag so a
    # sandboxed/offline full scan degrades every anchor to couldn't-check.
    if [ "$name" = "dead_anchors" ]; then
        $OFFLINE && scanner_args+=("--offline")
    fi

    # provenance shells out to npm audit signatures / gh attestation verify,
    # which contact their registries; --offline skips them.
    if [ "$name" = "provenance" ]; then
        $OFFLINE && scanner_args+=("--offline")
    fi

    if [ "$name" = "skill_threats" ]; then
        scanner_args+=("--full-audit")
    fi

    if [ -n "$TIMEOUT_CMD" ]; then
        $TIMEOUT_CMD "$SCANNER_TIMEOUT" "${PYTHON[@]}" "$SKILL_DIR/$script" "$REPO_PATH" --format "$internal_format" ${scanner_args[@]+"${scanner_args[@]}"} 3>&- > "$output_file" 2>> "$error_file"
    else
        "${PYTHON[@]}" "$SKILL_DIR/$script" "$REPO_PATH" --format "$internal_format" ${scanner_args[@]+"${scanner_args[@]}"} 3>&- > "$output_file" 2>> "$error_file"
    fi
    local exit_code=$?
    echo "$exit_code" > "$exit_file"

    # Per-scanner progress line (TTY only, silent in CI/piped output)
    if $PROGRESS; then
        local elapsed=$(( $(date +%s) - start_time ))
        local findings=0
        if [ -f "$output_file" ] && [ -s "$output_file" ]; then
            findings=$("${PYTHON[@]}" -c "
import json, sys
try:
    d = json.load(open('$output_file'))
    print(len(d.get('findings', d.get('results', []))))
except: print(0)
" 2>/dev/null || echo 0)
        fi
        if [ "$exit_code" -eq 0 ]; then
            echo "[OK] $name: $findings findings (${elapsed}s)" >&2
        else
            echo "[!!] $name: exit $exit_code (${elapsed}s)" >&2
        fi
    fi
}

if $SKILL_SCAN; then
    # Focused mode: the scanners most relevant to vetting skills
    if ! $MACHINE_FORMAT; then
        echo ""
        echo "[*] Running focused skill scan (${#FOCUSED_SCANNERS[@]} scanners)..."
    fi

    for _focused_spec in "${FOCUSED_SCANNERS[@]}"; do
        throttled_run run_scanner "${_focused_spec%%:*}" "${_focused_spec##*:}" &
    done
    unset _focused_spec
    wait

else
    # Full audit: all scanners in parallel
    if ! $MACHINE_FORMAT; then
        echo ""
        echo "[*] Running all ${#FULL_SCANNERS[@]} scanners in parallel..."
    fi
    for _full_spec in "${FULL_SCANNERS[@]}"; do
        if [ "${_full_spec%%:*}" = "integrity" ] && $WATCH_MODE; then
            throttled_run run_scanner "integrity" "${_full_spec##*:}" "--watch" &
        else
            throttled_run run_scanner "${_full_spec%%:*}" "${_full_spec##*:}" &
        fi
    done
    unset _full_spec
    wait
fi

# Scanners ran in JSON format internally so the correlation engine can see
# every scanner's findings together (security review A5 fix, 2026-04-05).
# aggregate_json.py runs forensics_core.correlate() on the merged findings
# and emits either JSON (for --format json) or text (for --format text /
# --format summary) output. This is the single aggregation path.

EXIT_CODE_FILE="$TMPDIR/aggregate.exit"
echo "99" > "$EXIT_CODE_FILE"

if $HISTORY; then
    export REPO_FORENSICS_HISTORY=1
fi

if [ "$FORMAT" = "json" ]; then
    if ! "${PYTHON[@]}" "$SKILL_DIR/aggregate_json.py" "$TMPDIR" "$REPO_PATH" "$SKILL_SCAN" "$EXIT_CODE_FILE"; then
        :
    fi
elif [ "$FORMAT" = "sarif" ]; then
    if ! "${PYTHON[@]}" "$SKILL_DIR/aggregate_json.py" --sarif "$TMPDIR" "$REPO_PATH" "$SKILL_SCAN" "$EXIT_CODE_FILE"; then
        :
    fi
else
    # text and summary modes both use text output from the aggregator
    if ! "${PYTHON[@]}" "$SKILL_DIR/aggregate_json.py" --text "$TMPDIR" "$REPO_PATH" "$SKILL_SCAN" "$EXIT_CODE_FILE"; then
        :
    fi
fi

_rc=$(cat "$EXIT_CODE_FILE" 2>/dev/null || echo "99")
case "$_rc" in
    0|1|2) exit "$_rc" ;;
    *) exit 99 ;;
esac
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall