feat: policy recommendation plumbing — denial aggregation, transport, approval pipeline, and mechanistic recommendations #204

Activity

1. johntmyers

   added

   state:agent-readyApproved for agent implementationApproved for agent implementation

   area:cliCLI-related workCLI-related work

   feat

   area:policyPolicy engine and policy lifecycle workPolicy engine and policy lifecycle work

   area:sandboxSandbox runtime and isolation workSandbox runtime and isolation work

   area:gatewayGateway server and control-plane workGateway server and control-plane work

   area:tuiTerminal UI workTerminal UI work

   and removed

   state:agent-readyApproved for agent implementationApproved for agent implementation

   on Mar 10, 2026
2. johntmyers commented on Mar 11, 2026

   

   johntmyers

   on Mar 11, 2026

   Last edited by johntmyers

   CollaboratorAuthor

   More actions

   🏗️ build-plan

   Implementation Plan

   Issue type: feat
   Complexity: High
   Confidence: High — all patterns are well-established in the codebase, the RFC is thorough, and the design has been simulated

   Summary

   Build the end-to-end policy recommendation pipeline: a sandbox-side DenialAggregator that captures structured deny events from the proxy and L7 relay, a deterministic mechanistic mapper that converts denial summaries into proposed policy chunks, gRPC transport to submit analysis results, gateway persistence with two new tables, an approval workflow that merges approved chunks into the active policy via existing UpdateSandboxPolicy internals, streaming notifications via DraftPolicyUpdate, CLI subcommands under openshell sandbox draft, and a TUI draft panel.

   Scope

   • proto/navigator.proto: New messages (DenialSummary, L7RequestSample, PolicyChunk, DraftPolicyUpdate, SubmitPolicyAnalysis*, GetDraftPolicy*, ApproveDraftChunk*, RejectDraftChunk*, ApproveAllDraftChunks*, EditDraftChunk*, UndoDraftChunk*, GetDraftHistory*) + new RPCs on Navigator service + new SandboxStreamEvent oneof variant
   • crates/navigator-server/migrations/sqlite/003_create_policy_recommendations.sql + postgres/003_...: New draft_policy_chunks and denial_summaries tables
   • crates/navigator-server/src/persistence/mod.rs: New record types (DraftChunkRecord, DenialSummaryRecord) + new delegation methods on Store enum
   • crates/navigator-server/src/persistence/sqlite.rs: Concrete implementations for new Store methods
   • crates/navigator-server/src/persistence/postgres.rs: Same for Postgres
   • crates/navigator-server/src/grpc.rs: 8 new RPC handlers + DraftPolicyUpdate on WatchSandbox stream
   • crates/navigator-sandbox/src/denial_aggregator.rs (new): DenialAggregator state machine with dedup windows, cooldown, L7 sample ingestion, cmdline sanitization, memory bounds
   • crates/navigator-sandbox/src/mechanistic_mapper.rs (new): Deterministic DenialSummary[] → PolicyChunk[] mapper (Stage 1 L7 audit + Stage 2 access refinement)
   • crates/navigator-sandbox/src/proxy.rs: Thread DenialEvent sender through proxy; emit structured deny events at CONNECT deny (line ~331), FORWARD deny (line ~1490), and SSRF deny points — Option A from codebase analysis (direct callback, no string parsing)
   • crates/navigator-sandbox/src/l7/relay.rs: Emit structured L7 deny/audit events to the aggregator channel (alongside existing tracing event at line ~123)
   • crates/navigator-sandbox/src/lib.rs: Spawn aggregator + analysis trigger loop as background tasks (after policy poll spawn at line ~537)
   • crates/navigator-sandbox/src/grpc_client.rs: New submit_policy_analysis() method on CachedNavigatorClient
   • crates/navigator-cli/src/main.rs: New DraftCommands enum nested under SandboxCommands, with Get, Approve, Reject, ApproveAll/Apply, Edit, Undo, Clear, History subcommands
   • crates/navigator-cli/src/run.rs: Handler functions for each draft subcommand
   • crates/navigator-tui/src/app.rs: New Focus::SandboxDraft variant, draft state fields, handle_draft_key() handler
   • crates/navigator-tui/src/ui/sandbox_draft.rs (new): Draft recommendations panel renderer
   • crates/navigator-tui/src/ui/mod.rs: Wire draft panel into draw_sandbox_screen()
   • crates/navigator-tui/src/lib.rs: Draft data fetching, Event::DraftResult variant

   Implementation Steps

   The steps are sequenced so each is independently testable.

   Step 1: Proto definitions

   Add all new messages and RPCs to proto/navigator.proto. This is the contract everything else builds against.

   New messages:

   • L7RequestSample (method, path, decision, count)
   • DenialSummary (sandbox_id, host, port, binary, ancestors, deny_reason, timestamps, counts, L7 samples, denial_stage, etc.)
   • PolicyChunk (id, status, stage, rule_name, proposed_rule: NetworkPolicyRule, rationale, security_notes, confidence, denial_summary_ids, supersedes_chunk_id)
   • DraftPolicyUpdate (draft_version, new_chunks, total_pending, summary)
   • Request/response pairs for all 8 RPCs
   • SubmitPolicyAnalysisRequest (summaries[], proposed_chunks[], analysis_mode)

   New SandboxStreamEvent oneof variant: DraftPolicyUpdate draft_policy_update = 5

   New RPCs on Navigator service:

   • SubmitPolicyAnalysis (sandbox → gateway)
   • GetDraftPolicy, ApproveDraftChunk, RejectDraftChunk, ApproveAllDraftChunks, EditDraftChunk, UndoDraftChunk, GetDraftHistory (CLI/TUI → gateway)

   Build to verify proto generation succeeds.

   Step 2: Persistence layer

   Create migration files 003_create_policy_recommendations.sql for both SQLite and Postgres:

   draft_policy_chunks table:

   • id TEXT PRIMARY KEY, sandbox_id TEXT NOT NULL, draft_version INTEGER NOT NULL, status TEXT NOT NULL DEFAULT 'pending', stage TEXT NOT NULL DEFAULT 'initial', rule_name TEXT NOT NULL, proposed_rule BLOB NOT NULL (protobuf NetworkPolicyRule), rationale TEXT NOT NULL, security_notes TEXT, confidence REAL, denial_refs TEXT NOT NULL (JSON array), supersedes_chunk_id TEXT, created_at_ms INTEGER NOT NULL, decided_at_ms INTEGER, decided_by TEXT
   • Index: (sandbox_id, status)

   denial_summaries table:

   • id TEXT PRIMARY KEY, sandbox_id TEXT NOT NULL, host TEXT NOT NULL, port INTEGER NOT NULL, binary TEXT NOT NULL, ancestors TEXT, deny_reason TEXT NOT NULL, timestamps, counts (count, suppressed_count, total_count), sample_cmdlines TEXT (JSON), binary_sha256 TEXT, persistent BOOLEAN, denial_stage TEXT, resolved_ips TEXT (JSON), is_private_ip BOOLEAN, l7_request_samples TEXT (JSON), l7_inspection_active BOOLEAN, status TEXT DEFAULT 'new', timestamps
   • Index: (sandbox_id, status), unique index: (sandbox_id, host, port, binary)

   Add record types (DraftChunkRecord, DenialSummaryRecord) and Store methods:

   • put_draft_chunk, get_draft_chunk, list_draft_chunks (with status filter), update_draft_chunk_status, update_draft_chunk_rule, delete_draft_chunks_by_sandbox
   • upsert_denial_summary, list_denial_summaries (with status filter), update_denial_summary_status
   • get_draft_version (max draft_version for sandbox), increment_draft_version

   Implement on both SqliteStore and PostgresStore. Write unit tests for CRUD operations.

   Step 3: Gateway gRPC handlers — submission + query

   Implement the receiving side:

   SubmitPolicyAnalysis handler:

   1. Validate sandbox exists
   2. For each denial summary: resolve DNS (tokio::net::lookup_host), annotate resolved_ips + is_private_ip, reject loopback/link-local hosts (reuse is_internal_ip logic from proxy.rs)
   3. Rate limit: count pending chunks for sandbox, reject if >= max_outstanding (10)
   4. Upsert denial summaries
   5. Validate each proposed chunk: format checks (rule_name, endpoint fields, binary paths), reject bad ones
   6. Persist valid chunks, increment draft_version
   7. Publish DraftPolicyUpdate event via SandboxWatchBus::notify()

   GetDraftPolicy handler:

   1. Validate sandbox exists
   2. Query list_draft_chunks with optional status_filter
   3. Return chunks + draft_version

   GetDraftHistory handler:

   1. List all chunks for sandbox ordered by created_at_ms
   2. Map to DraftHistoryEntry (created, approved, rejected events)

   Wire DraftPolicyUpdate into WatchSandbox stream — add a new arm in the tokio::select! loop. Reuse SandboxWatchBus notifications (the handler already re-reads from store on notification, so we just need to include draft data in the notification path, or add a separate subscription channel for draft events).

   Step 4: Gateway gRPC handlers — approval workflow

   ApproveDraftChunk handler:

   1. Validate chunk exists and is pending
   2. Load current active policy via get_latest_loaded_policy (or get_latest_policy with fallback)
   3. Pre-merge conflict detection: check if rule_name already exists in network_policies map
   4. Insert chunk's proposed_rule into network_policies map under chunk.rule_name
   5. Run validate_policy_safety() on merged policy
   6. Persist via existing update_sandbox_policy internals: deterministic_hash, put_policy_revision, supersede_older_policies, sandbox_watch_bus.notify()
   7. Update chunk status → approved, decided_at_ms, decided_by
   8. Update denial_summaries referenced by chunk → resolved
   9. If chunk.stage == "refined" and chunk.supersedes_chunk_id is set: update superseded chunk status → superseded, remove its rule from active policy (replace with refined rule)
   10. Return new policy version + hash

   RejectDraftChunk handler:

   1. Validate chunk exists and is pending
   2. Update status → rejected, store reason
   3. Return success

   ApproveAllDraftChunks handler:

   1. List all pending chunks for sandbox
   2. If !include_security_flagged, filter out chunks where security_notes is non-empty
   3. Merge all remaining chunks into active policy (batch)
   4. Persist, update statuses
   5. Return version + hash + counts

   EditDraftChunk handler:

   1. Validate chunk exists and is pending
   2. Replace proposed_rule with new rule from request
   3. Run validate_policy_safety() on the edited rule in isolation
   4. Persist

   UndoDraftChunk handler:

   1. Validate chunk exists and is approved
   2. Load current policy, remove chunk's rule_name from network_policies
   3. Persist updated policy
   4. Revert chunk status → pending

   Step 5: Sandbox DenialAggregator

   New module crates/navigator-sandbox/src/denial_aggregator.rs.

   Define DenialEvent enum:

   L4Deny { host, port, binary, binary_pid, ancestors, cmdline_paths, reason }
   L7Event { host, port, binary, l7_action, l7_target, l7_decision, l7_deny_reason }
   SsrfDeny { host, port, reason }
   

   DenialAggregator struct with HashMap<(String, u16, String), AggregatorEntry>:

   • AggregatorEntry: window_count, suppressed_count, total_count, distinct_cmdlines: HashSet<String>, first_seen, last_seen, in_cooldown, cooldown_until, l7_request_samples: HashMap<(String,String), L7SampleAccum>, l7_inspection_active, deny_reason, ancestors

   State machine (from RFC Section 9d):

   1. Sanitize cmdline (redact Authorization, X-Vault-Token, Cookie, X-Api-Key, passwords, query tokens)
   2. Lookup or create entry (with max_keys=1000 cap + overflow counter)
   3. Always: total_count++, last_seen=now, add cmdline, update L7 samples if L7 event
   4. If in cooldown: suppressed_count++, skip
   5. Else: window_count++, check threshold (3) or persistent_threshold (10)
   6. On threshold: emit DenialSummary, enter cooldown, reset window + suppressed

   Periodic sweep (30s):

   • Expire stale entries (age > 2*dedup_window, total < persistent_threshold)
   • Stale-flush (age > 5m, not in cooldown): emit with persistent=true
   • Overflow summary if overflow_count > 0

   Thread the sender channel through:

   • ProxyHandle::start_with_bind_addr() in proxy.rs → accept loop → handle_tcp_connection() → CONNECT/FORWARD handlers
   • relay_with_inspection() in relay.rs (or emit alongside existing tracing event)

   Step 6: Sandbox mechanistic mapper + analysis loop

   New module crates/navigator-sandbox/src/mechanistic_mapper.rs.

   generate_chunks(summaries: &[DenialSummary], existing_chunks: &[PolicyChunk]) -> Vec<PolicyChunk>:

   Stage 1 (new host:port, no existing chunk):

   • HTTP ports (80, 443, 8080, 8200, 9200): protocol: rest, tls: terminate (443), enforcement: audit, access: full
   • Other ports: plain L4 allow
   • Rule name: auto_{sanitized_host}_{port}
   • Rationale: template string with count + host + port + binary

   Stage 2 (summary has L7 samples, existing approved Stage 1 chunk):

   • Analyze methods: all GET/HEAD/OPTIONS → read-only; POST no DELETE → read-write; DELETE → full
   • enforcement: enforce, supersedes_chunk_id → Stage 1 chunk
   • Rationale: template with method summary

   Analysis trigger loop (spawned in lib.rs after policy poll):

   • Collect summaries from aggregator
   • Run mechanistic mapper
   • Call submit_policy_analysis() via CachedNavigatorClient
   • Adaptive interval: 10s cold-start, 60s steady-state, back-off on no-op

   Step 7: CLI subcommands

   Add DraftCommands enum nested under SandboxCommands:

   Draft {
       name: Option<String>,
       #[command(subcommand)]
       command: Option<DraftSubcommands>,
   }
   

   DraftSubcommands: Get (with --chunks, --chunk <id> flags), Approve (chunk_id or --all with --force), Reject (chunk_id, --reason), Apply, Clear, Edit (chunk_id, --allowed-ips, --access, --add-binary), Undo (chunk_id), History

   Handler functions in run.rs:

   • draft_get(): call GetDraftPolicy, format output (policy overview or chunk detail)
   • draft_approve(): call ApproveDraftChunk, display merge result + wait for sandbox reload
   • draft_reject(): call RejectDraftChunk
   • draft_approve_all() / draft_apply(): call ApproveAllDraftChunks
   • draft_edit(): load chunk, modify fields, call EditDraftChunk
   • draft_undo(): call UndoDraftChunk
   • draft_clear(): call bulk delete (may need a ClearDraftChunks RPC or iterate)
   • draft_history(): call GetDraftHistory, format timeline

   Output formatting follows existing patterns: section headers in cyan bold, key-value in dimmed labels, YAML for proposed rules via navigator_policy::serialize_*.

   Step 8: TUI draft panel

   Add Focus::SandboxDraft variant in app.rs. Add state fields: draft_chunks: Vec<PolicyChunk>, draft_scroll: usize, draft_selected: usize, draft_version: u64, pending_draft_fetch: bool, show_draft_detail: bool.

   Keybinding cycle update: SandboxPolicy → l → SandboxLogs → d → SandboxDraft → p → SandboxPolicy.

   handle_draft_key(): j/k navigate, Enter toggle detail popup, a approve selected, r reject selected, A approve all, p/l switch views, Esc back.

   New ui/sandbox_draft.rs: render chunk list with status badges, rationale preview, denial count + recency. Detail popup with full proposed YAML + rationale + denial refs.

   Data fetching: on entering sandbox draft view, set pending_draft_fetch = true. In lib.rs event loop, call GetDraftPolicy RPC. For approve/reject actions, spawn gRPC calls and refresh on completion.

   Wire DraftPolicyUpdate from WatchSandbox log stream: detect draft_policy_update variant in the stream handler, update draft state.

   Step 9: Architecture doc — architecture/policy-advisor.md

   New product-level architecture document capturing the holistic view of the policy recommendation feature (spanning both #204 and #205). Written in the style of the existing architecture/ docs (mermaid diagrams, descriptive prose, tables). Covers:

   • What the feature does and why (the problem: dead-end denials, manual remediation)
   • End-to-end logical flow: deny event → aggregation → analysis → transport → persistence → approval → merge → sandbox reload
   • Architecture diagram (sandbox components, gateway components, user touchpoints)
   • Message infrastructure: DenialSummary, PolicyChunk, DraftPolicyUpdate, and how they flow between components
   • The living draft policy concept (chunks, stages, supersession, status lifecycle)
   • Two analysis modes: mechanistic (deterministic, no LLM) and LLM-powered PolicyAdvisor (future, feat: LLM-powered PolicyAdvisor agent harness for intelligent policy recommendations #205)
   • Progressive L7 visibility: Stage 1 (L7 audit) → Stage 2 (refined from observed traffic)
   • Trust boundary: sandbox proposes, gateway validates, user approves
   • UX surfaces: CLI openshell sandbox draft commands, TUI draft panel, log stream notifications

   This is a product/architecture doc, not an engineering spec — it should be readable by someone who wants to understand what the system does without reading code.

   Step 10: Tests + verification

   Unit tests:

   • denial_aggregator.rs: threshold/cooldown/dedup, L7 sample accumulation, memory cap, stale-flush, cmdline sanitization
   • mechanistic_mapper.rs: Stage 1 generation (HTTP vs non-HTTP ports), Stage 2 refinement (method analysis), rule naming, supersession

   Integration tests (if feasible without full cluster):

   • Proto round-trip: serialize/deserialize new messages
   • Persistence: CRUD on both new tables via SQLite Store
   • Approval merge: create sandbox with policy, submit chunks, approve, verify merged policy

   Pre-commit: mise run pre-commit

   Test Plan

   • Unit tests: DenialAggregator state machine (threshold, cooldown, L7 samples, memory bounds, cmdline sanitization), mechanistic mapper (Stage 1/2 generation, edge cases), persistence CRUD for new tables. Tests live alongside their modules.
   • Integration tests: Full approval flow (submit → persist → approve → merge → verify policy version). Proto serialization round-trips for new message types. These can run against an in-memory SQLite store.
   • E2E tests: Defer to follow-up — the full sandbox deny → aggregate → submit → approve flow requires a running sandbox. CLI sandbox draft smoke tests could be added if cluster is available.

   Risks & Open Questions

   1. Proxy channel threading: Adding a sender to handle_tcp_connection and handle_forward_proxy touches a hot path. Benchmark try_send overhead (should be negligible but worth confirming).
   2. WatchSandbox DraftPolicyUpdate delivery: Reusing SandboxWatchBus::notify() means the client re-reads all sandbox state. A dedicated draft bus would be more efficient but adds complexity. Start with the notify approach.
   3. Approval atomicity: Approving a chunk involves read-modify-write on the active policy. Concurrent approvals need optimistic locking (check policy hash before persisting). The existing deterministic_hash + no-op check provides this.
   4. ClearDraftChunks RPC: The issue mentions sandbox draft clear but no dedicated RPC was specified. May need a ClearDraftChunks RPC or reuse bulk status update.
   5. Large file changes: grpc.rs (3645 lines), proxy.rs (2276 lines), main.rs (2196 lines), run.rs (3678 lines) are already large. Changes are additive (new handlers/commands), not modifying existing code, so risk is manageable.

   Documentation Impact

   • architecture/policy-advisor.md (new): Product-level architecture doc for the full policy recommendation feature (Step 9)
   • architecture/security-policy.md: Add section on draft policy chunks and approval workflow
   • architecture/sandbox.md: Add DenialAggregator and mechanistic mapper description
   • architecture/gateway.md: Add draft policy persistence and approval RPCs

   ---

   Revision 2 — added Step 9: architecture/policy-advisor.md product-level doc
   Revision 1 — initial plan
3. johntmyers

   added

   state:review-readyReady for human reviewReady for human review

   on Mar 11, 2026
4. johntmyers

   self-assigned this

   on Mar 11, 2026
5. johntmyers

   added

   state:agent-readyApproved for agent implementationApproved for agent implementation

   state:in-progressWork is currently in progressWork is currently in progress

   on Mar 11, 2026
6. johntmyers

   added a commit that references this issue on Mar 11, 2026

   feat(policy): add policy recommendation plumbing — denial aggregation…

   ...

   40fca82
7. johntmyers

   closed this as completedin #222on Mar 12, 2026
8. johntmyers

   added a commit that references this issue on Mar 12, 2026

   feat(policy): add policy recommendation plumbing (#204) (#222)

   ...

   795aa48
9. drew

   added 2 commits that reference this issue on Mar 16, 2026

   feat(policy): add policy recommendation plumbing (#204) (#222)

   ...

   454327d

   feat(policy): add policy recommendation plumbing — denial aggregation…

   ...

   b73f722