[aisecnomad]

Summary

Seven external reviews and the v0.1.0 audit (347 findings) made overlapping, sometimes conflicting recommendations for making Nexus SymBiote the reference AgentBOM tool. This change checks every recommendation against main (3ad53a2) and against primary sources, consolidates them into one roadmap (ROADMAP.md), and implements its "Delivered" set. Each commit is one self-contained unit and can be reviewed on its own.

Closes verified gate bypasses (each reproduced at main first; each now fails a default gate):

• IDE settings that were recognized but not bound (.cursor/cli.json Shell(ls) → Shell(*), a Codex notify command, the Antigravity, xAI and Copilot files) are now digested, after redaction so the digest cannot confirm a guessed secret.
• Unassigned default-ignorable code points (U+2065, U+FFF0–U+FFF8, U+E0080–U+E00FF, U+E01F0–U+E0FFF) are hidden-character findings and are neutralized in output.
• Hugging Face chat templates get the sandbox-escape check GGUF templates get.
• .git, node_modules, __pycache__, .venv and venv inside agent directories are coverage gaps; nested GEMINI.md and .cursorrules are collected.
• JavaScript-family MCP servers are analysed, and SDK forms the analysis cannot follow (require, import(), npm:/jsr:/URL/path specifiers, non-literal names, Python dynamic imports, servers launched from application code) are named gaps instead of silent skips.
• Audit residuals: the hidden Python MCP syntax-tree cap is the operator limit python-nodes; nested case variants of instruction files are failures; registry and index redirects for inventoried packages (.npmrc including scope, .yarnrc*, bunfig.toml, requirements index options, project pip.conf/pip.ini, uv, Poetry and PDM sources) are recorded with credentials withheld and a low registry_origin finding; the Action's scanners input says naming collectors makes coverage partial.
• Final review (four parallel adversarial reviews, two skeptics per finding, then an independent check of every fix): every default-ignorable code point is neutralized in output; the unkeyed settings digest binds every host and command and fails on ambiguous URL authorities; symlinked and case-variant chat templates are read or fail; Python launchers and server classes from unrecognized modules and any literal MCP module argument are gaps; trace-diff never matches a call to a tool served at another address and fails on attribute lists over its bound.

Adds evidence features (all offline):

• digest and SOURCE_DATE_EPOCH: byte-identical native JSON, CycloneDX and SPDX for identical inputs, and a content digest (nexus-symbiote/inventory-content/v1) that is equal for equal content.
• attest / verify-attestation: DSSE + in-toto Statement v1 with Ed25519, threshold, purpose, age and byte or content matching; trusted keys inside the checkout are refused.
• trace-diff: OpenTelemetry GenAI/MCP traces (OTLP/JSON) reconciled with the inventory; undeclared runtime use is a high runtime_undeclared finding; content attributes are never read; telemetry is recorded as reported, never as verification.
• Framework crosswalk: every finding category has a SARIF rule; tags add OWASP LLM 2026, MITRE ATLAS 2026.10 and NIST AI RMF; crosswalk reports findings per framework entry (a reading aid, not a compliance verdict).
• minimum-elements: coverage of the 50 G7 AI SBOM minimum elements with its denominator; never a compliance verdict.
• graph: a self-contained, CSP-hashed HTML view (or JSON) with derived risk classes and shortest exposure paths; unclassified means unknown, not safe.
• export-inventory --format shadowscan-simple: the reviewed repository agent as ShadowScan's approved inventory, checked against ShadowScan 0.1.4's own loader and matcher.

Merged with current main (#131, #132): main's deterministic export (ARCH-F1) and this branch's reproducible inventories share one serial, the UUIDv5 of the inventory content digest (profile nexus-symbiote/inventory-content/v1). Without SOURCE_DATE_EPOCH an inventory records no collection time, so native JSON and CycloneDX are byte-identical by default; with it, SPDX is too and the G7 "SBOM timestamp" element is present.

Validation (on the pushed tree, Python 3.13): make check (ruff, format, mypy strict, workflow, hygiene and lock checks, the full suite with coverage floors, the security regression corpus with 22 cases, build and twine check) and make wheel-smoke: 8,269 passed and 2 expected case-sensitive-file-system skips, package coverage 95.17% statements and 91.16% branches with every floor met, 22 security regression cases with 0 failures, and both distributions pass twine check. Every bypass fix has a regression test shown to fail on the previous code. The documented demo is unchanged (11 components, score 37). End to end on examples/demo-agent: two scans at different paths are byte-identical and share the content digest; attest/verify-attestation accept content matching and refuse a wrong purpose; the graph page renders under its CSP with no console errors in headless Chromium.

Related issues

None.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Security fix (see SECURITY.md for reporting guidelines)
• Refactoring (no functional changes)

Breaking: new coverage gaps and bound settings files can fail a default gate that passed before (see CHANGELOG Changed); a malformed SOURCE_DATE_EPOCH now exits 2; SARIF rules exist for every category, so code scanning shows new rule ids for categories that used the generic rule.

Checklist

make check runs the offline subset of the required CI checks. See CONTRIBUTING.md.

• Tests cover the new or changed behavior
• ruff check src tests scripts passes
• ruff format --check src tests scripts passes
• mypy src/nexus_symbiote scripts passes
• Workflow, repository hygiene and lock checks pass (make workflow-check hygiene lock-check)
• Dependency changes: locks regenerated with make lock, and the "Dependency health" run is green (no dependency changes)
• Documentation updated (if applicable)
• CHANGELOG.md updated under Unreleased

Review record

Written with AI assistance (Claude Code), in one session. Every unit was implemented by one agent, reviewed adversarially by a separate agent that did not write it, and fixed with a regression test per confirmed finding (each regression test was shown to fail against the pre-fix code). The integrated change then went through a multi-dimension adversarial review in which each finding needed two independent skeptics to confirm it before it was fixed. All of these ran inside the same session, so none of them is an independent human review. No human has reviewed the rendered diff yet: the maintainer's review after Verified CI finishes is still required.

Security-sensitive changes

• Trust boundary and abuse case stated (each guide's trust model; docs/known-limitations.md and SECURITY.md updated)
• Regression test fails on the vulnerable behavior (every closed bypass has one, checked against main)
• Security regression corpus reviewed (scripts/benchmark_security.py; four new hidden-character cases)
• No new network access, executable discovery, or credential collection without design and tests (every new command is offline and runs under the offline guard in tests/test_modes.py)

Limitations

• Maintainer decisions left open: settings files bound before this change (Claude Code, Gemini CLI, Windsurf, Cline, .cursor/settings.json, .codex/config.json) keep an unkeyed digest of the file as read, so a holder of the inventory can confirm a guess of a value in them, including Gemini MCP environment values; moving them to the redacted digest changes every baseline once. The release workflow exports SOURCE_DATE_EPOCH, so the release evidence now records the commit time.
• Static analysis of Python and TypeScript MCP sources stays incomplete by nature: computed module names, getattr/globals()/code in strings, and SDK aliases resolved outside the file (Node # imports, tsconfig paths, import maps) leave no gap; the new literal-argument rule can report a gap for an unrelated call that names an MCP module. All documented in docs/known-limitations.md.
• trace-diff evidence is reported: the agent's own instrumentation can omit or forge spans; a missing span proves nothing. A one-object 64 MiB trace can take about 2 GB of memory.
• crosswalk and minimum-elements are reading aids and coverage reports, never compliance verdicts; NIST AI RMF, EU AI Act, ISO/IEC 42001 and CWE identifiers were checked against secondary sources.
• Symbolic links that no collector would read stay collection failures: telling a link to a directory from a link to a file would mean examining a path outside the project.
• Tests that parse Markdown use markdown-it-py, which all three locks carry only through rich; no lock was changed.
• Only Linux with Python 3.11-3.14 is qualified, as before.

---

Generated by Claude Code

[aisecnomad]

Security & Engineering Verification Summary (Approved for Merge)

• CI & Provenance Gates: All 19/19 GitHub Actions checks (Verified CI, CodeQL, Tests Python 3.11–3.14, Coverage Python 3.12, Composite Action end to end, Committed security regression contracts) passed on c5f97be049 (0 commits behind main).
• Local Static & Security Verification: ruff check, ruff format --check (307 files), mypy (106 source files, 0 issues), check_workflows.py, check_locks.py, check_repository_hygiene.py (474 tracked paths), and check_security_regressions.py (22 cases, 0 failures) all passed.
• Subsystem Security Audit:
  • Attestation & Content Digest (attestation.py, content_digest.py): DSSEv1 PAE verified prior to JSON parsing; strict I-JSON + RFC 8785 JCS canonicalization; match='bytes' recomputes content_digest from verified native bytes; --trusted-key enforces st_nlink == 1 and working-tree exclusion by (st_dev, st_ino).
  • HTML/SVG Graph View (graph_view.py): Strict CSP (default-src 'none' with SHA-256 style/script hashes), neutralize() + html.escape(..., quote=True) across all untrusted inventory strings, and zero DOM HTML/eval sinks.
  • OTLP Trace Evidence & Scanners (otlp.py, trace_evidence.py, ide_agents.py, mcp.py, model.py, prompt.py, registry.py, ts_tools.py): Explicit byte/span/attribute/node bounds, linear-time $O(N)$ resolvers, redacted IDE config digests, and Unicode 15.1 default-ignorable neutralization.
• Follow-ups Tracked:
  • Resolving the 2 false-positive crosswalk.py:260 (FRAMEWORK_KEYS) threads (crosswalk_cli.py and test suites import FRAMEWORK_KEYS; __all__ export + trace_evidence.py:_endpoint URL authority guard + macOS APFS case-folding confinement in PR #140 follow immediately).