diff --git a/docs/g002-security-verification-map.md b/docs/g002-security-verification-map.md new file mode 100644 index 00000000..3f5909e7 --- /dev/null +++ b/docs/g002-security-verification-map.md @@ -0,0 +1,160 @@ +# 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 .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 .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)` +