Skip to content

Commit b73f722

Browse files
committed
feat(policy): add policy recommendation plumbing — denial aggregation, transport, approval pipeline, and mechanistic recommendations
Implement the infrastructure layer for automated policy recommendations (#204): - Proto: 9 new RPCs and messages for draft policy lifecycle (submit, get, approve, reject, approve-all, edit, undo, clear, history) - Persistence: SQLite/Postgres migrations and store methods for draft_policy_chunks and denial_summaries tables - Server: Full gRPC handler implementations with mechanistic mapper that auto-generates NetworkPolicyRule proposals from denial summaries - Sandbox: DenialAggregator with MPSC channel, deduplication, periodic flush to gateway via SubmitPolicyAnalysis - CLI: 'openshell draft' subcommand with get/approve/reject/approve-all/undo/clear/history operations - TUI: Draft recommendations panel accessible from sandbox policy view - Docs: Architecture documentation in architecture/policy-advisor.md
1 parent 36e8241 commit b73f722

29 files changed

Lines changed: 4223 additions & 30 deletions

‎architecture/policy-advisor.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
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

‎crates/navigator-cli/src/main.rs‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -374,6 +374,13 @@ enum Commands {
374374
command: Option<PolicyCommands>,
375375
},
376376

377+
/// Review and approve draft policy recommendations.
378+
#[command(visible_alias = "dr", hide = true, help_template = SUBCOMMAND_HELP_TEMPLATE)]
379+
Draft {
380+
#[command(subcommand)]
381+
command: Option<DraftCommands>,
382+
},
383+
377384
/// Manage provider configuration.
378385
#[command(hide = true, after_help = PROVIDER_EXAMPLES, help_template = SUBCOMMAND_HELP_TEMPLATE)]
379386
Provider {
@@ -1067,6 +1074,82 @@ enum SandboxCommands {
10671074
},
10681075
}
10691076

1077+
#[derive(Subcommand, Debug)]
1078+
enum DraftCommands {
1079+
/// Show pending draft policy recommendations.
1080+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1081+
Get {
1082+
/// Sandbox name (defaults to last-used sandbox).
1083+
name: Option<String>,
1084+
1085+
/// Filter by status (pending, approved, rejected).
1086+
#[arg(long)]
1087+
status: Option<String>,
1088+
},
1089+
1090+
/// Approve a single draft chunk.
1091+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1092+
Approve {
1093+
/// Sandbox name (defaults to last-used sandbox).
1094+
name: Option<String>,
1095+
1096+
/// Chunk ID to approve.
1097+
#[arg(long)]
1098+
chunk_id: String,
1099+
},
1100+
1101+
/// Reject a single draft chunk.
1102+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1103+
Reject {
1104+
/// Sandbox name (defaults to last-used sandbox).
1105+
name: Option<String>,
1106+
1107+
/// Chunk ID to reject.
1108+
#[arg(long)]
1109+
chunk_id: String,
1110+
1111+
/// Reason for rejection.
1112+
#[arg(long, default_value = "")]
1113+
reason: String,
1114+
},
1115+
1116+
/// Approve all pending draft chunks.
1117+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1118+
ApproveAll {
1119+
/// Sandbox name (defaults to last-used sandbox).
1120+
name: Option<String>,
1121+
1122+
/// Also approve security-flagged chunks.
1123+
#[arg(long)]
1124+
include_security_flagged: bool,
1125+
},
1126+
1127+
/// Undo an approved chunk (revert to pending, remove from policy).
1128+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1129+
Undo {
1130+
/// Sandbox name (defaults to last-used sandbox).
1131+
name: Option<String>,
1132+
1133+
/// Chunk ID to undo.
1134+
#[arg(long)]
1135+
chunk_id: String,
1136+
},
1137+
1138+
/// Clear all pending draft chunks.
1139+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1140+
Clear {
1141+
/// Sandbox name (defaults to last-used sandbox).
1142+
name: Option<String>,
1143+
},
1144+
1145+
/// Show draft policy history.
1146+
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
1147+
History {
1148+
/// Sandbox name (defaults to last-used sandbox).
1149+
name: Option<String>,
1150+
},
1151+
}
1152+
10701153
#[derive(Subcommand, Debug)]
10711154
enum PolicyCommands {
10721155
/// Update policy on a live sandbox.
@@ -1445,6 +1528,61 @@ async fn main() -> Result<()> {
14451528
}
14461529
}
14471530

1531+
// -----------------------------------------------------------
1532+
// Draft policy recommendations
1533+
// -----------------------------------------------------------
1534+
Some(Commands::Draft {
1535+
command: Some(draft_cmd),
1536+
}) => {
1537+
let ctx = resolve_gateway(&cli.gateway, &cli.gateway_endpoint)?;
1538+
let mut tls = tls.with_gateway_name(&ctx.name);
1539+
apply_edge_auth(&mut tls, &ctx.name);
1540+
match draft_cmd {
1541+
DraftCommands::Get { name, status } => {
1542+
let name = resolve_sandbox_name(name, &ctx.name)?;
1543+
run::sandbox_draft_get(&ctx.endpoint, &name, status.as_deref(), &tls).await?;
1544+
}
1545+
DraftCommands::Approve { name, chunk_id } => {
1546+
let name = resolve_sandbox_name(name, &ctx.name)?;
1547+
run::sandbox_draft_approve(&ctx.endpoint, &name, &chunk_id, &tls).await?;
1548+
}
1549+
DraftCommands::Reject {
1550+
name,
1551+
chunk_id,
1552+
reason,
1553+
} => {
1554+
let name = resolve_sandbox_name(name, &ctx.name)?;
1555+
run::sandbox_draft_reject(&ctx.endpoint, &name, &chunk_id, &reason, &tls)
1556+
.await?;
1557+
}
1558+
DraftCommands::ApproveAll {
1559+
name,
1560+
include_security_flagged,
1561+
} => {
1562+
let name = resolve_sandbox_name(name, &ctx.name)?;
1563+
run::sandbox_draft_approve_all(
1564+
&ctx.endpoint,
1565+
&name,
1566+
include_security_flagged,
1567+
&tls,
1568+
)
1569+
.await?;
1570+
}
1571+
DraftCommands::Undo { name, chunk_id } => {
1572+
let name = resolve_sandbox_name(name, &ctx.name)?;
1573+
run::sandbox_draft_undo(&ctx.endpoint, &name, &chunk_id, &tls).await?;
1574+
}
1575+
DraftCommands::Clear { name } => {
1576+
let name = resolve_sandbox_name(name, &ctx.name)?;
1577+
run::sandbox_draft_clear(&ctx.endpoint, &name, &tls).await?;
1578+
}
1579+
DraftCommands::History { name } => {
1580+
let name = resolve_sandbox_name(name, &ctx.name)?;
1581+
run::sandbox_draft_history(&ctx.endpoint, &name, &tls).await?;
1582+
}
1583+
}
1584+
}
1585+
14481586
// -----------------------------------------------------------
14491587
// Inference commands
14501588
// -----------------------------------------------------------
@@ -1864,6 +2002,13 @@ async fn main() -> Result<()> {
18642002
.print_help()
18652003
.expect("Failed to print help");
18662004
}
2005+
Some(Commands::Draft { command: None }) => {
2006+
Cli::command()
2007+
.find_subcommand_mut("draft")
2008+
.expect("draft subcommand exists")
2009+
.print_help()
2010+
.expect("Failed to print help");
2011+
}
18672012

18682013
None => {
18692014
Cli::command().print_help().expect("Failed to print help");

0 commit comments

Comments
 (0)