From fd00b51c3f298c163361b24d2399a16298ceb2d6 Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Wed, 18 Mar 2026 06:42:12 +0000 Subject: [PATCH] docs: fix proxy env vars and add missing CLI flags to usage - docs/environment.md: Remove incorrect claim that HTTP_PROXY/HTTPS_PROXY are no longer set (they ARE set to Squid's address). Clarify that only lowercase http_proxy is intentionally not set (httpoxy mitigation). - docs/environment.md: Add HTTP_PROXY, HTTPS_PROXY, https_proxy, SQUID_PROXY_HOST, SQUID_PROXY_PORT to internal env vars table. - docs/environment.md: Fix --env-all excluded variables list to match actual EXCLUDED_ENV_VARS in code (PATH, PWD, OLDPWD, SHLVL, _, SUDO_*). - docs/environment.md: Remove incorrect historical note claiming proxy vars were removed in v0.13.5. - docs/usage.md: Add missing CLI flags: --ruleset-file, --dns-over-https, --memory-limit, --enable-dind, --enable-dlp, --copilot-api-target, --openai-api-target, --anthropic-api-target, --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm, --no-rate-limit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/environment.md | 13 ++++++++----- docs/usage.md | 19 +++++++++++++++++++ 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/environment.md b/docs/environment.md index cd449e369..72ce35975 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -21,7 +21,7 @@ The following are always set/overridden: `PATH` (container values). Variables from `--env` flags override everything else. -**Note:** As of v0.13.5, `HTTP_PROXY` and `HTTPS_PROXY` are no longer automatically set. Traffic is transparently redirected to Squid via iptables NAT rules. If needed, you can still set these manually with `--env HTTP_PROXY=...` +**Proxy variables set automatically:** `HTTP_PROXY`, `HTTPS_PROXY`, and `https_proxy` are always set to point to the Squid proxy (`http://172.30.0.10:3128`). Note that lowercase `http_proxy` is intentionally **not** set — some curl builds on Ubuntu 22.04 ignore uppercase `HTTP_PROXY` for HTTP URLs (httpoxy mitigation), so HTTP traffic falls through to iptables DNAT interception instead. iptables DNAT serves as a defense-in-depth fallback for both HTTP and HTTPS. ## Security Warning: `--env-all` @@ -32,9 +32,9 @@ Using `--env-all` passes all host environment variables to the container, which 3. **Unnecessary Access**: Extra variables increase attack surface (violates least privilege) 4. **Accidental Sharing**: Easy to forget what's in your environment when sharing commands -**Excluded variables** (even with `--env-all`): `PATH`, `PWD`, `OLDPWD`, `SHLVL`, `_`, `SUDO_*`, `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy`, `https_proxy`, `NO_PROXY`, `no_proxy` +**Excluded variables** (even with `--env-all`): `PATH`, `PWD`, `OLDPWD`, `SHLVL`, `_`, `SUDO_*` -**Proxy variables:** Host proxy settings are excluded to prevent conflicts with iptables-based traffic redirection. The firewall uses transparent proxying via iptables NAT rules instead of environment variable-based proxy configuration. +**Proxy variables:** `HTTP_PROXY`, `HTTPS_PROXY`, `https_proxy` (and their lowercase/uppercase variants) from the host are ignored when using `--env-all` because the firewall always sets these to point to Squid. Host proxy settings cannot be passed through as they would conflict with the firewall's traffic routing. ## Best Practices @@ -61,6 +61,11 @@ The following environment variables are set internally by the firewall and used | Variable | Description | Example | |----------|-------------|---------| +| `HTTP_PROXY` | Squid forward proxy for HTTP traffic | `http://172.30.0.10:3128` | +| `HTTPS_PROXY` | Squid forward proxy for HTTPS traffic (explicit CONNECT) | `http://172.30.0.10:3128` | +| `https_proxy` | Lowercase alias for tools that only check lowercase (e.g., Yarn 4, undici) | `http://172.30.0.10:3128` | +| `SQUID_PROXY_HOST` | Squid proxy hostname (for tools needing host separately) | `squid-proxy` | +| `SQUID_PROXY_PORT` | Squid proxy port | `3128` | | `AWF_DNS_SERVERS` | Comma-separated list of trusted DNS servers | `8.8.8.8,8.8.4.4` | | `AWF_CHROOT_ENABLED` | Whether chroot mode is enabled | `true` | | `AWF_HOST_PATH` | Host PATH passed to chroot environment | `/usr/local/bin:/usr/bin` | @@ -95,8 +100,6 @@ When enabled, the library logs: **Note:** Debug output goes to stderr and does not interfere with command stdout. See `containers/agent/one-shot-token/README.md` for complete documentation. -**Historical note:** Prior to v0.13.5, `HTTP_PROXY` and `HTTPS_PROXY` were set to point to Squid. These have been removed in favor of transparent iptables-based redirection, which is more reliable and avoids conflicts with tools that don't honor proxy environment variables. - ## Troubleshooting **Variable not accessible:** Use `sudo -E` or pass explicitly with `--env VAR="$VAR"` diff --git a/docs/usage.md b/docs/usage.md index c3c600b9c..278bdb62a 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -67,6 +67,25 @@ Options: --enable-api-proxy Enable API proxy sidecar for holding authentication credentials. Deploys a Node.js proxy that injects API keys securely. Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false) + --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) + --anthropic-api-target Target hostname for Anthropic API requests + (default: api.anthropic.com) + --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) + --ruleset-file YAML rule file for domain allowlisting (repeatable). + 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 + --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) -V, --version Output the version number -h, --help Display help for command