docs: add missing security and network flags to CLI reference

[Copilot]

The CLI reference page was missing four flags: --dns-over-https, --allow-host-service-ports, --enable-dind, and --enable-dlp.

Changes

• Options Summary table: Added all four flags with types, defaults, and descriptions
• Options Details sections:
  • --dns-over-https [resolver-url] — DoH via sidecar proxy, default Google resolver, https:// requirement
  • --allow-host-service-ports <ports> — Host gateway-only port access for Actions services: containers; includes comparison table vs --allow-host-ports covering scope, dangerous port handling, and auto-enable behavior
  • --enable-dind — Docker socket mount with danger admonition re: firewall bypass
  • --enable-dlp — Credential exfiltration scanning for outbound URLs

[Copilot]

Pull request overview

Updates the AWF CLI reference documentation to include four previously undocumented network/security flags, helping users correctly configure DNS privacy, GitHub Actions service access, Docker socket exposure, and outbound credential scanning.

Changes:

• Added --dns-over-https, --allow-host-service-ports, --enable-dind, and --enable-dlp to the Options Summary table (types/defaults/descriptions).
• Added detailed reference sections for each new flag, including usage examples and security notes.
• Added a comparison table clarifying the intent and scope differences between --allow-host-ports and --allow-host-service-ports.

Comments suppressed due to low confidence (6)

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

• The DoH description implies DNS is fully “sent over HTTPS instead of plaintext UDP”. In implementation, the agent still sends plaintext DNS (UDP/TCP 53) to the local DoH sidecar, and only the sidecar forwards queries over HTTPS to the upstream resolver. Consider rephrasing to reflect the two-hop flow and avoid implying the agent itself speaks DoH.

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.

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

• It’s worth calling out that enabling --dns-over-https introduces a DoH proxy sidecar that has direct outbound HTTPS access to the resolver (bypassing Squid/domain allowlisting). Users may incorrectly assume they need to include the resolver domain in --allow-domains, or may not realize this is an allowlist bypass for that one dependency. Suggest adding a short note about this behavior and recommending only trusted resolver URLs.

- **Default resolver**: `https://dns.google/dns-query`
- **Requirement**: Resolver URL must start with `https://`

:::tip
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.
:::

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

• --allow-host-service-ports only accepts comma-separated numeric ports (no ranges like 3000-3010). The docs currently don’t mention this, while --allow-host-ports explicitly documents range support. Consider adding a brief input-format note here to prevent confusing validation errors.

### `--allow-host-service-ports <ports>`

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.

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

• Docs say --allow-host-service-ports “auto-enables host access”, but don’t mention the side effect that host access also opens ports 80/443 to the host gateway by default. This can be a meaningful security/behavior change for users who expect only the listed service ports to be opened. Suggest explicitly noting the implicit 80/443 allowance when host access is auto-enabled.

| **Scope** | General host access | Host gateway only |
| **Dangerous ports** | Blocked (SSH, SMTP, etc.) | Allowed (restricted to host) |
| **Requires `--enable-host-access`** | Yes | No (auto-enables it) |
| **Use case** | Local dev servers | GitHub Actions `services:` |

- **Auto-enables host access**: No need to also pass `--enable-host-access`
- **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

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

• The text claims dangerous DB ports “are safe with --allow-host-service-ports”. The implementation itself warns to ensure services on these ports do not provide external network access, so “safe” is stronger than what the tool can guarantee. Consider softening this phrasing (e.g., “lower risk than --allow-host-ports because it’s restricted to the host gateway”) and/or echoing the same caution.

- **Auto-enables host access**: No need to also pass `--enable-host-access`
- **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

:::danger[Security Warning]
Allowing port 22 grants SSH access to the host machine. Only allow ports for services you explicitly need.
:::

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

• The --enable-dlp section reads like it scans full outbound URLs for credentials in general. For HTTPS without --ssl-bump, Squid typically only sees the CONNECT authority (host:port), not path/query, so DLP won’t catch tokens embedded in HTTPS URL paths/queries unless SSL Bump is enabled. Consider adding a short note clarifying this limitation and recommending --ssl-bump for full HTTPS URL inspection (with appropriate security warning).

### `--enable-dlp`

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.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Options Summary “Default” value for --dns-over-https reads like the feature is enabled by default. In the CLI, DoH is disabled unless the flag is provided; the Google URL is only the default resolver when the flag is set without an argument. Consider changing the Default column to something like “— (when enabled: https://dns.google/dns-query)” to avoid confusion.

This issue also appears in the following locations of the same file:

• line 283
• line 293
• line 340
• line 355
• line 360
• ...and 1 more

Suggested change

	| `--dns-over-https [resolver-url]` | optional string | `https://dns.google/dns-query` | Enable DNS-over-HTTPS via sidecar proxy |
	| `--dns-over-https [resolver-url]` | optional string | — (when enabled: `https://dns.google/dns-query`) | Enable DNS-over-HTTPS via sidecar proxy |

[github-actions]

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit a9414c5