|
| 1 | +# Policy Advisor |
| 2 | + |
| 3 | +The Policy Advisor is a recommendation system that observes denied connections in a sandbox and proposes policy updates to allow legitimate traffic. It operates as a feedback loop: denials are detected, aggregated, analyzed, and presented to the user as draft policy chunks for review and approval. |
| 4 | + |
| 5 | +This document covers the plumbing layer (issue #204). The LLM-powered agent harness that enriches recommendations with context-aware rationale is covered separately (issue #205). |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +```mermaid |
| 10 | +flowchart LR |
| 11 | + PROXY[Sandbox Proxy] -->|DenialEvent| AGG[DenialAggregator] |
| 12 | + AGG -->|flush every 30s| GW[Gateway Server] |
| 13 | + GW --> MAPPER[Mechanistic Mapper] |
| 14 | + MAPPER --> STORE[(SQLite/Postgres)] |
| 15 | + STORE --> CLI[CLI: openshell draft] |
| 16 | + STORE --> TUI[TUI: Draft Panel] |
| 17 | + CLI -->|approve/reject| GW |
| 18 | + TUI -->|view| GW |
| 19 | + GW -->|merge rule| POLICY[Active Policy] |
| 20 | +``` |
| 21 | + |
| 22 | +## Components |
| 23 | + |
| 24 | +### Denial Aggregator (Sandbox Side) |
| 25 | + |
| 26 | +The `DenialAggregator` (`crates/navigator-sandbox/src/denial_aggregator.rs`) runs as a background tokio task inside the sandbox supervisor. It: |
| 27 | + |
| 28 | +1. Receives `DenialEvent` structs from the proxy via an unbounded MPSC channel |
| 29 | +2. Deduplicates events by `(host, port, binary)` key with running counters |
| 30 | +3. Periodically flushes accumulated summaries to the gateway via `SubmitPolicyAnalysis` gRPC |
| 31 | + |
| 32 | +The flush interval defaults to 30 seconds (configurable via `OPENSHELL_DENIAL_FLUSH_INTERVAL_SECS`). |
| 33 | + |
| 34 | +### Denial Event Sources |
| 35 | + |
| 36 | +Events are emitted at four denial points in the proxy: |
| 37 | + |
| 38 | +| Source | Stage | File | Description | |
| 39 | +|--------|-------|------|-------------| |
| 40 | +| CONNECT OPA deny | `connect` | `proxy.rs` | No matching network policy rule | |
| 41 | +| CONNECT SSRF deny | `ssrf` | `proxy.rs` | Resolved IP is internal/private | |
| 42 | +| FORWARD OPA deny | `forward` | `proxy.rs` | Forward proxy policy deny | |
| 43 | +| FORWARD SSRF deny | `ssrf` | `proxy.rs` | Forward proxy SSRF check failed | |
| 44 | + |
| 45 | +L7 (per-request) denials from `l7/relay.rs` are captured via tracing in the current implementation, with structured channel support planned for issue #205. |
| 46 | + |
| 47 | +### Mechanistic Mapper (Server Side) |
| 48 | + |
| 49 | +The `mechanistic_mapper` module (`crates/navigator-server/src/mechanistic_mapper.rs`) generates draft policy recommendations deterministically, without requiring an LLM: |
| 50 | + |
| 51 | +1. Groups denial summaries by `(host, port)` |
| 52 | +2. For each group, generates a `NetworkPolicyRule` allowing that endpoint for the observed binaries |
| 53 | +3. Computes confidence scores based on: |
| 54 | + - Denial count (higher count = higher confidence) |
| 55 | + - Port recognition (well-known ports like 443, 5432 get a boost) |
| 56 | + - SSRF origin (SSRF denials get lower confidence) |
| 57 | +4. Generates security notes for private IPs, database ports, and ephemeral port ranges |
| 58 | +5. Avoids rule name collisions with existing policies |
| 59 | + |
| 60 | +The mapper is invoked automatically when `SubmitPolicyAnalysis` receives denial summaries without pre-computed proposed chunks. |
| 61 | + |
| 62 | +### Persistence |
| 63 | + |
| 64 | +Draft chunks and denial summaries are stored in the gateway database: |
| 65 | + |
| 66 | +```sql |
| 67 | +-- draft_policy_chunks: individual rule proposals |
| 68 | +CREATE TABLE draft_policy_chunks ( |
| 69 | + id TEXT PRIMARY KEY, |
| 70 | + sandbox_id TEXT NOT NULL, |
| 71 | + draft_version INTEGER NOT NULL, |
| 72 | + status TEXT NOT NULL DEFAULT 'pending', -- pending | approved | rejected |
| 73 | + stage TEXT NOT NULL DEFAULT '', |
| 74 | + rule_name TEXT NOT NULL, |
| 75 | + proposed_rule BLOB NOT NULL, -- protobuf-encoded NetworkPolicyRule |
| 76 | + rationale TEXT NOT NULL DEFAULT '', |
| 77 | + security_notes TEXT NOT NULL DEFAULT '', |
| 78 | + confidence REAL NOT NULL DEFAULT 0.0, |
| 79 | + denial_refs TEXT NOT NULL DEFAULT '', |
| 80 | + supersedes_chunk_id TEXT NOT NULL DEFAULT '', |
| 81 | + analysis_mode TEXT NOT NULL DEFAULT 'mechanistic', |
| 82 | + created_at_ms INTEGER NOT NULL, |
| 83 | + decided_at_ms INTEGER, |
| 84 | + decided_by TEXT NOT NULL DEFAULT '' |
| 85 | +); |
| 86 | + |
| 87 | +-- denial_summaries: aggregated denial patterns |
| 88 | +CREATE TABLE denial_summaries ( |
| 89 | + id TEXT PRIMARY KEY, |
| 90 | + sandbox_id TEXT NOT NULL, |
| 91 | + host TEXT NOT NULL, |
| 92 | + port INTEGER NOT NULL, |
| 93 | + ... |
| 94 | +); |
| 95 | +``` |
| 96 | + |
| 97 | +Both tables use migrations in `crates/navigator-server/migrations/{sqlite,postgres}/003_create_policy_recommendations.sql`. |
| 98 | + |
| 99 | +## Approval Workflow |
| 100 | + |
| 101 | +Draft chunks follow a simple state machine: |
| 102 | + |
| 103 | +```mermaid |
| 104 | +stateDiagram-v2 |
| 105 | + [*] --> pending: proposed |
| 106 | + pending --> approved: approve |
| 107 | + pending --> rejected: reject |
| 108 | + approved --> pending: undo |
| 109 | + pending --> [*]: clear |
| 110 | +``` |
| 111 | + |
| 112 | +### Approval Actions |
| 113 | + |
| 114 | +| Action | CLI Command | gRPC RPC | Effect | |
| 115 | +|--------|-------------|----------|--------| |
| 116 | +| View drafts | `openshell draft get` | `GetDraftPolicy` | List pending/approved/rejected chunks | |
| 117 | +| Approve one | `openshell draft approve --chunk-id X` | `ApproveDraftChunk` | Merge rule into active policy, mark approved | |
| 118 | +| Reject one | `openshell draft reject --chunk-id X` | `RejectDraftChunk` | Mark rejected (no policy change) | |
| 119 | +| Approve all | `openshell draft approve-all` | `ApproveAllDraftChunks` | Bulk approve (skips security-flagged unless `--include-security-flagged`) | |
| 120 | +| Undo | `openshell draft undo --chunk-id X` | `UndoDraftChunk` | Remove rule from policy, revert to pending | |
| 121 | +| Clear | `openshell draft clear` | `ClearDraftChunks` | Delete all pending chunks | |
| 122 | +| History | `openshell draft history` | `GetDraftHistory` | Show timeline of proposals and decisions | |
| 123 | + |
| 124 | +### Policy Merge |
| 125 | + |
| 126 | +When a chunk is approved, the server: |
| 127 | + |
| 128 | +1. Decodes the chunk's `proposed_rule` (protobuf `NetworkPolicyRule`) |
| 129 | +2. Fetches the current active `SandboxPolicy` |
| 130 | +3. Inserts the rule into `network_policies` by name |
| 131 | +4. Persists a new policy revision with deterministic hash |
| 132 | +5. Supersedes older policy versions |
| 133 | +6. Notifies watchers (triggers sandbox policy poll) |
| 134 | + |
| 135 | +The sandbox picks up the new policy on its next poll cycle (default 30 seconds) and hot-reloads the OPA engine. |
| 136 | + |
| 137 | +## User Interfaces |
| 138 | + |
| 139 | +### CLI |
| 140 | + |
| 141 | +The `openshell draft` command group provides full CRUD: |
| 142 | + |
| 143 | +```bash |
| 144 | +# View pending recommendations |
| 145 | +openshell draft get my-sandbox |
| 146 | + |
| 147 | +# Approve a specific chunk |
| 148 | +openshell draft approve my-sandbox --chunk-id abc123 |
| 149 | + |
| 150 | +# Approve all safe recommendations |
| 151 | +openshell draft approve-all my-sandbox |
| 152 | + |
| 153 | +# Reject with reason |
| 154 | +openshell draft reject my-sandbox --chunk-id xyz789 --reason "not needed" |
| 155 | + |
| 156 | +# Undo a previous approval |
| 157 | +openshell draft undo my-sandbox --chunk-id abc123 |
| 158 | + |
| 159 | +# Clear all pending |
| 160 | +openshell draft clear my-sandbox |
| 161 | +``` |
| 162 | + |
| 163 | +### TUI |
| 164 | + |
| 165 | +The TUI sandbox screen includes a "Draft" panel accessible via `[r]` from the policy view. It displays: |
| 166 | + |
| 167 | +- List of draft chunks with status indicators (pending/approved/rejected) |
| 168 | +- Confidence scores |
| 169 | +- Expanded endpoint and binary details for the selected chunk |
| 170 | +- Security warnings for flagged proposals |
| 171 | + |
| 172 | +Navigation: `[j/k]` to select chunks, `[p]` to return to policy, `[l]` for logs. |
| 173 | + |
| 174 | +## Configuration |
| 175 | + |
| 176 | +| Environment Variable | Default | Description | |
| 177 | +|---------------------|---------|-------------| |
| 178 | +| `OPENSHELL_DENIAL_FLUSH_INTERVAL_SECS` | `30` | How often the aggregator flushes to the gateway | |
| 179 | +| `OPENSHELL_POLICY_POLL_INTERVAL_SECS` | `30` | How often the sandbox polls for policy updates | |
| 180 | + |
| 181 | +## Future Work (Issue #205) |
| 182 | + |
| 183 | +The LLM PolicyAdvisor agent will: |
| 184 | + |
| 185 | +- Wrap the mechanistic mapper with LLM-powered analysis |
| 186 | +- Generate context-aware rationale explaining *why* each rule is recommended |
| 187 | +- Group related denials into higher-level recommendations |
| 188 | +- Detect patterns (e.g., "this looks like a pip install") and suggest broader rules |
| 189 | +- Provide interactive refinement via chat |
0 commit comments