diff --git a/docs-site/src/content/docs/reference/cli-reference.md b/docs-site/src/content/docs/reference/cli-reference.md index a6893bac..bb346c9e 100644 --- a/docs-site/src/content/docs/reference/cli-reference.md +++ b/docs-site/src/content/docs/reference/cli-reference.md @@ -21,12 +21,14 @@ awf [options] -- |--------|------|---------|-------------| | `--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) | | `--block-domains ` | string | — | Comma-separated list of blocked domains (takes precedence over allowed) | | `--block-domains-file ` | string | — | Path to file containing blocked domains | | `--ssl-bump` | flag | `false` | Enable SSL Bump for HTTPS content inspection | | `--allow-urls ` | string | — | Comma-separated list of allowed URL patterns (requires `--ssl-bump`) | | `--log-level ` | string | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` | | `--keep-containers` | flag | `false` | Keep containers running after command exits | +| `--agent-timeout ` | number | no limit | Maximum time in minutes for the agent command to run | | `--tty` | flag | `false` | Allocate pseudo-TTY for interactive tools | | `--work-dir ` | string | `/tmp/awf-` | Working directory for temporary files | | `--build-local` | flag | `false` | Build containers locally instead of pulling from registry | @@ -36,11 +38,14 @@ awf [options] -- | `-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) | +| `--env-file ` | string | — | Read env vars from a file (KEY=VALUE format, one per line) | | `-v, --mount ` | string | `[]` | Volume mount (repeatable) | | `--container-workdir ` | string | User home | Working directory inside container | +| `--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 | | `--proxy-logs-dir ` | string | — | Directory to save Squid proxy logs to | +| `--audit-dir ` | string | — | Directory for firewall audit artifacts | | `--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:`) | @@ -96,6 +101,40 @@ Path to file with allowed domains. Supports comments (`#`) and one domain per li --allow-domains-file ./allowed-domains.txt ``` +### `--ruleset-file ` + +YAML rule file for domain allowlisting. Can be specified multiple times to load multiple files. Domains from ruleset files are merged with `--allow-domains` and `--allow-domains-file`. + +```bash +# Single ruleset file +--ruleset-file ./domains.yml + +# Multiple ruleset files +--ruleset-file ./base-domains.yml --ruleset-file ./extra-domains.yml +``` + +**Schema** (version 1): + +```yaml +version: 1 +rules: + - domain: github.com + subdomains: true # default: true — also allows *.github.com + - domain: example.com + subdomains: false # exact match only +``` + +**Fields:** +- `version` — Must be `1` +- `rules` — Array of rule objects + +Each rule has the following fields: + +| Field | Required | Default | Description | +|-------|----------|---------|-------------| +| `domain` | Yes | — | Domain name to allow | +| `subdomains` | No | `true` | Whether to also allow all subdomains | + ### `--block-domains ` Comma-separated list of blocked domains. **Blocked domains take precedence over allowed domains**, enabling fine-grained control. Supports the same wildcard patterns as `--allow-domains`. @@ -176,6 +215,24 @@ Keep containers and configuration files after command exits for debugging. Requires manual cleanup: `docker stop awf-squid awf-agent && docker network rm awf-net` ::: +### `--agent-timeout ` + +Maximum time in minutes for the agent command to run. When the timeout is reached, the agent container is stopped and the firewall exits. Must be a positive integer. + +```bash +# Allow up to 30 minutes +sudo awf --agent-timeout 30 --allow-domains github.com \ + -- long-running-command + +# Allow up to 2 hours +sudo awf --agent-timeout 120 --allow-domains github.com \ + -- npx @github/copilot@latest --prompt "complex task" +``` + +:::note +By default, there is no time limit. Use this flag to prevent runaway agent processes. +::: + ### `--tty` Allocate a pseudo-TTY for interactive tools (e.g., Claude Code, interactive shells). @@ -234,9 +291,47 @@ Pass environment variable to container. Can be specified multiple times. Pass all host environment variables to container. :::danger[Security Risk] -May expose sensitive credentials. Prefer `-e` for specific variables. +May expose sensitive credentials. Prefer `-e` for specific variables, or use `--exclude-env` to filter out sensitive variables. ::: +### `--exclude-env ` + +Exclude a specific environment variable from `--env-all` passthrough. Can be specified multiple times. Only meaningful when used with `--env-all`. + +```bash +# Pass all env vars except secrets +sudo -E awf --env-all \ + --exclude-env AWS_SECRET_ACCESS_KEY \ + --exclude-env GITHUB_TOKEN \ + --allow-domains github.com \ + -- my-command +``` + +:::tip[Security Best Practice] +When using `--env-all`, always exclude sensitive variables like API keys, tokens, and credentials with `--exclude-env`. +::: + +### `--env-file ` + +Read environment variables from a file. The file uses `KEY=VALUE` format with one variable per line. Lines starting with `#` are treated as comments. + +```bash +sudo awf --env-file ./env.production \ + --allow-domains github.com \ + -- my-command +``` + +**File format:** +```bash +# Database configuration +DB_HOST=localhost +DB_PORT=5432 + +# API settings +API_KEY=your-api-key-here +DEBUG=true +``` + ### `-v, --mount ` Mount host directories into container. Format: `host_path:container_path[:ro|rw]` @@ -260,6 +355,26 @@ Mount host directories into container. Format: `host_path:container_path[:ro|rw] Working directory inside the container. +### `--memory-limit ` + +Memory limit for the agent container. Format: `` where unit is `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). + +- **Default**: `6g` + +```bash +# Increase memory for large language model agents +sudo awf --memory-limit 8g --allow-domains github.com \ + -- memory-intensive-command + +# Reduce memory for lightweight tasks +sudo awf --memory-limit 2g --allow-domains github.com \ + -- curl https://api.github.com +``` + +:::tip +If your agent process is being killed unexpectedly (OOM), try increasing the memory limit with `--memory-limit 8g` or higher. +::: + ### `--dns-servers ` Comma-separated list of trusted DNS servers. DNS traffic is **only** allowed to these servers, preventing DNS-based data exfiltration. Both IPv4 and IPv6 addresses are supported. @@ -380,6 +495,24 @@ cat ./firewall-logs/access.log **Note:** The directory must be writable by the current user. +### `--audit-dir ` + +Directory for firewall audit artifacts. When specified, the firewall saves configuration files, the policy manifest, and iptables state to this directory for compliance and debugging purposes. + +```bash +# Save audit artifacts +sudo awf --audit-dir ./audit \ + --allow-domains github.com \ + -- curl https://api.github.com + +# Review audit artifacts +ls ./audit/ +``` + +:::tip +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. +::: + ### `--agent-image ` Specify the agent container image to use. Supports pre-built presets or custom base images.