Skip to content

Commit ed55eb8

Browse files
committed
feat(sandbox): allow egress to private IP space via allowed_ips policy field
Add an allowed_ips field to NetworkEndpoint that accepts CIDR notation and exact IPs, enabling sandboxes to reach private IP space under policy control while maintaining SSRF protections for loopback and link-local addresses. Three modes are supported: - Default (no allowed_ips): all private IPs blocked (existing behavior) - Host + allowlist: domain must resolve to an IP in allowed_ips - Hostless allowlist (no host): any domain allowed if resolved IP matches Closes #59
1 parent 734ec5e commit ed55eb8

11 files changed

Lines changed: 1017 additions & 31 deletions

File tree

‎.agents/skills/generate-sandbox-policy/SKILL.md‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ Ask these when the user's intent is broad and more specificity is possible:
109109
| Multiple hosts in one policy | "Do all of these hosts need the same access level? If some need tighter restrictions, I can split them into separate policies." |
110110
| `access: full` with `enforcement: audit` | "Full access in audit mode means nothing is actually restricted — all traffic flows through and violations are only logged. Is that intentional, or did you want to enforce restrictions?" |
111111
| `**` path glob on all rules | "Using `**` on all paths allows any URL path. Do you know the specific API path prefixes you need (e.g., `/api/v1/`)?" |
112+
| Private/internal IP destination | "Does this service resolve to a private IP (10.x, 172.16.x, 192.168.x)? If so, you'll need `allowed_ips` to permit access — what CIDR range should be allowed?" |
112113

113114
### Auto-Discovery of API Docs for Well-Known Services
114115

@@ -160,9 +161,10 @@ Read architecture/security-policy.md
160161
Key sections to reference:
161162
- **Full YAML Policy Schema** — top-level structure
162163
- **`network_policies`** — rule structure
163-
- **`NetworkEndpoint`** fields — host, port, protocol, tls, enforcement, access, rules
164+
- **`NetworkEndpoint`** fields — host, port, protocol, tls, enforcement, access, rules, allowed_ips
164165
- **`L7Rule` / `L7Allow`** — method + path matching
165166
- **Access Presets** — `read-only`, `read-write`, `full`
167+
- **Private IP Access via `allowed_ips`** — CIDR allowlist for private IP space
166168
- **Validation Rules** — what combinations are valid/invalid
167169

168170
Also read the example policy for real-world patterns:
@@ -257,10 +259,35 @@ network_policies:
257259
- allow:
258260
method: <METHOD>
259261
path: "<glob_pattern>"
262+
# Optional: allow private IP destinations (CIDR or exact IP)
263+
# allowed_ips:
264+
# - "10.0.5.0/24"
260265
binaries:
261266
- { path: <binary_path> }
262267
```
263268

269+
### Private IP Destinations
270+
271+
When the endpoint resolves to a private IP (RFC 1918), the proxy's SSRF protection blocks the connection by default. Use `allowed_ips` to selectively allow specific private IP ranges:
272+
273+
- **Host + allowlist**: `host` + `allowed_ips` — domain must resolve to an IP in the allowlist
274+
- **Hostless allowlist**: `allowed_ips` only (no `host`) — any domain on the port is allowed if it resolves to an IP in the allowlist
275+
276+
Loopback (`127.0.0.0/8`) and link-local (`169.254.0.0/16`) are **always blocked** regardless of `allowed_ips`.
277+
278+
```yaml
279+
# Example: Allow access to internal service at a known private IP range
280+
internal_api:
281+
name: internal_api
282+
endpoints:
283+
- host: api.internal.corp
284+
port: 8080
285+
allowed_ips:
286+
- "10.0.5.0/24"
287+
binaries:
288+
- { path: /usr/bin/curl }
289+
```
290+
264291
### Policy Key Naming
265292

266293
Use descriptive snake_case keys: `github_api`, `nvidia_inference`, `internal_service_readonly`.
@@ -309,6 +336,8 @@ Evaluate the generated policy for overly broad access and **include warnings in
309336
| **Wildcard binary** (`*` or `**` in binary path) | "This policy allows any binary matching the glob pattern. A compromised or unexpected binary in that directory could use this policy. Consider listing specific binary paths." |
310337
| **`**` path glob** on all explicit rules | "All rules use `**` path patterns, which match any URL path. This is equivalent to a preset — consider using `access: read-only` (or similar) for clarity, or narrowing paths if you know the API structure." |
311338
| **Multiple broad endpoints** in one policy | "This policy grants the same broad access to N different hosts. If any of these hosts needs tighter restrictions later, you'll need to split the policy." |
339+
| **Hostless `allowed_ips`** (no `host` field) | "This endpoint has no `host` — any domain resolving to the allowed IP range on this port will be permitted. Consider adding a `host` field to restrict which domains can use this allowlist." |
340+
| **Broad CIDR** in `allowed_ips` (e.g., `10.0.0.0/8`) | "This `allowed_ips` entry covers a very broad range. Consider narrowing to a specific subnet (e.g., `10.0.5.0/24`) to minimize exposure." |
312341

313342
Format breadth warnings clearly in the output, e.g.:
314343

@@ -484,6 +513,34 @@ internal_svc:
484513
- { path: /usr/bin/curl }
485514
```
486515

516+
### Private IP Access (Host + Allowlist)
517+
518+
```yaml
519+
internal_db:
520+
name: internal_db
521+
endpoints:
522+
- host: db.internal.corp
523+
port: 5432
524+
allowed_ips:
525+
- "10.0.5.0/24"
526+
binaries:
527+
- { path: /usr/bin/curl }
528+
```
529+
530+
### Private IP Access (Hostless — Any Domain in Range)
531+
532+
```yaml
533+
private_services:
534+
name: private_services
535+
endpoints:
536+
- port: 8080
537+
allowed_ips:
538+
- "10.0.5.0/24"
539+
- "10.0.6.0/24"
540+
binaries:
541+
- { path: /usr/bin/curl }
542+
```
543+
487544
## Additional Resources
488545

489546
- Full policy schema: [architecture/security-policy.md](../../../architecture/security-policy.md)

‎.agents/skills/generate-sandbox-policy/examples.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -625,6 +625,108 @@ network_policies:
625625

626626
## File Operation Examples (update existing / create new)
627627

628+
## Private IP Access Examples (allowed_ips)
629+
630+
### Example P1: Internal Service with Known IP Range
631+
632+
**User**: "Allow curl to reach our internal API at api.internal.corp on port 8080. It resolves to 10.0.5.x addresses."
633+
634+
The user knows the service resolves to private IPs. Use `allowed_ips` to permit the specific subnet.
635+
636+
```yaml
637+
network_policies:
638+
internal_api:
639+
name: internal_api
640+
endpoints:
641+
- host: api.internal.corp
642+
port: 8080
643+
allowed_ips:
644+
- "10.0.5.0/24"
645+
binaries:
646+
- { path: /usr/bin/curl }
647+
```
648+
649+
**What this allows**: Connections to `api.internal.corp:8080` when DNS resolves to any IP in `10.0.5.0/24`.
650+
**What this blocks**: Connections if the domain resolves outside the allowlist, or to any loopback/link-local address.
651+
652+
---
653+
654+
### Example P2: Multiple Internal Subnets
655+
656+
**User**: "Our microservices are spread across 10.0.5.x and 10.0.6.x on port 8080. Let opencode reach any of them without listing every hostname."
657+
658+
Use a hostless endpoint with `allowed_ips` — any domain on port 8080 is allowed if it resolves to an IP in the listed ranges.
659+
660+
```yaml
661+
network_policies:
662+
private_services:
663+
name: private_services
664+
endpoints:
665+
- port: 8080
666+
allowed_ips:
667+
- "10.0.5.0/24"
668+
- "10.0.6.0/24"
669+
binaries:
670+
- { path: /usr/local/bin/opencode }
671+
```
672+
673+
**What this allows**: Any hostname on port 8080 whose DNS resolves to `10.0.5.0/24` or `10.0.6.0/24`.
674+
**What this blocks**: Any hostname resolving outside these ranges, or to loopback/link-local addresses.
675+
676+
**Note**: No `host` field means any domain name is accepted — only the resolved IP is checked. This is broader; use `host` when you know the specific hostname.
677+
678+
---
679+
680+
### Example P3: Private IP with L7 Inspection
681+
682+
**User**: "Allow read-only REST access to db-proxy.internal on port 3128. It's at 172.16.1.50."
683+
684+
Combine `allowed_ips` with L7 inspection for fine-grained control over a private service.
685+
686+
```yaml
687+
network_policies:
688+
db_proxy_readonly:
689+
name: db_proxy_readonly
690+
endpoints:
691+
- host: db-proxy.internal
692+
port: 3128
693+
protocol: rest
694+
enforcement: enforce
695+
access: read-only
696+
allowed_ips:
697+
- "172.16.1.50"
698+
binaries:
699+
- { path: /usr/bin/curl }
700+
```
701+
702+
**What this allows**: GET, HEAD, OPTIONS on any path to `db-proxy.internal:3128`, only if it resolves to `172.16.1.50`.
703+
**What this blocks**: POST, PUT, PATCH, DELETE, and connections resolving to any other IP.
704+
705+
---
706+
707+
### Example P4: Exact IP (No CIDR)
708+
709+
**User**: "Allow curl to reach exactly 10.0.5.20 on port 9090 via metrics.internal."
710+
711+
```yaml
712+
network_policies:
713+
metrics_internal:
714+
name: metrics_internal
715+
endpoints:
716+
- host: metrics.internal
717+
port: 9090
718+
allowed_ips:
719+
- "10.0.5.20"
720+
binaries:
721+
- { path: /usr/bin/curl }
722+
```
723+
724+
An exact IP is treated as `/32` — only that specific address is permitted.
725+
726+
---
727+
728+
## File Operation Examples (update existing / create new)
729+
628730
### Example F1: Add a New Policy to an Existing File
629731

630732
**User**: "Add read-only access to api.github.com for curl to my dev-sandbox-policy.yaml"

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)