claude-code/docs/g002-security-verification-map.md

G002 alpha security map and verification plan

Generated by worker-4 for OMX team task 5 on 2026-05-14.

Scope and coordination

• Active goal context: G002-alpha-security / Stream 6 day-one security and permissions gate.
• Worker ownership: worker-1 owns minimal implementation changes for workspace/path enforcement. worker-4 owns this repository map, integration verification plan, changed-file/commit report, and exact verification evidence.
• Boundary: this report does not mutate .omx/ultragoal and does not edit shared security/path tests.
• Parallel probe status: three native subagents were spawned for repository map, test probe, and change-slice probe, but all failed before returning findings with 429 Too Many Requests; local mapping below is based on direct repository inspection.

Current permission and path enforcement map

Runtime permission policy and enforcer

• rust/crates/runtime/src/permissions.rs

  • Owns the PermissionMode ordering and PermissionPolicy authorization contract.
  • Existing tests cover read-only denial, workspace-write escalation, prompt approvals/denials, danger-full-access allowance, override recording, and required-mode reporting.
  • Integration risk: any new dynamic file/path rule must preserve the existing PermissionPolicy::authorize semantics so prompt/override audit events remain stable.

• rust/crates/runtime/src/permission_enforcer.rs

  • PermissionEnforcer::check, check_with_required_mode, check_file_write, and check_bash convert policy outcomes into structured EnforcementResult payloads.
  • check_file_write currently has the direct write gate for workspace-write mode.
  • is_within_workspace is a string-prefix boundary check after simple relative-path joining; it does not canonicalize symlinks, .., Windows drive prefixes, or case variants.
  • Existing tests cover read-only denial, workspace-write inside/outside paths, trailing slashes, root equality, bash read-only heuristics, prompt-mode denial payloads, and structured denied fields.

File tool path handling

• rust/crates/runtime/src/file_ops.rs
  • read_file, write_file, and edit_file normalize paths before filesystem operations but do not themselves require a workspace root.
  • read_file_in_workspace, write_file_in_workspace, and edit_file_in_workspace exist as boundary-enforced wrappers.
  • validate_workspace_boundary canonicalizes through the caller-provided resolved path and checks starts_with(workspace_root).
  • is_symlink_escape detects direct symlink escapes by comparing canonical target to canonical workspace root.
  • Search tools (glob_search, grep_search) derive walk roots and prune heavy directories, but they are separate from the write enforcement path.
  • Existing tests cover oversized/binary reads, workspace-boundary read rejection, symlink escape detection, glob brace expansion, ignored directories, and grep/glob behavior.

Bash command validation

• rust/crates/runtime/src/bash_validation.rs
  • validate_command runs mode validation, sed validation, destructive warning checks, then path validation.
  • validate_read_only blocks write-like commands, state-modifying commands, write redirects, and mutating git subcommands in read-only mode.
  • validate_mode warns when workspace-write commands appear to target hard-coded system paths.
  • validate_paths warns for ../, ~/, and $HOME references; it is intentionally heuristic and does not resolve shell expansion or canonical targets.
  • Existing tests cover read-only blockers, destructive warnings, sed in-place blocking, path traversal/home warnings, command classification, and full pipeline allow/block/warn outcomes.

Sandbox and diagnostics surfaces

• rust/crates/runtime/src/sandbox.rs

  • Owns container/sandbox status detection and workspace-only sandbox command construction.
  • Relevant for day-one security because sandbox status must not overstate filesystem isolation.

• rust/crates/rusty-claude-cli/src/main.rs

  • Owns CLI permission-mode parsing, direct JSON/text diagnostic output, /permissions, /status, /doctor, and command dispatch paths.
  • Existing CLI integration tests under rust/crates/rusty-claude-cli/tests/ cover permission prompt scenarios and output-format contracts.

• rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs

  • End-to-end harness includes bash_permission_prompt_approved, bash_permission_prompt_denied, read/write file allow/deny, and plugin workspace-write scenarios.

Existing G002-adjacent coverage

• Unit-level permission coverage:

  • cargo test -p runtime permissions::tests
  • cargo test -p runtime permission_enforcer::tests
  • cargo test -p runtime bash_validation::tests
  • cargo test -p runtime file_ops::tests

• CLI and integration coverage:

  • cargo test -p rusty-claude-cli --test mock_parity_harness
  • cargo test -p rusty-claude-cli --test output_format_contract
  • cargo test -p rusty-claude-cli --test cli_flags_and_config_defaults

• Board/report validation coverage:

  • python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json
  • python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json

Recommended safe work slices

Implementation lane (owned by worker-1 unless re-scoped)

1. Replace string-prefix workspace boundary checks with canonical path comparison in the runtime enforcement path.

   • Primary files: rust/crates/runtime/src/permission_enforcer.rs, possibly shared helper extraction from rust/crates/runtime/src/file_ops.rs.
   • Regression cases: ../ traversal, symlink escape, root prefix collision (/workspace vs /workspacex), relative paths, trailing slash root equality.

2. Ensure direct file tools call workspace-aware wrappers when active permission mode is workspace-write.

   • Primary files: likely rust/crates/runtime/src/mcp_tool_bridge.rs and/or the runtime tool execution bridge that calls file_ops.
   • Regression cases: direct read/write paths, missing parent creation, symlink parent escape, and error payload stability.

3. Keep bash validation as a warning/classification layer unless a real shell-expansion resolver is introduced.

   • Primary files: rust/crates/runtime/src/bash_validation.rs, rust/crates/runtime/src/bash.rs.
   • Risk: heuristic parsing cannot faithfully resolve shell expansion, globs, aliases, or platform-specific path rules; avoid claiming hard enforcement unless execution sandbox or command resolver proves it.

Test lane (coordinate with worker-3/worker-1 before editing)

1. Add unit regressions close to each enforcement function before changing behavior.

   • permission_enforcer.rs: canonical path boundary and Windows-shaped path cases.
   • file_ops.rs: write/edit workspace wrappers with symlink parent escapes and missing file parent canonicalization.
   • bash_validation.rs: shell expansion/glob/path warnings remain warnings unless a resolver is introduced.

2. Add at least one integration test proving the runtime bridge actually routes file tools through workspace enforcement, not only helper functions.

   • Candidate: rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs for direct write denial and no file created outside workspace.

3. Preserve existing prompt/event visibility tests.

   • Candidate surfaces: permission prompt scenarios in mock_parity_harness.rs, status/doctor JSON in output_format_contract.rs.

Docs/reporting lane (owned by worker-4)

1. Keep this file as the integration handoff artifact for G002 mapping and verification.
2. Report changed files and commits relative to origin/main so the leader can integrate worker branches deterministically.
3. Include exact command evidence in the task lifecycle result.

Changed files relative to origin/main at map time

The worktree currently contains these files added relative to origin/main before this task report:

• .omx/cc2/board.json
• .omx/cc2/board.md
• .omx/cc2/issue-parity-intake.json
• .omx/cc2/issue-parity-intake.md
• .omx/cc2/render_board_md.py
• .omx/cc2/validate_issue_parity_intake.py
• scripts/cc2_board.py
• scripts/generate_cc2_board.py
• scripts/validate_cc2_board.py

This task adds:

• docs/g002-security-verification-map.md

Commits relative to origin/main at map time

• 8311655 — omx(team): auto-checkpoint worker-1 [1]
• c6e2a7d — omx(team): merge worker-1
• 481585f — omx(team): auto-checkpoint worker-1 [1]
• 74bbf4b — omx(team): auto-checkpoint worker-4 [unknown]
• 5c77896 — omx(team): auto-checkpoint worker-1 [1]
• 07dad88 — Classify issue and parity intake for CC2 board integration
• 424825f — task: G001 human board and docs rendering
• d15268e — Create a canonical CC2 board so every frozen ROADMAP heading is verifiably mapped
• 45b43b5 — Make the CC2 board schema executable for G001

Verification checklist for leader integration

Run these from the repository root unless noted:

1. Python board/schema validation:

   • python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json
   • python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json

2. Rust formatting and lint/type checks:

   • scripts/fmt.sh --check
   • (cd rust && cargo check --workspace)
   • (cd rust && cargo clippy --workspace --all-targets -- -D warnings)

3. Targeted G002 security tests:

   • (cd rust && cargo test -p runtime permissions::tests permission_enforcer::tests bash_validation::tests file_ops::tests)
   • (cd rust && cargo test -p rusty-claude-cli --test mock_parity_harness)

4. Full regression:

   • (cd rust && cargo test --workspace)

Worker-4 verification evidence (2026-05-14)

PASS:

• python3 scripts/validate_cc2_board.py --board .omx/cc2/board.json → PASS cc2 board validation; 729 items; ROADMAP headings 124/124; ROADMAP actions 542/542.
• python3 .omx/cc2/validate_issue_parity_intake.py .omx/cc2/issue-parity-intake.json → PASS issue/parity intake: 19 issue rows, 9 parity rows.
• scripts/fmt.sh --check → no output and zero exit before Rust checks continued.
• (cd rust && cargo check --workspace) → Finished dev profile successfully.
• (cd rust && cargo test -p runtime permissions::tests) → 9 passed.
• (cd rust && cargo test -p runtime permission_enforcer::tests) → 21 passed.
• (cd rust && cargo test -p runtime bash_validation::tests) → 32 passed.
• (cd rust && cargo test -p runtime file_ops::tests) → 14 passed.
• (cd rust && cargo test -p rusty-claude-cli --test mock_parity_harness) → 1 passed.

FAIL / integration blockers observed on this worktree:

• (cd rust && cargo clippy --workspace --all-targets -- -D warnings) failed in existing runtime code, not this docs-only task:
  • rust/crates/runtime/src/compact.rs:215 / :216: clippy::match_same_arms.
  • rust/crates/runtime/src/policy_engine.rs:5: clippy::duration-suboptimal-units.
  • rust/crates/runtime/src/sandbox.rs:295-302: clippy::map_unwrap_or.
• (cd rust && cargo test --workspace) failed after broad success in API/commands/plugins/runtime tests because rusty-claude-cli unit test tests::session_lifecycle_prefers_running_process_over_idle_shell asserted RunningProcess but observed IdleShell.
• Rerun of the specific failing test confirmed deterministic failure: (cd rust && cargo test -p rusty-claude-cli --bin claw tests::session_lifecycle_prefers_running_process_over_idle_shell -- --exact --nocapture) → 0 passed, 1 failed with the same IdleShell vs RunningProcess assertion.

Recommended owner for failures: not worker-4 unless re-scoped. These failures are outside the docs/report artifact and touch shared runtime/CLI implementation files.