Skip to content

Sync CLI docs and refresh compiled workflow artifacts for consistency checker #2115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 7 commits into from
Apr 20, 2026
Merged

Sync CLI docs and refresh compiled workflow artifacts for consistency checker #2115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
295c226
Initial plan
Copilot Apr 20, 2026
22194e8
docs: sync CLI flag documentation with implementation
Copilot Apr 20, 2026
be084ba
docs: clarify DIFC proxy flag wording
Copilot Apr 20, 2026
ef4028b
Update docs/usage.md
lpcox Apr 20, 2026
8d576da
Initial plan
Copilot Apr 20, 2026
c19f2cc
chore: rebase main and recompile workflows
Copilot Apr 20, 2026
ee264d0
Revert broken lock file changes
lpcox Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions docs-site/src/content/docs/reference/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ awf [options] -- <command>

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--config <path>` | string | — | Path to AWF JSON/YAML config file (use `-` to read from stdin) |
| `--allow-domains <domains>` | string | — | Comma-separated list of allowed domains (optional; if not specified, all network access is blocked) |
| `--allow-domains-file <path>` | string | — | Path to file containing allowed domains |
| `--ruleset-file <path>` | string | `[]` | YAML rule file for domain allowlisting (repeatable) |
Expand All @@ -35,6 +36,7 @@ awf [options] -- <command>
| `--image-registry <url>` | string | `ghcr.io/github/gh-aw-firewall` | Container image registry |
| `--image-tag <tag>` | string | `latest` | Container image tag. Supports optional per-image digest pinning: `<tag>,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 <socket>` | string | auto-detected | Docker socket for AWF's own containers |
| `-e, --env <KEY=VALUE>` | string | `[]` | Environment variable (repeatable) |
| `--env-all` | flag | `false` | Pass all host environment variables |
| `--exclude-env <name>` | string | `[]` | Exclude a variable from `--env-all` passthrough (repeatable) |
Expand All @@ -44,8 +46,10 @@ awf [options] -- <command>
| `--memory-limit <limit>` | string | `6g` | Memory limit for the agent container |
| `--dns-servers <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 <url>` | string | auto-detected | Upstream (corporate) proxy URL for Squid to chain through |
| `--proxy-logs-dir <path>` | string | — | Directory to save Squid proxy logs to |
| `--audit-dir <path>` | string | — | Directory for firewall audit artifacts |
| `--session-state-dir <path>` | 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 <ports>` | string | `80,443` | Ports to allow when using --enable-host-access |
| `--allow-host-service-ports <ports>` | string | — | Ports to allow ONLY to host gateway (for GitHub Actions `services:`) |
Expand All @@ -58,15 +62,34 @@ awf [options] -- <command>
| `--openai-api-base-path <path>` | string | — | Base path prefix for OpenAI API requests |
| `--anthropic-api-target <host>` | string | `api.anthropic.com` | Target hostname for Anthropic API requests |
| `--anthropic-api-base-path <path>` | string | — | Base path prefix for Anthropic API requests |
| `--gemini-api-target <host>` | string | `generativelanguage.googleapis.com` | Target hostname for Gemini API requests |
| `--gemini-api-base-path <path>` | string | — | Base path prefix for Gemini API requests |
| `--rate-limit-rpm <n>` | number | `600` | Max requests per minute per provider |
| `--rate-limit-rph <n>` | number | `10000` | Max requests per hour per provider |
| `--rate-limit-bytes-pm <n>` | number | `52428800` (~50 MB) | Max request bytes per minute per provider |
| `--no-rate-limit` | flag | — | Disable rate limiting in API proxy |
| `--difc-proxy-host <host:port>` | string | — | Connect to external DIFC proxy and enable CLI proxy sidecar |
| `--difc-proxy-ca-cert <path>` | 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 <path>`

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 <domains>`

Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns, protocol-specific filtering, and special keywords.
Expand Down Expand Up @@ -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 <socket>`

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 <KEY=VALUE>`

Pass environment variable to container. Can be specified multiple times.
Expand Down Expand Up @@ -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 <url>`

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).
Expand Down Expand Up @@ -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 <path>`

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 <value>`

Specify the agent container image to use. Supports pre-built presets or custom base images.
Expand Down Expand Up @@ -777,6 +834,35 @@ sudo -E awf --enable-api-proxy \
-- command
```

### `--gemini-api-target <host>`

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 <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 <n>`

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.
Expand Down Expand Up @@ -831,6 +917,33 @@ sudo -E awf --enable-api-proxy --no-rate-limit \
-- command
```

### `--difc-proxy-host <host:port>`

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>`

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 `<workDir>/diagnostics/` (or `<audit-dir>/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.
:::
Expand Down Expand Up @@ -963,6 +1076,7 @@ awf predownload [options]
| `--image-tag <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 <value>` | 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.
Expand All @@ -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

Expand Down
74 changes: 56 additions & 18 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
sudo awf [options] -- <command>

Options:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
-d, --allow-domains <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
Expand Down Expand Up @@ -43,31 +44,44 @@ Options:
default → agent:<tag>
act → agent-act:<tag>
--skip-pull Use local images without pulling from registry (requires images to be
pre-downloaded) (default: false)
pre-downloaded) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from
DOCKER_HOST env). Example: unix:///run/user/1000/docker.sock
-e, --env <KEY=VALUE> 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 <path:path> Volume mount (can be specified multiple times). Format:
host_path:container_path[:ro|rw]
like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough
(can be specified multiple times)
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:ro|rw]> Volume mount (can be specified multiple times). Format:
host_path:container_path[:ro|rw]
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE
for path consistency)
--dns-servers <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 <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to
this directory)
this directory)
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest,
iptables state)
--session-state-dir <path> 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 <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 <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 <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.
Expand All @@ -76,29 +90,46 @@ Options:
--copilot-api-target <host> Target hostname for Copilot API requests
(default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests
--anthropic-api-target <host> Target hostname for Anthropic API requests
(default: api.anthropic.com)
(default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests
--gemini-api-target <host> Target hostname for Gemini API requests
(default: generativelanguage.googleapis.com)
--gemini-api-base-path <path> Base path prefix for Gemini API requests
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> 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 <host:port> 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> Path to TLS CA cert written by external DIFC proxy
--ruleset-file <path> 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 <limit> Memory limit for the agent container (default: 2g)
Examples: 1g, 4g, 512m
--memory-limit <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 <workDir>/diagnostics/ (or <audit-dir>/diagnostics/)
-V, --version Output the version number
-h, --help Display help for command

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 <registry> Container image registry (default: ghcr.io/github/gh-aw-firewall)
--image-tag <tag> Container image tag (default: latest)
--agent-image <value> 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 <format> Output format: raw, pretty (colorized), json
Expand All @@ -113,6 +144,13 @@ Commands:
logs summary [options] Generate summary report (markdown by default)
--format <format> Output format: json, markdown, pretty
--source <path> Path to log directory or "running" for live container

logs audit [options] Show firewall audit with policy rule matching
--format <format> Output format: json, markdown, pretty
--source <path> Path to log directory or "running" for live container
--rule <id> Filter to specific rule ID
--domain <domain> Filter to specific domain
--decision <decision> Filter to "allowed" or "denied"
```

## Basic Examples
Expand Down
Loading