Generate Sandbox Policy

Generate Sandbox Policy

Generate YAML sandbox network policies and network middleware configuration from API documentation and natural-language user requirements.

Overview

This skill translates a user's plain-language policy intent into a valid sandbox policy. The amount of detail the user provides determines the granularity of the generated policy — from broad L4 or preset-based policies (just a host:port) up to fine-grained per-endpoint L7 rules (full API docs).

The output is a network_policies YAML block, an optional network_middlewares block, and optionally a full policy file that conforms to the sandbox policy schema.

Step 1: Gather Inputs

Determine the Detail Tier

The user's input falls into one of three tiers. Work with whatever the user provides — do not require a higher tier than needed.

Minimal Tier (host + intent only)

The user provides API endpoints and a broad intent. No API docs needed.

Examples:

• "Allow curl to hit api.github.com, read-only"
• "Give claude full access to api.anthropic.com"
• "Let /usr/bin/myapp talk to internal-svc:8080 but only for reading"

This is sufficient for:

• L4-only policies (host:port + binary checks, no method or path rules)
• Preset-based L7 policies (read-only, read-write, full on all paths)

For this tier, default to:

• access: read-only when the user says "read", "browse", "view", "query", "fetch"
• access: read-write when the user says "read-write", "create", "update" (but not "delete")
• access: full when the user says "full access", "everything", "unrestricted"
• L4-only when the user says "just allow it", "pass through", or "no inspection". Omit protocol for explicit-proxy clients. Use protocol: tcp only when the workload must use native DNS and direct socket calls, the endpoint has a valid DNS hostname, and the selected runtime support (currently Docker and Podman).

Moderate Tier (host + partial path knowledge)

The user knows some API paths but doesn't have full docs.

Examples:

• "Allow GET on /api/v1/models and POST on /api/v1/completions at integrate.api.nvidia.com"
• "Read-only on /repos/** at api.github.com, but also allow POST on /repos/*/issues"

Generate explicit rules for the known paths. If the user also wants broader access beyond the specific paths, combine with a catch-all rule or suggest a preset instead.

Full Tier (complete API docs)

The user provides full API documentation. Accepted formats:

From the API docs, build an endpoint inventory — a list of (method, path, description) tuples. Group them logically (e.g., by resource or tag). Then generate precise rules that allow only what the user's intent requires.

Policy Intent

Regardless of tier, extract (or infer) these from the user's description:

If the host and access level are clear but binaries are not specified, ask the user which binary or process will be making the requests. Suggest common defaults like /usr/bin/curl, /usr/local/bin/claude, etc.

Step 2: Refine Scope (Clarification Loop)

Before generating the policy, proactively ask clarifying questions to help the user scope the policy down as narrowly as possible. The goal is the most restrictive policy that still satisfies the user's needs.

Required Clarifications

Always ask about these if the user hasn't already specified them:

Scoping-Down Questions

Ask these when the user's intent is broad and more specificity is possible:

Auto-Discovery of API Docs for Well-Known Services

When the user mentions a recognizable API host but hasn't provided docs, and the current tier is Minimal, attempt to upgrade to Full by searching for the API documentation online.

When to trigger:

• The host is a well-known public API (e.g., api.github.com, api.anthropic.com, api.openai.com, integrate.api.nvidia.com, api.stripe.com, api.slack.com, api.gitlab.com)
• The user has NOT already provided API docs
• The user has NOT explicitly asked for a broad preset ("just read-only, nothing fancy")

How to do it:

1. Tell the user: "I can look up the REST API docs for [service] to help generate a more precise policy. Want me to do that?"
2. If the user agrees (or hasn't declined), search for the docs:
   • Search the web with a query like "[service name] REST API documentation endpoints" or "[service name] OpenAPI spec"
   • Look for official documentation URLs in the results
3. Fetch the documentation page and extract the endpoint inventory (method + path pairs)
4. Use the discovered endpoints to offer tighter scoping: "I found [N] endpoints in the [service] API. Based on your intent, I can narrow the policy to just [subset]. Want me to do that, or keep the broader preset?"

When to skip:

• The user explicitly asked for a broad preset or said "don't bother with docs"
• The API is internal, private, or not publicly documented
• The host is not recognizable as a well-known service
• A previous search attempt for this host returned no useful results

Graceful fallback: If the search doesn't return usable API docs (results are irrelevant, docs are behind authentication, the page is too large to parse), fall back to the current tier without stalling. Say: "I couldn't find usable API docs for [host], so I'll generate the policy using a [preset/L4] approach. You can always provide docs later to tighten it."

When the User Can't Narrow Further

If the user confirms the policy must stay broad (they don't know the paths, need genuinely broad access, etc.), accept it but flag the breadth. Do not block policy generation — just make sure the warnings are visible in the output (see Step 6).

Iteration

You may need to go back and forth a few times. Keep the loop tight:

1. Ask one batch of clarifying questions (group related questions together)
2. Update your understanding based on the answer
3. If the answer reveals further scoping opportunities, ask a follow-up
4. Stop when the user confirms the scope or says to proceed

Do not over-interrogate. If the user has given a clear, specific request, skip clarification and go straight to generation. Only ask when there is genuine ambiguity or an opportunity to meaningfully reduce the attack surface.

Step 3: Read the Policy Schema

Read the published policy schema reference before generating or changing a policy. Published documentation is the authority for the current schema; do not infer fields from examples in this skill.

Key sections to reference:

• Policy Schema Reference — top-level structure
• network_policies — rule structure
• NetworkEndpoint fields — host, port, protocol, tls, enforcement, access, rules, allowed_ips
• L7Rule / L7Allow — method + path matching
• Access Presets — read-only, read-write, full
• Private IP Access via allowed_ips — CIDR allowlist for private IP space
• Network Middleware - top-level middleware configs, ordering, host selection, and failure behavior
• Validation Rules — what combinations are valid/invalid

When middleware is requested, also read the published supervisor middleware guide.

For enforcement concepts and the shipped baseline, read sandbox policies and the default policy reference. The default policy is built into the OpenShell runtime and applies when no explicit policy is supplied.

Validate the intended provider combination as well as the authored policy. An image endpoint can become credentialed after provider composition and block startup with ConfigurationInvalid. Repair the complete policy or provider selection using the published policy workflow; do not add allow_uninspected_credentials merely to bypass a startup error.

Step 4: Choose Policy Shape

Follow this decision tree based on the detail tier and user intent:

Is L7 inspection needed?
├─ No (user wants pass-through / "just allow it")
│   ├─ Explicit-proxy client → omit protocol
│   └─ Native DNS/socket client with a DNS hostname on a supported runtime → protocol: tcp
│
└─ Yes (user wants method/path control)
    │
    ├─ Does a preset match the intent exactly?
    │   ├─ Read-only (GET, HEAD, OPTIONS) → access: read-only
    │   ├─ Read-write (no DELETE)          → access: read-write
    │   └─ Everything                      → access: full
    │
    └─ No preset fits (specific paths, mixed broad+narrow, exclude certain paths)
        └─ Build explicit rules list
            └─ Requires either known paths from the user or full API docs

Principle: always choose the simplest representation that satisfies the intent. A preset is preferable to explicit rules when it covers the use case.

TLS Decision

Omit tls on every endpoint, regardless of port: the proxy auto-detects TLS and terminates it for inspection. skip is the only accepted non-empty value, reserved for upstreams requiring client-certificate mTLS or a non-HTTP protocol.

Do not "fix" a rejected value — including the removed terminate and passthrough spellings — by changing it to skip; remove the field instead. skip stops inspection, credential injection, and L7 rule enforcement for that endpoint, so it silently widens what the endpoint allows.

Middleware Decision

Add network_middlewares only when the user asks to inspect, transform, redact, or independently authorize admitted HTTP requests, final HTTP responses, or client WebSocket text messages. Request middleware runs after network and L7 policy admission and before provider credential injection. Response middleware runs on the matching final response before it returns to the sandbox.

• Use openshell/regex without gateway registration for fixed-pattern redaction of UTF-8 HTTP request bodies or complete client-to-upstream WebSocket text messages.
• Use an operator-owned middleware name only when it is already registered under [[openshell.supervisor.middleware]] and reachable from both the gateway and sandbox supervisors.
• Confirm that the implementation advertises the requested binding: HTTP_REQUEST/PRE_CREDENTIALS, HTTP_RESPONSE/PRE_RETURN, or WEBSOCKET_MESSAGE/PRE_CREDENTIALS. A host match alone does not enable inspection.
• WebSocket middleware inspects client text messages only, over both ws:// and wss://. Binary and upstream-to-client messages pass without inspection, even with fail_closed.
• on_error controls selected-stage failures. Explicit denials always block traffic. A failed WebSocket stage with fail_open can remain bypassed for the rest of the connection.
• Default on_error to fail_closed. Use fail_open only when bypassing the stage preserves the user's stated security requirement.
• Assign unique order values across the complete policy. Lower values run first, and at most 10 configs may be selected.
• Match the narrowest destination hosts possible with endpoints.include; use exclude when a broad selector has trusted exceptions.
• Do not select fail-closed middleware for tls: skip endpoints because the supervisor cannot inspect that traffic.

Mapping Paths to Glob Patterns (when building explicit rules)

Only needed for the Moderate and Full tiers. Translate API path parameters to glob patterns:

Path matching uses the runtime glob engine. Both * and ** may cross / boundaries; ? matches one character, and bracket classes such as [0-9] and [!0] are supported. Prefer segment-shaped patterns such as /repos/*/issues for readability, but do not rely on * to stop at /.

Building the Explicit Rules List

For each allowed operation, create an allow entry:

rules:
  - allow:
      method: GET
      path: "/api/v1/models/*"
  - allow:
      method: POST
      path: "/api/v1/completions"

Use the most specific pattern that covers the intent. Prefer narrow globs over ** when the API structure is known.

Step 5: Generate the Policy

Output Format

Generate a complete network_policies entry. Use this template:

network_policies:
  <policy_key>:
    name: <policy_key>
    endpoints:
      - host: <api_host>
        port: <port>
        protocol: rest          # Required for L7 inspection
        enforcement: enforce    # or audit
        # Use ONE of: access OR rules (never both)
        access: <preset>        # read-only | read-write | full
        # OR
        rules:
          - allow:
              method: <METHOD>
              path: "<glob_pattern>"
        # Optional: restrict resolved addresses (CIDR or exact IP). Required
        # for private IPs on wildcard or hostless endpoints.
        # allowed_ips:
        #   - "10.0.5.0/24"
    binaries:
      - { path: <binary_path> }

When middleware is requested, add it as a separate top-level map rather than nesting it under a network policy:

network_middlewares:
  <config_key>:
    name: <human_readable_name>
    middleware: <built_in_or_registered_name>
    order: 10
    config: {}
    on_error: fail_closed
    endpoints:
      include: ["<api_host>"]
      # exclude: ["<trusted_host>"]

The map key is the stable policy-local identity. Middleware selection is independent of the network policy entry that admitted the request.

Deny Rules

Use deny_rules to block specific dangerous operations while allowing broad access. Deny rules are evaluated after allow rules and take precedence. This is the inverse of the rules approach — instead of enumerating every allowed operation, you grant broad access and block a small set of dangerous ones.

# Example: Allow full access to GitHub but block admin operations
github_api:
  name: github_api
  endpoints:
    - host: api.github.com
      port: 443
      protocol: rest
      enforcement: enforce
      access: read-write
      deny_rules:
        - method: POST
          path: "/repos/*/pulls/*/reviews"
        - method: PUT
          path: "/repos/*/branches/*/protection"
        - method: "*"
          path: "/repos/*/rulesets"
  binaries:
    - { path: /usr/bin/curl }

Deny rules support the same matching capabilities as allow rules: method, path, and query parameter matchers. When generating policies, prefer deny rules when the user needs broad access with a small set of blocked operations — it produces a shorter, more maintainable policy than enumerating 60+ allow rules.

Private IP Destinations

The proxy's SSRF protection treats private (RFC 1918) destinations differently depending on how the endpoint names its host:

• Exact hostname (host: api.internal.corp) — the connection may reach the private addresses the hostname resolves to without allowed_ips.
• Wildcard host, hostless endpoint, or policy-advisor proposal — private resolved addresses are blocked unless allowed_ips covers them.

Use allowed_ips to pin the addresses an endpoint may reach. When it is set, every resolved address must fall within the list, including public addresses:

• Host + allowlist: host + allowed_ips — domain must resolve to an IP in the allowlist
• Hostless allowlist: allowed_ips only (no host) — any domain on the port is allowed if it resolves to an IP in the allowlist

Loopback (127.0.0.0/8), link-local (169.254.0.0/16), unspecified, and cloud metadata addresses are always blocked as upstream destinations regardless of allowed_ips.

The Google Cloud metadata emulator reserves 127.0.0.1:8174 in Linux sandboxes. OpenShell handles SDK discovery locally through the supervisor; do not add an allowed_ips exception or grant access to the host cloud metadata service. See the Google provider documentation.

# Example: Pin an internal service to a known private IP range
internal_api:
  name: internal_api
  endpoints:
    - host: api.internal.corp
      port: 8080
      allowed_ips:
        - "10.0.5.0/24"
  binaries:
    - { path: /usr/bin/curl }

Policy Key Naming

Use descriptive snake_case keys: github_api, nvidia_inference, internal_service_readonly.

Multiple Endpoints

If the user needs access to multiple hosts or the same host with different rules, either:

1. Same policy — multiple entries in endpoints if the binary set is the same
2. Separate policies — different policy keys if the binary sets differ

Step 6: Validate and Warn

Before presenting the policy to the user, verify correctness and flag breadth concerns.