Merge pull request #32 from stranma/feat/webfetch-firewall-integration

feat: auto-whitelist WebFetch domains in devcontainer firewall

Author: stranma

.devcontainer/init-firewall.sh

@@ -3,7 +3,8 @@ set -euo pipefail
 IFS=$'\n\t'
 
 # Network security firewall for devcontainer.
-# Restricts egress to: PyPI, GitHub, Anthropic/Claude, VS Code, uv/Astral.
+# Restricts egress to: PyPI, GitHub, Anthropic/Claude, VS Code, uv/Astral,
+# plus any domains from WebFetch(domain:...) permission patterns.
 # Uses ipset with aggregated CIDR ranges for reliable filtering.
 
 echo "iptables version: $(iptables --version)"
@@ -109,6 +110,50 @@ for domain in \
     done < <(echo "$ips")
 done
 
+# --- Extract domains from WebFetch permission settings ---
+extract_webfetch_domains() {
+    local file="$1"
+    [ -f "$file" ] || return 0
+    jq -r '
+        [(.permissions.allow // []), (.permissions.ask // [])] | add
+        | .[]
+        | select(startswith("WebFetch(domain:"))
+        | sub("^WebFetch\\(domain:"; "") | sub("\\)$"; "")
+    ' "$file" 2>/dev/null || true
+}
+
+SETTINGS_DIR="/workspace/.claude"
+WEBFETCH_DOMAINS=""
+for settings_file in "$SETTINGS_DIR/settings.json" "$SETTINGS_DIR/settings.local.json"; do
+    if [ -f "$settings_file" ]; then
+        echo "Scanning $settings_file for WebFetch domains..."
+        WEBFETCH_DOMAINS="$WEBFETCH_DOMAINS $(extract_webfetch_domains "$settings_file")"
+    fi
+done
+
+UNIQUE_DOMAINS=$(printf '%s\n' "$WEBFETCH_DOMAINS" | tr ' ' '\n' | sed '/^$/d' | sort -u)
+if [ -n "$UNIQUE_DOMAINS" ]; then
+    while read -r domain; do
+        if [[ "$domain" == \** ]]; then
+            echo "WARNING: Wildcard domain '$domain' cannot be resolved to IPs (skipping)"
+            continue
+        fi
+        echo "Resolving WebFetch domain: $domain..."
+        ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+        if [ -z "$ips" ]; then
+            echo "WARNING: Failed to resolve $domain (skipping)"
+            continue
+        fi
+        while read -r ip; do
+            if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+                echo "WARNING: Invalid IP from DNS for $domain: $ip (skipping)"
+                continue
+            fi
+            ipset add allowed-domains "$ip" 2>/dev/null || true
+        done < <(echo "$ips")
+    done <<< "$UNIQUE_DOMAINS"
+fi
+
 # --- Host network detection ---
 HOST_IP=$(ip route | grep default | cut -d" " -f3)
 if [ -z "$HOST_IP" ]; then

docs/DECISIONS.md

@@ -190,3 +190,15 @@ When a decision is superseded or obsolete, delete it (git history preserves the
 - Deny `git remote add`, `set-url`, `remove`, `rename`, `set-head` in settings.json and all tier files -- read-only `git remote -v` remains allowed via the existing `Bash(git remote *)` allow rule
 - Deny rules are absolute in Claude Code (cannot be overridden by allow), making this the correct control layer vs hooks
 - Tier files use wildcard prefix `Bash(*git remote add *)` to catch chained command variants
+
+## 2026-03-16: WebFetch Firewall Integration
+
+**Request**: Connect the devcontainer iptables firewall to Claude Code's WebFetch permission settings so users don't need to manually edit the firewall script when working with external services.
+
+**Decisions**:
+- Firewall reads `WebFetch(domain:...)` patterns from settings.json and settings.local.json at container startup -- single source of truth for domain whitelisting
+- Only `allow` and `ask` lists are scanned (not `deny`) -- denied domains should never be whitelisted
+- Bare `WebFetch` (no domain qualifier) is ignored -- it grants tool permission but has no domain to resolve
+- Wildcard domains (e.g., `*.example.com`) are skipped with a warning -- DNS cannot resolve wildcard patterns to IPs
+- Empty domain values filtered by `sed '/^$/d'` instead of `grep -v '^$'` -- grep exits non-zero on empty input under `set -euo pipefail`
+- WebFetch settings changes take effect on container restart (`init-firewall.sh` runs from `postStartCommand`); permission tier changes require rebuild (`onCreateCommand` copies tier to `settings.local.json`)

docs/DEVCONTAINER_PERMISSIONS.md

@@ -16,7 +16,7 @@ Set the tier via `PERMISSION_TIER` environment variable before building the devc
 
 Regardless of tier, these layers provide defense-in-depth:
 
-- **Firewall (iptables)**: All egress blocked except ~10 whitelisted domains
+- **Firewall (iptables)**: All egress blocked except whitelisted domains (built-in + WebFetch settings)
 - **Non-root user**: Cannot install system packages or modify system files
 - **dangerous-actions-blocker.sh**: Blocks rm -rf, sudo, force push, DROP DATABASE, secrets in args
 - **output-secrets-scanner.sh**: Warns on leaked credentials in command output
@@ -47,6 +47,23 @@ Regardless of tier, these layers provide defense-in-depth:
 | `cd path && command` | Use absolute paths: `command /absolute/path` | Chained commands bypass glob-based permission checks |
 | `git remote add/set-url/remove/rename/set-head` | Ask the user to manage remotes | Prevents code exfiltration to unauthorized remotes |
 
+## Firewall Configuration
+
+The devcontainer firewall (`init-firewall.sh`) restricts all outbound traffic to a built-in allowlist plus domains from Claude Code permission settings.
+
+**Built-in domains** (always allowed): PyPI, GitHub (via API CIDR ranges), Anthropic/Claude, VS Code Marketplace, uv/Astral, plus telemetry endpoints (`sentry.io`, `statsig.anthropic.com`, `statsig.com`).
+
+**WebFetch domain auto-whitelisting**: The firewall scans `.claude/settings.json` and `.claude/settings.local.json` for `WebFetch(domain:...)` patterns in `allow` and `ask` lists. Matched domains are resolved via DNS and added to the ipset allowlist.
+
+| Pattern | Firewall behavior |
+|---------|-------------------|
+| `WebFetch(domain:algoenergy.cz)` | Resolved and whitelisted |
+| `WebFetch(domain:*.example.com)` | Skipped (wildcards cannot be resolved) |
+| `WebFetch` (bare) | Ignored (no domain to resolve) |
+| `WebFetch(domain:)` (empty) | Filtered out |
+
+Changes to WebFetch settings in `.claude/settings.json` or `.claude/settings.local.json` take effect on container restart. Changes to `.devcontainer/permissions/*.json` require a full rebuild (`devcontainer rebuild`).
+
 ## Tier Comparison
 
 | Capability | Tier 1 | Tier 2 | Tier 3 |