Add AWF Sandbox Specification v1.0.0

[Copilot]

Summary

Adds a formal W3C-style specification for the Agent Workflow Firewall (AWF) binary interface in docs/src/content/docs/reference/. The specification focuses exclusively on what AWF itself consumes and enforces — CLI arguments, flat domain lists, container isolation, and credential proxying. Compiler-level constructs (workflow frontmatter, ecosystem domain identifiers, engine definitions) are explicitly out of scope.

What's Included

The specification (awf-sandbox-specification.md, ~574 lines) covers:

AWF Command Interface (Section 4)

• Command structure with expandable and safe args separated by --
• Required arguments (--env-all, --allow-domains, --enable-api-proxy, --container-workdir, --log-level, --image-tag, etc.)
• Conditional arguments (--tty, --exclude-env, --block-domains, --mount, --memory-limit, --ssl-bump, API targets, etc.)
• Version-gated features (e.g., --exclude-env requires AWF ≥ v0.25.3)

Network Filtering (Section 5)

• Domain list format: literal domains, wildcards (*.example.com), protocol-qualified, IP addresses
• Allow/block semantics: default-deny, block precedence, subdomain inclusion, wildcard matching
• Proxy implementation via Squid forward proxy
• Explicit note that ecosystem identifiers are compiler constructs resolved before AWF invocation

Container Isolation (Section 6)

• Docker container model with mount syntax validation (source:destination:mode)
• Standard mounts, working directory, memory limits
• Environment variable passthrough (--env-all) and exclusion (--exclude-env)

API Proxy Sidecar (Section 7)

• Transparent credential injection for LLM provider APIs
• Custom API targets (--openai-api-target, --anthropic-api-target, --copilot-api-target)
• Base path support for path-prefixed endpoints

SSL Bump HTTPS Inspection (Section 8)

• HTTPS content inspection for URL path-level filtering
• URL pattern filtering via --allow-urls
• Certificate pinning considerations

Logging and Audit (Section 9)

• Log level validation (debug, info, warn, error)
• Proxy logs and audit directory artifacts (policy manifest, squid.conf, Docker Compose)

Compliance Testing (Section 11)

• 37 test IDs across 6 categories (CMD, NET, PRX, SSL, LOG)
• Three compliance levels (Required, Standard, Complete)

References

• Derived from AWF CLI interface in pkg/workflow/awf_helpers.go (BuildAWFCommand, BuildAWFArgs)
• Follows W3C conventions matching the existing MCP Gateway specification
• Uses RFC 2119 requirement keywords throughout

[pelikhan]

@copilot ignore MCP only focus on sandbox.awf

[pelikhan]

@copilot domains set is a compiler construct, awf only sees a list of domains

[pelikhan]

@copilot focus on the awf config file format, ignore current front matter

[Copilot]

@copilot ignore MCP only focus on sandbox.awf

Removed all MCP gateway content from the spec in 67ff498. The spec now focuses exclusively on sandbox.agent — removed Section 4.3 (MCP Gateway Runtime Configuration), the sandbox.mcp field from the top-level structure, MCP references from the architecture diagram, default behavior, test cases, changelog, and references. Added an explicit out-of-scope note deferring sandbox.mcp to the MCP Gateway Specification.

[Copilot]

@copilot domains set is a compiler construct, awf only sees a list of domains

Rewrote the network section in f7726ae. AWF now only documents flat domain lists (literal, wildcard, protocol-qualified, IP) received via --allow-domains and --block-domains. Ecosystem identifiers are explicitly called out as compiler constructs that are resolved before AWF is invoked. Removed all ecosystem identifier tables and expansion semantics.

@copilot focus on the awf config file format, ignore current front matter

Restructured the entire spec in f7726ae to focus on the AWF binary interface. Removed all frontmatter YAML syntax, engine definitions (EngineDefinition, ProviderSelection, AuthDefinition, RequestShape), engine-specific firewall behavior, sandbox config format, and FirewallConfig frontmatter structure. The spec now documents AWF's CLI arguments, network filtering behavior, container isolation, API proxy sidecar, SSL Bump, and audit logging — what AWF itself consumes and enforces.