fix(runner): prevent NUL content scan bypass

[steipete]

Summary

• keep NUL-obfuscated source, scripts, and otherwise inspectable content in the static scan path
• remove NUL bytes before applying rules so obfuscated tokens cannot suppress matches, while retaining hashes and byte counts for the original file
• pass normalized content to external judges and surface truly opaque binary omissions as low-severity policy evidence
• decode BOM-marked UTF-16/32 safely, scan both decoded and raw normalized representations, and enforce prompt budgets on rendered content
• document the behavior and cover source, shebang, opaque media, Unicode, forged-magic, and budget boundaries

Proof

• TMPDIR=<canonical /private/tmp directory> go test -count=1 ./...
• go vet ./...
• make docs-site
• built-CLI black-box validation: NUL-split curl triggered both static.nul_byte_in_text and static.pipe_to_shell; the judge received normalized text without a raw NUL; opaque PNG content remained omitted with static.opaque_binary; clean text remained finding-free
• structured autoreview focused regressions passed; all accepted findings were addressed

Reported by @nedlir — thank you for the clear reproduction and root-cause analysis.

Closes #42

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 14, 2026, 3:54 PM ET / 19:54 UTC.

ClawSweeper review

What this changes

The PR normalizes inspectable NUL-containing files for static scanning and judge prompts, records opaque binary omissions, and adds documentation and regression coverage.

Merge readiness

⛔ Blocked until real behavior proof is added - 3 items remain

Keep open. Current main still silently omits NUL-containing files from the static scan path; this focused patch addresses that boundary without a source-level correctness finding. Before merge, it needs observable after-fix proof rather than only asserted command results.

Priority: P1
Reviewed head: 0061bd41d5c3a399720d1ae195bac81fcf73747e

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The patch is focused and well-covered in source, but real after-fix behavior proof is still absent.
Proof confidence	🧂 unranked krab (1/6)	Needs real behavior proof before merge: The PR body reports after-fix CLI validation but does not include observable terminal output, logs, media, or an artifact that demonstrates the claimed results. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR body reports after-fix CLI validation but does not include observable terminal output, logs, media, or an artifact that demonstrates the claimed results. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Current-main bypass: Current main omits any file containing a NUL byte as a binary file before static rules run, so the reported scanner bypass remains present in the released base. Scanner repair path: The PR replaces the unconditional omission with shared inspection, normalization, static-rule scanning, and an explicit NUL finding for inspectable content. Judge prompt boundary: The rendered target-file prompt uses normalized or decoded content and re-applies per-file and aggregate rendered-content budgets.
Findings	None	None.
Security	None	None.

How this fits together

ClawScan’s built-in static scanner reads local skill or plugin files and writes raw JSON evidence, which can then be included in an external judge prompt. This change decides whether NUL-containing input is decoded and scanned or retained as an opaque omission, affecting both findings and judge context.

flowchart LR
  A[Skill or plugin files] --> B[Static scanner and prompt renderer]
  B --> C{NUL bytes present?}
  C -->|No| D[Scan original text]
  C -->|Inspectable text| E[Normalize or decode content]
  C -->|Opaque binary| F[Omission with policy evidence]
  E --> G[Static findings and judge prompt]
  D --> G
  F --> G

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The PR body reports after-fix CLI validation but does not include observable terminal output, logs, media, or an artifact that demonstrates the claimed results. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The NUL classifier changes which binary-like files are inspected and sent to judges; the stated validation has no observable proof covering an obfuscated script, opaque asset, and decoded BOM text.
• Complete next step (P2) - The remaining merge blocker is contributor-supplied real behavior proof, not a narrow automated code repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and test delta	production +215/-8, tests +234/-1	The substantial parser and classification change is paired with similarly substantial focused regression coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #42
Summary: This PR is the candidate repair for the concrete NUL-content scanner bypass reported in the linked issue.

Members:

• canonical: [Bug]: single binary bypasses whole scan #42 - The PR explicitly targets the issue’s NUL-triggered binary omission and contains the corresponding scanner and prompt-path repair.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Capture boundary proof before merge (recommended)
   Add redacted live CLI output or logs showing both the repaired NUL-text path and the preserved opaque-binary path before accepting this security-sensitive classification change.

Technical review

Best possible solution:

Add a redacted built-CLI transcript that demonstrates the NUL-split detection, a judge prompt free of raw NUL bytes, opaque-image omission evidence, and successful BOM-text scanning, then merge this narrow repair.

Do we have a high-confidence way to reproduce the issue?

Yes—source-reproducible with high confidence: current main omits a file immediately upon finding a NUL byte, and the branch’s focused tests encode the affected input shapes. This read-only review did not execute the reproduction.

Is this the best way to solve the issue?

Yes, the shared inspection helper is a narrow solution because it preserves original scan accounting while making inspectable NUL content visible to both rules and judges; the remaining requirement is real after-fix proof.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9f6a6fbb9f11.

Labels

Label changes:

• add P1: Current v0.1.6 can omit NUL-obfuscated inspectable content before security rules run, enabling a practical scanner-evasion path.
• add merge-risk: 🚨 security-boundary: The PR changes the security scanner’s inspect-versus-omit boundary and the content supplied to external judges.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports after-fix CLI validation but does not include observable terminal output, logs, media, or an artifact that demonstrates the claimed results. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P1: Current v0.1.6 can omit NUL-obfuscated inspectable content before security rules run, enabling a practical scanner-evasion path.
• merge-risk: 🚨 security-boundary: The PR changes the security scanner’s inspect-versus-omit boundary and the content supplied to external judges.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports after-fix CLI validation but does not include observable terminal output, logs, media, or an artifact that demonstrates the claimed results. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Current-main bypass: Current main omits any file containing a NUL byte as a binary file before static rules run, so the reported scanner bypass remains present in the released base. (internal/runner/static_scanner.go:223, 9f6a6fbb9f11)
• Scanner repair path: The PR replaces the unconditional omission with shared inspection, normalization, static-rule scanning, and an explicit NUL finding for inspectable content. (internal/runner/static_scanner.go:235, 0061bd41d5c3)
• Judge prompt boundary: The rendered target-file prompt uses normalized or decoded content and re-applies per-file and aggregate rendered-content budgets. (internal/runner/runner.go:1063, 0061bd41d5c3)
• Regression coverage: The branch adds coverage for NUL-obfuscated content, opaque PNG omission, UTF-16 decoding, decoded NUL code points, alternate raw representations, and expanded prompt budgets. (internal/runner/runner_test.go:3055, 0061bd41d5c3)
• Feature history: The current scanner omission behavior appears in the recent runner change authored by Peter Steinberger, making that area the closest current-main ownership signal. (internal/runner/static_scanner.go:223, 9f6a6fbb9f11)
• Release baseline: The current-main commit containing the bypass is included in v0.1.6, so the reported behavior remains on the latest released baseline rather than being already fixed upstream. (internal/runner/static_scanner.go:223, 9f6a6fbb9f11)

Likely related people:

• steipete: Authored the recent current-main runner change that contains the NUL binary-omission path and the proposed repair. (role: recent area contributor; confidence: high; commits: 9f6a6fbb9f11; files: internal/runner/static_scanner.go, internal/runner/runner.go)
• Jesse Merhi: Recent history shows repeated changes to runner execution, policy, sandbox, and artifact behavior adjacent to this prompt-rendering path. (role: recent runner contributor; confidence: medium; commits: e63bacb73e8e, 13c6cb59b581, a9b45ab69396; files: internal/runner/runner.go)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add a redacted terminal transcript or log showing the NUL-obfuscated scan result, normalized judge input, and opaque-binary behavior.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.