diff --git a/docs-site/src/content/docs/reference/cli-reference.md b/docs-site/src/content/docs/reference/cli-reference.md index 8bf8a83c..1258d2b6 100644 --- a/docs-site/src/content/docs/reference/cli-reference.md +++ b/docs-site/src/content/docs/reference/cli-reference.md @@ -19,6 +19,7 @@ awf [options] -- | Option | Type | Default | Description | |--------|------|---------|-------------| +| `--config ` | string | — | Path to AWF JSON/YAML config file (use `-` to read from stdin) | | `--allow-domains ` | string | — | Comma-separated list of allowed domains (optional; if not specified, all network access is blocked) | | `--allow-domains-file ` | string | — | Path to file containing allowed domains | | `--ruleset-file ` | string | `[]` | YAML rule file for domain allowlisting (repeatable) | @@ -35,6 +36,7 @@ awf [options] -- | `--image-registry ` | string | `ghcr.io/github/gh-aw-firewall` | Container image registry | | `--image-tag ` | string | `latest` | Container image tag. Supports optional per-image digest pinning: `,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...` | | `--skip-pull` | flag | `false` | Use local images without pulling from registry | +| `--docker-host ` | string | auto-detected | Docker socket for AWF's own containers | | `-e, --env ` | string | `[]` | Environment variable (repeatable) | | `--env-all` | flag | `false` | Pass all host environment variables | | `--exclude-env ` | string | `[]` | Exclude a variable from `--env-all` passthrough (repeatable) | @@ -44,8 +46,10 @@ awf [options] -- | `--memory-limit ` | string | `6g` | Memory limit for the agent container | | `--dns-servers ` | string | Auto-detected | Trusted DNS servers (comma-separated; auto-detected from host, falls back to `8.8.8.8,8.8.4.4`) | | `--dns-over-https [resolver-url]` | optional string | `https://dns.google/dns-query` | Enable DNS-over-HTTPS via sidecar proxy | +| `--upstream-proxy ` | string | auto-detected | Upstream (corporate) proxy URL for Squid to chain through | | `--proxy-logs-dir ` | string | — | Directory to save Squid proxy logs to | | `--audit-dir ` | string | — | Directory for firewall audit artifacts | +| `--session-state-dir ` | string | — | Directory to save Copilot CLI session state | | `--enable-host-access` | flag | `false` | Enable access to host services via host.docker.internal | | `--allow-host-ports ` | string | `80,443` | Ports to allow when using --enable-host-access | | `--allow-host-service-ports ` | string | — | Ports to allow ONLY to host gateway (for GitHub Actions `services:`) | @@ -58,15 +62,34 @@ awf [options] -- | `--openai-api-base-path ` | string | — | Base path prefix for OpenAI API requests | | `--anthropic-api-target ` | string | `api.anthropic.com` | Target hostname for Anthropic API requests | | `--anthropic-api-base-path ` | string | — | Base path prefix for Anthropic API requests | +| `--gemini-api-target ` | string | `generativelanguage.googleapis.com` | Target hostname for Gemini API requests | +| `--gemini-api-base-path ` | string | — | Base path prefix for Gemini API requests | | `--rate-limit-rpm ` | number | `600` | Max requests per minute per provider | | `--rate-limit-rph ` | number | `10000` | Max requests per hour per provider | | `--rate-limit-bytes-pm ` | number | `52428800` (~50 MB) | Max request bytes per minute per provider | | `--no-rate-limit` | flag | — | Disable rate limiting in API proxy | +| `--difc-proxy-host ` | string | — | Connect to external DIFC proxy and enable CLI proxy sidecar | +| `--difc-proxy-ca-cert ` | string | — | Path to TLS CA cert for external DIFC proxy verification | +| `--diagnostic-logs` | flag | `false` | Collect diagnostics on non-zero exit | | `-V, --version` | flag | — | Display version | | `-h, --help` | flag | — | Display help | ## Options Details +### `--config ` + +Load AWF options from a JSON or YAML config file. Use `-` to read config from stdin. + +CLI flags always take precedence over values loaded from the config file. + +```bash +# Load from file +sudo awf --config ./awf.yml -- curl https://api.github.com + +# Load from stdin +cat awf.yml | sudo awf --config - -- curl https://api.github.com +``` + ### `--allow-domains ` Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns, protocol-specific filtering, and special keywords. @@ -370,6 +393,18 @@ When using `--skip-pull`, you are responsible for verifying image authenticity. The `--skip-pull` flag cannot be used with `--build-local` since building images requires pulling base images from the registry. ::: +### `--docker-host ` + +Override the Docker socket used by AWF for its own container operations. + +```bash +sudo awf --docker-host unix:///run/user/1000/docker.sock \ + --allow-domains github.com \ + -- curl https://api.github.com +``` + +The value must be a `unix://` socket URI. + ### `-e, --env ` Pass environment variable to container. Can be specified multiple times. @@ -508,6 +543,18 @@ Enable DNS-over-HTTPS (DoH) via a sidecar proxy. When enabled, DNS queries are e Use `--dns-over-https` without a value to use the Google DNS default. Provide a custom URL only if your environment requires a specific resolver. ::: +### `--upstream-proxy ` + +Configure Squid to chain outbound traffic through an upstream corporate proxy. + +```bash +sudo awf --upstream-proxy http://proxy.corp.com:3128 \ + --allow-domains github.com \ + -- curl https://api.github.com +``` + +If omitted, AWF auto-detects host `https_proxy`/`http_proxy` settings. + ### `--enable-host-access` Enable access to host services via `host.docker.internal`. This allows containers to connect to services running on the host machine (e.g., local development servers, MCP gateways). @@ -605,6 +652,16 @@ ls ./audit/ Use `--audit-dir` in CI/CD pipelines to capture firewall configuration for audit trails. Can also be set via the `AWF_AUDIT_DIR` environment variable. ::: +### `--session-state-dir ` + +Directory to persist Copilot CLI session state (such as `events.jsonl`) during execution. + +```bash +sudo awf --session-state-dir ./session-state \ + --allow-domains github.com \ + -- copilot --prompt "hello" +``` + ### `--agent-image ` Specify the agent container image to use. Supports pre-built presets or custom base images. @@ -777,6 +834,35 @@ sudo -E awf --enable-api-proxy \ -- command ``` +### `--gemini-api-target ` + +Target hostname for Gemini API requests. Useful for private gateways or compatible Gemini endpoints. + +- **Default:** `generativelanguage.googleapis.com` +- **Requires:** `--enable-api-proxy` + +```bash +sudo -E awf --enable-api-proxy \ + --gemini-api-target ai-gateway.internal.example.com \ + --allow-domains ai-gateway.internal.example.com \ + -- command +``` + +### `--gemini-api-base-path ` + +Base path prefix prepended to Gemini API requests. + +- **Default:** none +- **Requires:** `--enable-api-proxy` + +```bash +sudo -E awf --enable-api-proxy \ + --gemini-api-target ai-gateway.internal.example.com \ + --gemini-api-base-path /gemini \ + --allow-domains ai-gateway.internal.example.com \ + -- command +``` + ### `--rate-limit-rpm ` Maximum number of requests per minute per provider. Rate limiting is opt-in — it is only enabled when at least one `--rate-limit-*` flag is provided. @@ -831,6 +917,33 @@ sudo -E awf --enable-api-proxy --no-rate-limit \ -- command ``` +### `--difc-proxy-host ` + +Connect to an external DIFC proxy (`mcpg`) and enable the CLI proxy sidecar for `gh` command routing. + +```bash +sudo awf --difc-proxy-host 127.0.0.1:5555 \ + --allow-domains github.com \ + -- gh repo view github/gh-aw-firewall +``` + +### `--difc-proxy-ca-cert ` + +Path to a CA certificate written by the external DIFC proxy. Recommended when using `--difc-proxy-host` over TLS. + +```bash +sudo awf --difc-proxy-host 127.0.0.1:5555 \ + --difc-proxy-ca-cert /tmp/mcpg-ca.crt \ + --allow-domains github.com \ + -- gh repo view github/gh-aw-firewall +``` + +### `--diagnostic-logs` + +Collect container logs, exit state, and a sanitized config snapshot when the wrapped command exits non-zero. + +Diagnostic artifacts are written to `/diagnostics/` (or `/diagnostics/` when `--audit-dir` is set). + :::caution When using a custom `--openai-api-target` or `--anthropic-api-target`, you must add the target domain to `--allow-domains` so the firewall permits outbound traffic. AWF emits a warning if a custom target is set but not in the allowlist. ::: @@ -963,6 +1076,7 @@ awf predownload [options] | `--image-tag ` | string | `latest` | Container image tag (applies to squid, agent, agent-act, api-proxy, and cli-proxy images). Supports optional digest metadata — see [`--image-tag`](#--image-tag-tag) for format details. | | `--agent-image ` | string | `default` | Agent image preset (`default`, `act`) or custom image | | `--enable-api-proxy` | flag | `false` | Also download the API proxy image | +| `--difc-proxy` | flag | `false` | Also download the CLI proxy image used when runtime flag `--difc-proxy-host` is set | :::tip After pre-downloading, use `--skip-pull` on subsequent runs to skip pulling images at runtime. @@ -977,6 +1091,9 @@ awf predownload # Pre-download including the API proxy image awf predownload --enable-api-proxy +# Pre-download including the CLI proxy image +awf predownload --difc-proxy + # Pre-download a specific version awf predownload --image-tag v0.3.0 diff --git a/docs/usage.md b/docs/usage.md index a0f2ea3f..efbf1277 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -6,6 +6,7 @@ sudo awf [options] -- Options: + --config Path to AWF JSON/YAML config file (use "-" to read from stdin) -d, --allow-domains Comma-separated list of allowed domains. Supports wildcards and protocol prefixes: - github.com: exact domain + subdomains (HTTP & HTTPS) - *.github.com: any subdomain of github.com @@ -43,31 +44,44 @@ Options: default → agent: act → agent-act: --skip-pull Use local images without pulling from registry (requires images to be - pre-downloaded) (default: false) + pre-downloaded) (default: false) + --docker-host Docker socket for AWF's own containers (default: auto-detect from + DOCKER_HOST env). Example: unix:///run/user/1000/docker.sock -e, --env Additional environment variables to pass to container (can be - specified multiple times) + specified multiple times) --env-all Pass all host environment variables to container (excludes system vars - like PATH) (default: false) - -v, --mount Volume mount (can be specified multiple times). Format: - host_path:container_path[:ro|rw] + like PATH) (default: false) + --exclude-env Exclude a specific environment variable from --env-all passthrough + (can be specified multiple times) + --env-file Read environment variables from a file (KEY=VALUE format, one per line) + -v, --mount Volume mount (can be specified multiple times). Format: + host_path:container_path[:ro|rw] --container-workdir Working directory inside the container (should match GITHUB_WORKSPACE for path consistency) --dns-servers Comma-separated list of trusted DNS servers. DNS traffic is ONLY - allowed to these servers (default: 8.8.8.8,8.8.4.4) + allowed to these servers (default: auto-detected from host resolvers, + falls back to 8.8.8.8,8.8.4.4) + --upstream-proxy Upstream (corporate) proxy URL for Squid to chain through. + Auto-detected from host https_proxy/http_proxy if not set. --proxy-logs-dir Directory to save Squid proxy logs to (writes access.log directly to - this directory) + this directory) + --audit-dir Directory for firewall audit artifacts (configs, policy manifest, + iptables state) --session-state-dir Directory to save Copilot CLI session state (events.jsonl, session - data). Writes directly during execution (timeout-safe, predictable - path). Also configurable via AWF_SESSION_STATE_DIR env var. + data). Writes directly during execution (timeout-safe, predictable + path). Also configurable via AWF_SESSION_STATE_DIR env var. --enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false) --allow-host-ports Comma-separated list of ports or port ranges to allow when using - --enable-host-access. By default, only ports 80 and 443 are allowed. - Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or - --allow-host-ports 3000-3010,8000-8090 + --enable-host-access. By default, only ports 80 and 443 are allowed. + Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or + --allow-host-ports 3000-3010,8000-8090 + --allow-host-service-ports Comma-separated ports to allow ONLY to host gateway + (for GitHub Actions services). Auto-enables host access. + Example: --allow-host-service-ports 5432,6379 --ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path - filtering for HTTPS) (default: false) + filtering for HTTPS) (default: false) --allow-urls Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump). Supports wildcards: https://github.com/myorg/* --enable-api-proxy Enable API proxy sidecar for holding authentication credentials. @@ -76,22 +90,32 @@ Options: --copilot-api-target Target hostname for Copilot API requests (default: api.githubcopilot.com) --openai-api-target Target hostname for OpenAI API requests (default: api.openai.com) + --openai-api-base-path Base path prefix for OpenAI API requests --anthropic-api-target Target hostname for Anthropic API requests - (default: api.anthropic.com) + (default: api.anthropic.com) + --anthropic-api-base-path Base path prefix for Anthropic API requests + --gemini-api-target Target hostname for Gemini API requests + (default: generativelanguage.googleapis.com) + --gemini-api-base-path Base path prefix for Gemini API requests --rate-limit-rpm Max requests per minute per provider (requires --enable-api-proxy) --rate-limit-rph Max requests per hour per provider (requires --enable-api-proxy) --rate-limit-bytes-pm Max request bytes per minute per provider (requires --enable-api-proxy) --no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy) + --difc-proxy-host Connect to an external DIFC proxy (Multi-Cloud Proxy Gateway, "mcpg") + and enable the CLI proxy sidecar for gh command routing + --difc-proxy-ca-cert Path to TLS CA cert written by external DIFC proxy --ruleset-file YAML rule file for domain allowlisting (repeatable). - Schema: version: 1, rules: [{domain, subdomains}] + Schema: version: 1, rules: [{domain, subdomains}] --dns-over-https [url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query) - --memory-limit Memory limit for the agent container (default: 2g) - Examples: 1g, 4g, 512m + --memory-limit Memory limit for the agent container (default: 6g) + Examples: 1g, 4g, 512m --enable-dind Enable Docker-in-Docker by exposing host Docker socket. WARNING: allows firewall bypass via docker run (default: false) --enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential - exfiltration in outbound request URLs. (default: false) + exfiltration in outbound request URLs. (default: false) + --diagnostic-logs Collect container logs, exit state, and sanitized config on non-zero + exit. Written to /diagnostics/ (or /diagnostics/) -V, --version Output the version number -h, --help Display help for command @@ -99,6 +123,13 @@ Arguments: command Command to execute (wrap in quotes, use -- separator) Commands: + predownload [options] Pre-download Docker images for offline use or faster startup + --image-registry Container image registry (default: ghcr.io/github/gh-aw-firewall) + --image-tag Container image tag (default: latest) + --agent-image Agent image preset (default, act) or custom image + --enable-api-proxy Also download the API proxy image + --difc-proxy Also download the CLI proxy image (for --difc-proxy-host) + logs [options] View and analyze Squid proxy logs -f, --follow Follow log output in real-time (like tail -f) --format Output format: raw, pretty (colorized), json @@ -113,6 +144,13 @@ Commands: logs summary [options] Generate summary report (markdown by default) --format Output format: json, markdown, pretty --source Path to log directory or "running" for live container + + logs audit [options] Show firewall audit with policy rule matching + --format Output format: json, markdown, pretty + --source Path to log directory or "running" for live container + --rule Filter to specific rule ID + --domain Filter to specific domain + --decision Filter to "allowed" or "denied" ``` ## Basic Examples