feat: add --enable-host-access flag and fix CONNECT to port 80 (#190)

This PR addresses issue #189 by:

1. Making host.docker.internal opt-in via --enable-host-access flag
   - By default, containers cannot resolve host.docker.internal
   - When enabled, adds extra_hosts to both Squid and agent containers
   - Shows security warning when combined with host.docker.internal domain

2. Allowing CONNECT method to Safe_ports (80 and 443)
   - Changes `http_access deny CONNECT !SSL_ports` to `!Safe_ports`
   - Required because Node.js fetch uses CONNECT for HTTP through proxy
   - Domain ACLs remain the primary security control

Security considerations:
- Host access is opt-in to prevent accidental exposure of host services
- Warning displayed when host.docker.internal is in allowed domains
- Safe_ports change has minimal security impact as domain filtering is primary control

Closes #189

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: Mossaka

docs/usage.md

@@ -8,9 +8,19 @@ sudo awf [options] <command>
 Options:
   --allow-domains <domains>  Comma-separated list of allowed domains (required)
                              Example: github.com,api.github.com,arxiv.org
+  --allow-domains-file <path>  Path to file containing allowed domains
+  --block-domains <domains>  Comma-separated list of blocked domains
+  --block-domains-file <path>  Path to file containing blocked domains
+  --enable-host-access       Enable access to host services via host.docker.internal
+                             (see "Host Access" section for security implications)
   --log-level <level>        Log level: debug, info, warn, error (default: info)
   --keep-containers          Keep containers running after command exits
   --work-dir <dir>           Working directory for temporary files
+  --dns-servers <servers>    Comma-separated list of DNS servers (default: 8.8.8.8,8.8.4.4)
+  -e, --env <KEY=VALUE>      Additional environment variables (can repeat)
+  --env-all                  Pass all host environment variables to container
+  -v, --mount <path:path>    Volume mount (host_path:container_path[:ro|rw])
+  --tty                      Allocate a pseudo-TTY for interactive tools
   -V, --version              Output the version number
   -h, --help                 Display help for command
 
@@ -254,6 +264,48 @@ sudo awf \
 - Block known bad domains while allowing a curated list
 - Prevent access to internal services from AI agents
 
+## Host Access (MCP Gateways)
+
+When running MCP gateways or other services on your host machine that need to be accessible from inside the firewall, use the `--enable-host-access` flag.
+
+### Enabling Host Access
+
+```bash
+# Enable access to services running on the host via host.docker.internal
+sudo awf \
+  --enable-host-access \
+  --allow-domains host.docker.internal \
+  -- curl http://host.docker.internal:8080
+```
+
+### Security Considerations
+
+> ⚠️ **Security Warning**: When `--enable-host-access` is combined with `host.docker.internal` in `--allow-domains`, containers can access **ANY service** running on the host machine, including:
+> - Local databases (PostgreSQL, MySQL, Redis)
+> - Development servers
+> - Other sensitive services
+>
+> Only enable this for trusted workloads like MCP gateways.
+
+**Why opt-in?** By default, `host.docker.internal` hostname resolution is disabled to prevent containers from accessing host services. This is a defense-in-depth measure against malicious code attempting to access local resources.
+
+### Example: MCP Gateway on Host
+
+```bash
+# Start your MCP gateway on the host (port 8080)
+./my-mcp-gateway --port 8080 &
+
+# Run awf with host access enabled
+sudo awf \
+  --enable-host-access \
+  --allow-domains host.docker.internal,api.github.com \
+  -- 'copilot --mcp-gateway http://host.docker.internal:8080 --prompt "test"'
+```
+
+### CONNECT Method on Port 80
+
+The firewall allows the HTTP CONNECT method on both ports 80 and 443. This is required because some HTTP clients (e.g., Node.js fetch) use the CONNECT method even for HTTP connections when going through a proxy. Domain ACLs remain the primary security control.
+
 ## Limitations
 
 ### No Internationalized Domains

src/cli.ts

@@ -384,6 +384,13 @@ program
     '--proxy-logs-dir <path>',
     'Directory to save Squid proxy logs to (writes access.log directly to this directory)'
   )
+  .option(
+    '--enable-host-access',
+    'Enable access to host services via host.docker.internal. ' +
+    'Security warning: When combined with --allow-domains host.docker.internal, ' +
+    'containers can access ANY service on the host machine.',
+    false
+  )
   .argument('[args...]', 'Command and arguments to execute (use -- to separate from options)')
   .action(async (args: string[], options) => {
     // Require -- separator for passing command arguments
@@ -549,6 +556,7 @@ program
       containerWorkDir: options.containerWorkdir,
       dnsServers,
       proxyLogsDir: options.proxyLogsDir,
+      enableHostAccess: options.enableHostAccess,
     };
 
     // Warn if --env-all is used
@@ -557,6 +565,18 @@ program
       logger.warn('   This may expose sensitive credentials if logs or configs are shared');
     }
 
+    // Warn if --enable-host-access is used with host.docker.internal in allowed domains
+    if (config.enableHostAccess) {
+      const hasHostDomain = allowedDomains.some(d =>
+        d === 'host.docker.internal' || d.endsWith('.host.docker.internal')
+      );
+      if (hasHostDomain) {
+        logger.warn('⚠️  Host access enabled with host.docker.internal in allowed domains');
+        logger.warn('   Containers can access ANY service running on the host machine');
+        logger.warn('   Only use this for trusted workloads (e.g., MCP gateways)');
+      }
+    }
+
     // Log config with redacted secrets
     const redactedConfig = {
       ...config,

src/docker-manager.test.ts

@@ -317,11 +317,44 @@ describe('docker-manager', () => {
       expect(agent.dns_search).toEqual([]);
     });
 
-    it('should configure extra_hosts for host.docker.internal', () => {
+    it('should NOT configure extra_hosts by default (opt-in for security)', () => {
       const result = generateDockerCompose(mockConfig, mockNetworkConfig);
       const agent = result.services.agent;
+      const squid = result.services['squid-proxy'];
+
+      expect(agent.extra_hosts).toBeUndefined();
+      expect(squid.extra_hosts).toBeUndefined();
+    });
+
+    describe('enableHostAccess option', () => {
+      it('should configure extra_hosts when enableHostAccess is true', () => {
+        const config = { ...mockConfig, enableHostAccess: true };
+        const result = generateDockerCompose(config, mockNetworkConfig);
+        const agent = result.services.agent;
+        const squid = result.services['squid-proxy'];
+
+        expect(agent.extra_hosts).toEqual(['host.docker.internal:host-gateway']);
+        expect(squid.extra_hosts).toEqual(['host.docker.internal:host-gateway']);
+      });
+
+      it('should NOT configure extra_hosts when enableHostAccess is false', () => {
+        const config = { ...mockConfig, enableHostAccess: false };
+        const result = generateDockerCompose(config, mockNetworkConfig);
+        const agent = result.services.agent;
+        const squid = result.services['squid-proxy'];
+
+        expect(agent.extra_hosts).toBeUndefined();
+        expect(squid.extra_hosts).toBeUndefined();
+      });
 
-      expect(agent.extra_hosts).toEqual(['host.docker.internal:host-gateway']);
+      it('should NOT configure extra_hosts when enableHostAccess is undefined', () => {
+        const result = generateDockerCompose(mockConfig, mockNetworkConfig);
+        const agent = result.services.agent;
+        const squid = result.services['squid-proxy'];
+
+        expect(agent.extra_hosts).toBeUndefined();
+        expect(squid.extra_hosts).toBeUndefined();
+      });
     });
 
     it('should override environment variables with additionalEnv', () => {

src/docker-manager.ts

@@ -186,6 +186,15 @@ export function generateDockerCompose(
     ports: [`${SQUID_PORT}:${SQUID_PORT}`],
   };
 
+  // Only enable host.docker.internal when explicitly requested via --enable-host-access
+  // This allows containers to reach services on the host machine (e.g., MCP gateways)
+  // Security note: When combined with allowing host.docker.internal domain,
+  // containers can access any port on the host
+  if (config.enableHostAccess) {
+    squidService.extra_hosts = ['host.docker.internal:host-gateway'];
+    logger.debug('Host access enabled: host.docker.internal will resolve to host gateway');
+  }
+
   // Use GHCR image or build locally
   if (useGHCR) {
     squidService.image = `${registry}/squid:${tag}`;
@@ -297,7 +306,6 @@ export function generateDockerCompose(
     },
     dns: dnsServers, // Use configured DNS servers (prevents DNS exfiltration)
     dns_search: [], // Disable DNS search domains to prevent embedded DNS fallback
-    extra_hosts: ['host.docker.internal:host-gateway'], // Enable host.docker.internal on Linux
     volumes: agentVolumes,
     environment,
     depends_on: {
@@ -337,6 +345,11 @@ export function generateDockerCompose(
     logger.debug(`Set container working directory to: ${config.containerWorkDir}`);
   }
 
+  // Enable host.docker.internal for agent when --enable-host-access is set
+  if (config.enableHostAccess) {
+    agentService.extra_hosts = ['host.docker.internal:host-gateway'];
+  }
+
   // Use GHCR image or build locally
   if (useGHCR) {
     agentService.image = `${registry}/agent:${tag}`;

src/squid-config.test.ts

@@ -332,6 +332,24 @@ describe('generateSquidConfig', () => {
       expect(result).toContain('logformat firewall_detailed');
     });
 
+    it('should allow CONNECT to Safe_ports (80 and 443) for HTTP proxy compatibility', () => {
+      // See: https://github.com/githubnext/gh-aw-firewall/issues/189
+      // Node.js fetch uses CONNECT method even for HTTP connections when proxied
+      const config: SquidConfig = {
+        domains: ['example.com'],
+        port: defaultPort,
+      };
+      const result = generateSquidConfig(config);
+
+      // Should deny CONNECT to non-Safe_ports (not just SSL_ports)
+      expect(result).toContain('http_access deny CONNECT !Safe_ports');
+      // Should NOT deny CONNECT to non-SSL_ports (would block port 80)
+      expect(result).not.toContain('http_access deny CONNECT !SSL_ports');
+      // Safe_ports should include both 80 and 443
+      expect(result).toContain('acl Safe_ports port 80');
+      expect(result).toContain('acl Safe_ports port 443');
+    });
+
     it('should deny access to domains not in the allowlist', () => {
       const config: SquidConfig = {
         domains: ['example.com'],

src/squid-config.ts

@@ -309,7 +309,11 @@ acl CONNECT method CONNECT
 # Access rules
 # Deny unsafe ports first
 http_access deny !Safe_ports
-http_access deny CONNECT !SSL_ports
+# Allow CONNECT to Safe_ports (80 and 443) instead of just SSL_ports (443)
+# This is required because some HTTP clients (e.g., Node.js fetch) use CONNECT
+# method even for HTTP connections when going through a proxy.
+# See: gh-aw-firewall issue #189
+http_access deny CONNECT !Safe_ports
 
 ${accessRulesSection}# Deny requests to unknown domains (not in allow-list)
 # This applies to all sources including localnet

src/types.ts

@@ -233,6 +233,27 @@ export interface WrapperConfig {
    * @example '/tmp/my-proxy-logs'
    */
   proxyLogsDir?: string;
+
+  /**
+   * Enable access to host services via host.docker.internal
+   *
+   * When true, adds `host.docker.internal` hostname resolution to containers,
+   * allowing traffic to reach services running on the host machine.
+   *
+   * **Security Warning**: When enabled and `host.docker.internal` is added to
+   * --allow-domains, containers can access ANY service running on the host,
+   * including databases, APIs, and other sensitive services. Only enable this
+   * when you specifically need container-to-host communication (e.g., for MCP
+   * gateways running on the host).
+   *
+   * @default false
+   * @example
+   * ```bash
+   * # Enable host access for MCP gateway on host
+   * awf --enable-host-access --allow-domains host.docker.internal -- curl http://host.docker.internal:8080
+   * ```
+   */
+  enableHostAccess?: boolean;
 }
 
 /**