Skip to content

fix(evidence): reject NUL bytes in subject and snapshot paths - #1873

Merged
morluto merged 1 commit into
morluto:mainfrom
DeryFerd:fix/evidence-subject-nul-path
Oct 11, 2026
Merged

morluto merged 1 commit into
morluto:mainfrom
DeryFerd:fix/evidence-subject-nul-path

Conversation

@DeryFerd

Copy link
Copy Markdown
Contributor

Summary

Evidence subject local_path and the analysis-snapshot subject path were plain strings, so an inline Evidence record supplied through a tool input could carry a NUL byte into the observation, the persisted snapshot, and any bundle written from it. Every other selected-path boundary in the repository already refuses NUL through the shared local-path schema, and a harness that exercises the real advertised MCP contracts asserts exactly that; the two Evidence subject schemas were the remaining gap. This PR routes both fields through the shared NUL-free schema, keeping the snapshot's nonempty rule and leaving the Evidence local_path free to be empty because network capture Evidence uses an empty path as a deliberate sentinel.

Problem and expected behavior

Smallest trigger: parse an Evidence record whose subject is { "local_path": "a\u0000b", ... }, for example through an inline source: { kind: "inline", evidence: ... } input on inspect_analysis_view or an imported bundle. Prior behavior: the schema accepted it, and the value flowed into subject.local_path on the observation and into any serialized snapshot or bundle. The violated invariant: a value the caller selects as a local filesystem path should be parsed once at the owning boundary, and NUL is never a valid filesystem path byte on any supported host, so it should be refused there rather than propagated as display data. Expected behavior: evidenceSchema and the snapshot subject schema reject a NUL local_path/path, an ordinary absolute or relative path is still accepted, and an empty Evidence local_path stays accepted because existing producers depend on it.

Change and scope

The NUL-free pattern now lives in src/domain/localPath.ts as nulFreeStringSchema, and localPathStringSchema is composed from it as nulFreeStringSchema.min(1) so the nonempty rule is expressed once instead of duplicated. src/domain/evidence.ts uses nulFreeStringSchema for subject.local_path because that field is legitimately empty for network capture Evidence, and src/domain/analysisSnapshot.ts uses localPathStringSchema for subject.path, which preserves the exact previous nonempty behavior while adding the NUL refusal. Intentionally not included: no change to subject.name, no change to any other string field, no new advertised contract shape, and no attempt to reinterpret the empty network-capture path as an error.

Contract and boundary impact

  • Semantic owner and earliest changed stage: domain contract schemas in src/domain/evidence.ts and src/domain/analysisSnapshot.ts, parsed at the tool-input and snapshot-import boundaries before any observation or bundle is built.
  • CLI and MCP/tool-catalog contract: the advertised JSON Schema for existing localPathStringSchema consumers is unchanged (the emitted pattern and minLength: 1 are byte-identical); the two Evidence subject fields gain the same NUL-rejecting pattern already used on every other path field, which is a validation tightening consistent with the existing boundary contracts.
  • Provider, bridge, target-format, or platform compatibility: none; the schema is provider-neutral and the NUL rule is host-independent.
  • Evidence, artifact, provenance, or reconstruction contract: accepted Evidence keeps byte-identical identity and digests; local_path was already excluded from the semantic identity, so no existing ev_/snapshot identity changes, and the tightening only rejects inputs that were never valid.
  • Process execution, authorization, cleanup, or containment impact: none; this is schema validation only.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in skill-src/ and never commit build outputs): none committed. .cache/mcp-tool-catalog.json is regenerated test metadata and is not part of the repository; the catalog digest moves only because the Evidence subject schema moved.

Evidence and regression coverage

  • Tests added or updated: a unit case in src/domain/evidence.test.ts asserts evidenceSchema accepts an ordinary path and an empty path and rejects a NUL local_path; a unit case in src/domain/analysisSnapshot.test.ts asserts the snapshot schema rejects a NUL subject path.
  • Base reproduction or other evidence: on the base revision both new cases fail because the fields accept any string; after the change the domain suite passes with no other expectation changes.
  • User-visible CLI/MCP output: a request carrying a NUL local path now fails validation at the boundary with the shared "Local filesystem paths cannot contain NUL" message instead of being accepted and later serialized.
  • Remaining proof gaps: no real provider or browser run applies to this schema-only change; the behavior is fully exercised by the unit and boundary suites listed below.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npx vitest run src/domain/ — 126 files, 1704 tests passed, including the new Evidence and snapshot cases.
  • npx vitest run tests/boundary/mcp/evidenceBundleInline.test.ts tests/boundary/mcp/retainedApplicationEvidenceMcp.test.ts — passed.
  • npx vitest run tests/acceptance/tools/localToolContracts.test.ts — passed, including the existing OS-invalid-local-input harness that rejects NUL through the real advertised MCP contracts.
  • npx vitest run tests/boundary/mcp/toolSchemaValidity.test.ts — 8 passed after npm run mcp-catalog:generate.
  • npm run typecheck — exit 0 after rebasing onto bcd350c36.
  • npx oxlint on the five changed files — 0 errors (the no-control-regex and max-lines warnings are pre-existing on the base); oxfmt --check on the committed (LF) form — clean.
  • Real Hopper/Ghidra, browser, or OS lanes: not applicable; no provider, bridge, or platform-specific code is touched.

Compatibility, safety, and release

  • Breaking changes or migration steps: none for valid callers. An input that carried a NUL path was already invalid on every host, so it now fails earlier with a named constraint; all previously accepted valid paths, including the empty network-capture path, still parse identically.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable; the boundary suites above cover the changed schemas.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: the change closes a small boundary inconsistency where an OS-invalid byte could be carried into retained Evidence and bundle output; it adds no network, process, or authority surface.

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Evidence subject local_path and analysis-snapshot subject path accepted
any string, so a caller-supplied inline Evidence record could carry a NUL
byte into the observation and bundle output even though every other
selected-path boundary already refuses it. Both fields now use the shared
NUL-free local-path schema: the snapshot path keeps its nonempty rule,
and the Evidence local_path stays free to be empty because network
capture Evidence uses an empty path as a deliberate sentinel.

localPath.ts now exports the NUL-free base schema separately so the
nonempty rule is composed rather than duplicated; the advertised pattern
and minLength for existing localPathStringSchema consumers are unchanged.

Validation: new unit cases reject a NUL local_path and snapshot path while
admitting an empty Evidence path and an ordinary path; domain suite
126 files / 1704 tests pass, evidence bundle and retained-evidence MCP
boundaries pass, localToolContracts NUL harness passes, toolSchemaValidity
passes with a regenerated catalog, typecheck, oxlint, oxfmt.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-11T15:13:08.534444Z ed0a1e7 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@morluto
morluto merged commit fa9a7e5 into morluto:main Oct 11, 2026
31 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 11, 2026
3 tasks done
@morluto

morluto commented Oct 11, 2026

Copy link
Copy Markdown
Owner

A small boundary gap with real provenance consequences—thanks for closing it, @DeryFerd. Reusing the NUL-free path schema blocks invalid local paths before they enter Evidence or snapshots, while preserving the intentionally empty network-capture path. That edge case is especially well handled.

@morluto morluto added bug Something isn't working area: evidence Evidence, artifacts, and reconstruction labels Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: evidence Evidence, artifacts, and reconstruction bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants