Skip to content

Commit 7d5bd3d

Browse files
CopilotMossaka
andauthored
docs: add missing security and network flags to CLI reference
Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/3fc94665-b60c-4a10-a7e7-656c3a5d0b11 Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
1 parent 0abddf7 commit 7d5bd3d

File tree

1 file changed

+76
-0
lines changed

1 file changed

+76
-0
lines changed

docs-site/src/content/docs/reference/cli-reference.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,13 @@ awf [options] -- <command>
3939
| `-v, --mount <host:container[:mode]>` | string | `[]` | Volume mount (repeatable) |
4040
| `--container-workdir <dir>` | string | User home | Working directory inside container |
4141
| `--dns-servers <servers>` | string | `8.8.8.8,8.8.4.4` | Trusted DNS servers (comma-separated) |
42+
| `--dns-over-https [resolver-url]` | optional string | `https://dns.google/dns-query` | Enable DNS-over-HTTPS via sidecar proxy |
4243
| `--proxy-logs-dir <path>` | string || Directory to save Squid proxy logs to |
4344
| `--enable-host-access` | flag | `false` | Enable access to host services via host.docker.internal |
4445
| `--allow-host-ports <ports>` | string | `80,443` | Ports to allow when using --enable-host-access |
46+
| `--allow-host-service-ports <ports>` | string || Ports to allow ONLY to host gateway (for GitHub Actions `services:`) |
47+
| `--enable-dind` | flag | `false` | Enable Docker-in-Docker by exposing host Docker socket |
48+
| `--enable-dlp` | flag | `false` | Enable DLP scanning to block credential exfiltration |
4549
| `--agent-image <value>` | string | `default` | Agent container image (default, act, or custom) |
4650
| `-V, --version` | flag || Display version |
4751
| `-h, --help` | flag || Display help |
@@ -274,6 +278,25 @@ Docker's embedded DNS (127.0.0.11) is always allowed for container name resoluti
274278
AWF always runs in chroot mode, making the host filesystem appear as the root filesystem inside the container. This provides transparent access to host-installed binaries (Python, Node.js, Go, etc.) while maintaining network isolation. See [Chroot Mode Documentation](/gh-aw-firewall/docs/chroot-mode/) for details.
275279
:::
276280

281+
### `--dns-over-https [resolver-url]`
282+
283+
Enable DNS-over-HTTPS (DoH) via a sidecar proxy. When enabled, DNS queries are encrypted and sent over HTTPS instead of plaintext UDP, preventing DNS-based traffic inspection or tampering.
284+
285+
```bash
286+
# Use default resolver (Google DNS)
287+
--dns-over-https
288+
289+
# Use a custom resolver
290+
--dns-over-https https://cloudflare-dns.com/dns-query
291+
```
292+
293+
- **Default resolver**: `https://dns.google/dns-query`
294+
- **Requirement**: Resolver URL must start with `https://`
295+
296+
:::tip
297+
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.
298+
:::
299+
277300
### `--enable-host-access`
278301

279302
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).
@@ -314,6 +337,33 @@ sudo awf --allow-domains localhost --allow-host-ports 3000 \
314337
Always explicitly specify `--allow-host-ports` to ensure consistent behavior across versions.
315338
:::
316339

340+
### `--allow-host-service-ports <ports>`
341+
342+
Comma-separated ports to allow **only** to the host gateway (`host.docker.internal`). Designed for GitHub Actions `services:` containers (e.g., PostgreSQL, Redis) whose ports are exposed to the host gateway.
343+
344+
```bash
345+
# Allow PostgreSQL and Redis on host gateway
346+
sudo awf --allow-host-service-ports 5432,6379 \
347+
--allow-domains github.com \
348+
-- python run_tests.py
349+
```
350+
351+
**Key differences from `--allow-host-ports`:**
352+
353+
| | `--allow-host-ports` | `--allow-host-service-ports` |
354+
|---|---|---|
355+
| **Scope** | General host access | Host gateway only |
356+
| **Dangerous ports** | Blocked (SSH, SMTP, etc.) | Allowed (restricted to host) |
357+
| **Requires `--enable-host-access`** | Yes | No (auto-enables it) |
358+
| **Use case** | Local dev servers | GitHub Actions `services:` |
359+
360+
- **Auto-enables host access**: No need to also pass `--enable-host-access`
361+
- **Bypasses dangerous port restrictions**: Ports like 5432 (PostgreSQL) and 6379 (Redis) are normally blocked when using `--allow-host-ports` to prevent unintended database access, but are safe with `--allow-host-service-ports` because traffic is restricted to the host gateway only
362+
363+
:::danger[Security Warning]
364+
Allowing port 22 grants SSH access to the host machine. Only allow ports for services you explicitly need.
365+
:::
366+
317367
### `--proxy-logs-dir <path>`
318368

319369
Save Squid proxy logs directly to a custom directory instead of the default temporary location. Useful for preserving logs across multiple runs or integrating with log aggregation systems.
@@ -364,6 +414,32 @@ Custom images are validated against approved patterns to prevent supply chain at
364414

365415
**See also:** [Agent Images Reference](/gh-aw-firewall/reference/agent-images/)
366416

417+
### `--enable-dind`
418+
419+
Enable Docker-in-Docker by mounting the host Docker socket (`/var/run/docker.sock`) into the agent container. This allows the agent to run Docker commands.
420+
421+
```bash
422+
sudo awf --enable-dind --allow-domains github.com \
423+
-- docker run hello-world
424+
```
425+
426+
:::danger[Security Warning]
427+
Enabling Docker-in-Docker allows the agent to **bypass all firewall restrictions** by spawning new containers that are not subject to the firewall's network rules. Only enable this when you trust the command being executed and Docker access is required.
428+
:::
429+
430+
### `--enable-dlp`
431+
432+
Enable Data Loss Prevention (DLP) scanning on outbound requests. When enabled, the firewall inspects outbound request URLs for patterns that match common credentials (API keys, tokens, passwords) and blocks requests that appear to exfiltrate secrets.
433+
434+
```bash
435+
sudo awf --enable-dlp --allow-domains github.com \
436+
-- python my_script.py
437+
```
438+
439+
:::tip
440+
Enable DLP scanning as a defense-in-depth measure when running untrusted code that has access to environment variables or files containing credentials.
441+
:::
442+
367443

368444
## Exit Codes
369445

0 commit comments

Comments
 (0)