From f3403bf0f84adb2e3550d40c14ee41f9fb482ddc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 21:02:48 +0000
Subject: [PATCH 1/7] Initial plan


From dc449d371c36a1a5d1233d2357e6840c79e08423 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 21:16:06 +0000
Subject: [PATCH 2/7] feat: add localhost keyword for playwright testing

- Automatically maps 'localhost' to 'host.docker.internal'
- Enables host access when localhost is specified
- Configures common development ports (3000, 4200, 5173, 8080, etc.)
- Supports protocol prefixes (http://localhost, https://localhost)
- Preserves user-specified --allow-host-ports if provided
- Add comprehensive integration tests for localhost functionality

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 containers/agent/setup-iptables.sh         |   3 +-
 src/cli.ts                                 |  34 +++++
 tests/fixtures/awf-runner.ts               |  11 ++
 tests/integration/localhost-access.test.ts | 137 +++++++++++++++++++++
 4 files changed, 184 insertions(+), 1 deletion(-)
 create mode 100644 tests/integration/localhost-access.test.ts

diff --git a/containers/agent/setup-iptables.sh b/containers/agent/setup-iptables.sh
index f2cf67c8..6fcd7ca7 100644
--- a/containers/agent/setup-iptables.sh
+++ b/containers/agent/setup-iptables.sh
@@ -173,7 +173,8 @@ if [ -n "$AWF_ALLOW_HOST_PORTS" ]; then
     if [[ $port_spec == *"-"* ]]; then
       # Port range (e.g., "3000-3010")
       echo "[iptables]   Redirect port range $port_spec to Squid..."
-      iptables -t nat -A OUTPUT -p tcp -m multiport --dports "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
+      # For port ranges, use --dport with range syntax (without multiport)
+      iptables -t nat -A OUTPUT -p tcp --dport "$port_spec" -j DNAT --to-destination "${SQUID_IP}:${SQUID_PORT}"
     else
       # Single port (e.g., "3000")
       echo "[iptables]   Redirect port $port_spec to Squid..."
diff --git a/src/cli.ts b/src/cli.ts
index ce86006d..c64f708d 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -633,6 +633,40 @@ program
     // Remove duplicates (in case domains appear in both sources)
     allowedDomains = [...new Set(allowedDomains)];
 
+    // Handle special "localhost" keyword for Playwright testing
+    // This makes localhost testing work out of the box without requiring manual configuration
+    const localhostIndex = allowedDomains.findIndex(d => 
+      d === 'localhost' || d === 'http://localhost' || d === 'https://localhost'
+    );
+    if (localhostIndex !== -1) {
+      // Remove localhost and replace with host.docker.internal
+      const localhostValue = allowedDomains[localhostIndex];
+      allowedDomains.splice(localhostIndex, 1);
+      
+      // Preserve protocol if specified
+      if (localhostValue.startsWith('http://')) {
+        allowedDomains.push('http://host.docker.internal');
+      } else if (localhostValue.startsWith('https://')) {
+        allowedDomains.push('https://host.docker.internal');
+      } else {
+        allowedDomains.push('host.docker.internal');
+      }
+      
+      // Auto-enable host access
+      if (!options.enableHostAccess) {
+        options.enableHostAccess = true;
+        logger.info('ℹ️  localhost keyword detected - automatically enabling host access');
+      }
+      
+      // Auto-configure common dev ports if not already specified
+      // Use specific popular development ports to avoid dangerous ports
+      if (!options.allowHostPorts) {
+        options.allowHostPorts = '3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090';
+        logger.info('ℹ️  localhost keyword detected - allowing common development ports (3000, 4200, 5173, 8080, etc.)');
+        logger.info('   Use --allow-host-ports to customize the port list');
+      }
+    }
+
     // Validate all domains and patterns
     for (const domain of allowedDomains) {
       try {
diff --git a/tests/fixtures/awf-runner.ts b/tests/fixtures/awf-runner.ts
index 1ad6e29b..3a37fbd9 100644
--- a/tests/fixtures/awf-runner.ts
+++ b/tests/fixtures/awf-runner.ts
@@ -16,6 +16,7 @@ export interface AwfOptions {
   containerWorkDir?: string; // Working directory inside the container
   tty?: boolean; // Allocate pseudo-TTY (required for interactive tools like Claude Code)
   dnsServers?: string[]; // DNS servers to use (e.g., ['8.8.8.8', '2001:4860:4860::8888'])
+  allowHostPorts?: string; // Ports or port ranges to allow for host access (e.g., '3000' or '3000-8000')
 }
 
 export interface AwfResult {
@@ -92,6 +93,11 @@ export class AwfRunner {
       args.push('--dns-servers', options.dnsServers.join(','));
     }
 
+    // Add allow-host-ports
+    if (options.allowHostPorts) {
+      args.push('--allow-host-ports', options.allowHostPorts);
+    }
+
     // Add -- separator before command
     args.push('--');
 
@@ -211,6 +217,11 @@ export class AwfRunner {
       args.push('--dns-servers', options.dnsServers.join(','));
     }
 
+    // Add allow-host-ports
+    if (options.allowHostPorts) {
+      args.push('--allow-host-ports', options.allowHostPorts);
+    }
+
     // Add -- separator before command
     args.push('--');
 
diff --git a/tests/integration/localhost-access.test.ts b/tests/integration/localhost-access.test.ts
new file mode 100644
index 00000000..591c2f81
--- /dev/null
+++ b/tests/integration/localhost-access.test.ts
@@ -0,0 +1,137 @@
+/**
+ * Localhost Access Tests
+ *
+ * These tests verify the localhost keyword functionality for Playwright testing:
+ * - localhost keyword automatically enables host access
+ * - localhost is mapped to host.docker.internal
+ * - Common dev ports (3000-10000) are automatically allowed
+ * - Protocol prefixes (http://localhost, https://localhost) are preserved
+ */
+
+/// <reference path="../jest-custom-matchers.d.ts" />
+
+import { describe, test, expect, beforeAll, afterAll } from '@jest/globals';
+import { createRunner, AwfRunner } from '../fixtures/awf-runner';
+import { cleanup } from '../fixtures/cleanup';
+
+describe('Localhost Access', () => {
+  let runner: AwfRunner;
+
+  beforeAll(async () => {
+    // Run cleanup before tests to ensure clean state
+    await cleanup(false);
+    runner = createRunner();
+  });
+
+  afterAll(async () => {
+    // Clean up after all tests
+    await cleanup(false);
+  });
+
+  test('should automatically enable host access when localhost is in allowed domains', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['localhost'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    // Check that the logs show automatic host access enablement
+    expect(result.stderr).toContain('localhost keyword detected - automatically enabling host access');
+    expect(result.stderr).toContain('allowing common development ports');
+  }, 120000);
+
+  test('should map localhost to host.docker.internal in configuration', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['localhost'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    // Check that host.docker.internal is in the allowed domains
+    expect(result.stderr).toContain('Allowed domains: host.docker.internal');
+  }, 120000);
+
+  test('should preserve http:// protocol prefix for localhost', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['http://localhost'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    expect(result.stderr).toContain('localhost keyword detected');
+    expect(result.stderr).toContain('Allowed domains: http://host.docker.internal');
+  }, 120000);
+
+  test('should preserve https:// protocol prefix for localhost', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['https://localhost'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    expect(result.stderr).toContain('localhost keyword detected');
+    expect(result.stderr).toContain('Allowed domains: https://host.docker.internal');
+  }, 120000);
+
+  test('should work with localhost combined with other domains', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['localhost', 'github.com', 'example.com'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    expect(result.stderr).toContain('localhost keyword detected');
+    // All domains should be present (localhost replaced with host.docker.internal)
+    expect(result.stderr).toContain('host.docker.internal');
+    expect(result.stderr).toContain('github.com');
+    expect(result.stderr).toContain('example.com');
+  }, 120000);
+
+  test('should allow custom port range to override default', async () => {
+    const result = await runner.runWithSudo('echo "test"', {
+      allowDomains: ['localhost'],
+      allowHostPorts: '8080',
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    // Should not show automatic port range message since user specified their own
+    expect(result.stderr).not.toContain('allowing common development ports');
+  }, 120000);
+
+  test('should resolve host.docker.internal from inside container', async () => {
+    // Verify that host.docker.internal is resolvable
+    const result = await runner.runWithSudo('getent hosts host.docker.internal', {
+      allowDomains: ['localhost'],
+      logLevel: 'debug',
+      timeout: 60000,
+    });
+
+    expect(result).toSucceed();
+    // getent should return IP address for host.docker.internal
+    expect(result.stdout).toMatch(/\d+\.\d+\.\d+\.\d+/);
+  }, 120000);
+
+  test('should work for Playwright-style testing scenario', async () => {
+    // Simulate a Playwright test scenario: testing a local dev server
+    // We can't actually run a server here, but we can verify the setup is correct
+    const result = await runner.runWithSudo(
+      'bash -c "echo Starting Playwright test for localhost && echo Test complete"',
+      {
+        allowDomains: ['localhost'],
+        logLevel: 'info',
+        timeout: 60000,
+      }
+    );
+
+    expect(result).toSucceed();
+    expect(result.stdout).toContain('Starting Playwright test for localhost');
+    expect(result.stdout).toContain('Test complete');
+  }, 120000);
+});

From fb598ac42eca56ec6dae10a71428c541c1570bae Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 21:17:32 +0000
Subject: [PATCH 3/7] docs: add playwright localhost testing documentation

- Add localhost keyword section to AGENTS.md
- Add Playwright testing examples to README.md
- Add comprehensive guide to docs/usage.md
- Create dedicated Playwright testing guide in docs-site
- Explain automatic configuration and security considerations

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 AGENTS.md                                     |  21 +++
 README.md                                     |   9 +
 .../content/docs/guides/playwright-testing.md | 157 ++++++++++++++++++
 docs/usage.md                                 |  25 +++
 4 files changed, 212 insertions(+)
 create mode 100644 docs-site/src/content/docs/guides/playwright-testing.md

diff --git a/AGENTS.md b/AGENTS.md
index 7c16761a..4ad7b660 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -256,6 +256,27 @@ Containers stopped, temporary files cleaned up
   - `.github.com` → matches all subdomains
 - Squid denies any domain not in the allowlist
 
+### Localhost Keyword
+
+The `localhost` keyword provides simplified access to host services for Playwright testing and local development:
+
+**Usage:**
+```bash
+sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
+```
+
+**Automatic configuration when `localhost` is specified:**
+1. Maps `localhost` to `host.docker.internal` (Docker's host gateway)
+2. Enables `--enable-host-access` automatically
+3. Allows common development ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
+4. Preserves protocol prefixes (`http://localhost` → `http://host.docker.internal`)
+
+**Customization:**
+- Use `--allow-host-ports` to override the default port list
+- Example: `--allow-domains localhost --allow-host-ports 3000,8080`
+
+**Security note:** The localhost keyword enables access to host services. Only use for trusted workloads like local testing and development.
+
 ## Exit Code Handling
 
 The wrapper propagates the exit code from the agent container:
diff --git a/README.md b/README.md
index e6026509..0b67de19 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,15 @@ sudo -E awf \
   -- copilot --prompt "List my repositories"
 ```
 
+### Playwright Testing Localhost (out of the box)
+
+```bash
+# Start your dev server, then test it:
+sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
+```
+
+The `localhost` keyword automatically configures everything for local testing.
+
 For checksum verification, version pinning, and manual installation steps, see [Quick start](docs/quickstart.md).
 
 #### GitHub Action (recommended for CI/CD)
diff --git a/docs-site/src/content/docs/guides/playwright-testing.md b/docs-site/src/content/docs/guides/playwright-testing.md
new file mode 100644
index 00000000..ba060f95
--- /dev/null
+++ b/docs-site/src/content/docs/guides/playwright-testing.md
@@ -0,0 +1,157 @@
+---
+title: Playwright Testing with Localhost
+description: Test local web applications with Playwright through the firewall
+---
+
+The firewall makes it easy to test local web applications with Playwright using the `localhost` keyword.
+
+## Quick Start
+
+Test a local development server with Playwright:
+
+```bash
+# Start your dev server (e.g., npm run dev on port 3000)
+
+# Run Playwright tests through the firewall
+sudo awf --allow-domains localhost,playwright.dev -- npx playwright test
+```
+
+The `localhost` keyword automatically configures everything needed for local testing - no manual setup required.
+
+## What the localhost Keyword Does
+
+When you include `localhost` in `--allow-domains`, awf automatically:
+
+1. **Enables host access** - Activates `--enable-host-access` flag
+2. **Maps to host.docker.internal** - Replaces `localhost` with Docker's host gateway
+3. **Allows development ports** - Opens common dev ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
+
+This means your Playwright tests inside the container can reach services running on your host machine's localhost.
+
+## Protocol Prefixes
+
+The `localhost` keyword preserves HTTP/HTTPS protocol prefixes:
+
+```bash
+# HTTP only
+sudo awf --allow-domains http://localhost -- npx playwright test
+
+# HTTPS only
+sudo awf --allow-domains https://localhost -- npx playwright test
+
+# Both HTTP and HTTPS (default)
+sudo awf --allow-domains localhost -- npx playwright test
+```
+
+## Custom Port Configuration
+
+Override the default port list with `--allow-host-ports`:
+
+```bash
+# Allow only specific ports
+sudo awf \
+  --allow-domains localhost \
+  --allow-host-ports 3000,8080 \
+  -- npx playwright test
+
+# Allow a port range
+sudo awf \
+  --allow-domains localhost \
+  --allow-host-ports 3000,8080-8090 \
+  -- npx playwright test
+```
+
+:::note
+Port ranges must avoid dangerous ports (SSH, databases, etc.). See the [security model](/gh-aw-firewall/concepts/security-model) for details.
+:::
+
+## Example: Testing a Next.js App
+
+```bash
+# Terminal 1: Start Next.js dev server
+npm run dev
+# Server runs on http://localhost:3000
+
+# Terminal 2: Run Playwright tests through firewall
+sudo awf \
+  --allow-domains localhost,vercel.app,next.js.org \
+  -- npx playwright test
+```
+
+Your Playwright tests can now access `http://localhost:3000` and also fetch from `vercel.app` and `next.js.org`.
+
+## Example: Testing a React App with External APIs
+
+```bash
+# Start React dev server on port 3000
+npm start
+
+# Run tests with access to localhost and external APIs
+sudo awf \
+  --allow-domains localhost,api.github.com,cdn.example.com \
+  -- npx playwright test
+```
+
+## Without the localhost Keyword
+
+Before the `localhost` keyword, you had to manually configure host access:
+
+```bash
+# Old way (still works)
+sudo awf \
+  --enable-host-access \
+  --allow-domains host.docker.internal \
+  --allow-host-ports 3000,8080 \
+  -- npx playwright test
+```
+
+The `localhost` keyword eliminates this boilerplate.
+
+## Security Considerations
+
+:::caution
+The `localhost` keyword enables access to services running on your host machine. Only use it for trusted workloads like local testing and development.
+:::
+
+When `localhost` is specified:
+- Containers can access ANY service on the specified ports on your host machine
+- This includes local databases, development servers, and other services
+- This is safe for local development but should not be used in production
+
+## Troubleshooting
+
+### "Connection refused" errors
+
+If Playwright can't connect to your local server:
+
+1. **Verify server is running:** Check that your dev server is actually running on the host
+2. **Check the port:** Ensure the port is in the allowed list (default: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090)
+3. **Use custom ports:** If using a different port, specify it with `--allow-host-ports`
+
+### "Host not found" errors
+
+If you see DNS resolution errors:
+
+- Use `localhost` (not `127.0.0.1` or your machine's hostname)
+- The `localhost` keyword maps to `host.docker.internal` which resolves to the host
+
+### Server binds to 127.0.0.1 only
+
+Some dev servers bind only to 127.0.0.1. To make them accessible from Docker containers:
+
+```bash
+# Bind to 0.0.0.0 instead of 127.0.0.1
+npm run dev -- --host 0.0.0.0
+
+# Or for Vite/Vue
+npm run dev -- --host
+
+# Or for Next.js
+npm run dev -- -H 0.0.0.0
+```
+
+## See Also
+
+- [Server Connectivity](/gh-aw-firewall/guides/server-connectivity) - Connecting to HTTP, HTTPS, and gRPC servers
+- [Security Model](/gh-aw-firewall/concepts/security-model) - Understanding the firewall's security guarantees
+- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - All command-line options
diff --git a/docs/usage.md b/docs/usage.md
index 66f62518..e3e72712 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -45,6 +45,31 @@ sudo awf \
   'curl https://api.github.com'
 ```
 
+### Playwright Testing Localhost
+
+Test local web applications with Playwright without complex configuration:
+
+```bash
+# Start your dev server (e.g., npm run dev on port 3000)
+# Then run Playwright tests through the firewall:
+sudo awf \
+  --allow-domains localhost,playwright.dev \
+  'npx playwright test'
+```
+
+The `localhost` keyword automatically:
+- Enables access to host services via `host.docker.internal`
+- Allows common development ports (3000, 4200, 5173, 8080, etc.)
+- Works with both HTTP and HTTPS protocols
+
+You can customize the ports with `--allow-host-ports`:
+```bash
+sudo awf \
+  --allow-domains localhost \
+  --allow-host-ports 3000,8080 \
+  'npx playwright test'
+```
+
 ### With GitHub Copilot CLI
 
 ```bash

From f0db83fac94cc20007cc366ec446e7953d23b579 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 26 Jan 2026 21:18:21 +0000
Subject: [PATCH 4/7] docs: update CLI help text for localhost keyword

Add localhost to --allow-domains help text explaining it auto-configures for local testing

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 src/cli.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/cli.ts b/src/cli.ts
index c64f708d..6de5b8aa 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -447,7 +447,8 @@ program
     '                                   *.github.com       - any subdomain of github.com\n' +
     '                                   api-*.example.com  - api-* subdomains\n' +
     '                                   https://secure.com - HTTPS only\n' +
-    '                                   http://legacy.com  - HTTP only'
+    '                                   http://legacy.com  - HTTP only\n' +
+    '                                   localhost          - auto-configure for local testing (Playwright, etc.)'
   )
   .option(
     '--allow-domains-file <path>',

From 6ba8651bac80cad4b982321c22ac708717dd3f7f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 3 Feb 2026 20:07:52 +0000
Subject: [PATCH 5/7] test: add unit tests for localhost keyword processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract localhost processing logic into testable function and add comprehensive unit tests covering:
- Plain localhost, http://localhost, https://localhost variants
- Protocol prefix preservation
- Host access auto-enablement
- Default port configuration
- Edge cases and domain order preservation

Coverage improvements:
- Overall: 81.58% → 82.03% (+0.45%)
- cli.ts lines: 37.82% → 41.47% (+3.65%)
- cli.ts branches: 31.03% → 38.01% (+6.98%)

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 src/cli.test.ts | 154 +++++++++++++++++++++++++++++++++++++++++++++++-
 src/cli.ts      |  97 +++++++++++++++++++++++-------
 2 files changed, 229 insertions(+), 22 deletions(-)

diff --git a/src/cli.test.ts b/src/cli.test.ts
index ea697c90..eca3f4e5 100644
--- a/src/cli.test.ts
+++ b/src/cli.test.ts
@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption } from './cli';
+import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword } from './cli';
 import { redactSecrets } from './redact-secrets';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -1140,4 +1140,156 @@ describe('cli', () => {
       });
     });
   });
+
+  describe('processLocalhostKeyword', () => {
+    describe('when localhost keyword is not present', () => {
+      it('should return domains unchanged', () => {
+        const result = processLocalhostKeyword(
+          ['github.com', 'example.com'],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(false);
+        expect(result.allowedDomains).toEqual(['github.com', 'example.com']);
+        expect(result.shouldEnableHostAccess).toBe(false);
+        expect(result.defaultPorts).toBeUndefined();
+      });
+    });
+
+    describe('when plain localhost is present', () => {
+      it('should replace localhost with host.docker.internal', () => {
+        const result = processLocalhostKeyword(
+          ['localhost', 'github.com'],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.allowedDomains).toEqual(['github.com', 'host.docker.internal']);
+        expect(result.shouldEnableHostAccess).toBe(true);
+        expect(result.defaultPorts).toBe('3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090');
+      });
+
+      it('should replace localhost when it is the only domain', () => {
+        const result = processLocalhostKeyword(
+          ['localhost'],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.allowedDomains).toEqual(['host.docker.internal']);
+        expect(result.shouldEnableHostAccess).toBe(true);
+      });
+    });
+
+    describe('when http://localhost is present', () => {
+      it('should replace with http://host.docker.internal', () => {
+        const result = processLocalhostKeyword(
+          ['http://localhost', 'github.com'],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.allowedDomains).toEqual(['github.com', 'http://host.docker.internal']);
+        expect(result.shouldEnableHostAccess).toBe(true);
+        expect(result.defaultPorts).toBe('3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090');
+      });
+    });
+
+    describe('when https://localhost is present', () => {
+      it('should replace with https://host.docker.internal', () => {
+        const result = processLocalhostKeyword(
+          ['https://localhost', 'github.com'],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.allowedDomains).toEqual(['github.com', 'https://host.docker.internal']);
+        expect(result.shouldEnableHostAccess).toBe(true);
+        expect(result.defaultPorts).toBe('3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090');
+      });
+    });
+
+    describe('when host access is already enabled', () => {
+      it('should not suggest enabling host access again', () => {
+        const result = processLocalhostKeyword(
+          ['localhost', 'github.com'],
+          true, // Already enabled
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.shouldEnableHostAccess).toBe(false);
+        expect(result.defaultPorts).toBe('3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090');
+      });
+    });
+
+    describe('when custom ports are already specified', () => {
+      it('should not suggest default ports', () => {
+        const result = processLocalhostKeyword(
+          ['localhost', 'github.com'],
+          false,
+          '8080,9000' // Custom ports
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.shouldEnableHostAccess).toBe(true);
+        expect(result.defaultPorts).toBeUndefined();
+      });
+    });
+
+    describe('when both host access and custom ports are specified', () => {
+      it('should not suggest either', () => {
+        const result = processLocalhostKeyword(
+          ['localhost', 'github.com'],
+          true, // Already enabled
+          '8080' // Custom ports
+        );
+
+        expect(result.localhostDetected).toBe(true);
+        expect(result.shouldEnableHostAccess).toBe(false);
+        expect(result.defaultPorts).toBeUndefined();
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should only replace first occurrence of localhost', () => {
+        // Although unlikely, the function should handle this gracefully
+        const result = processLocalhostKeyword(
+          ['localhost', 'github.com', 'http://localhost'],
+          false,
+          undefined
+        );
+
+        // Should only replace the first match
+        expect(result.localhostDetected).toBe(true);
+        expect(result.allowedDomains).toEqual(['github.com', 'http://localhost', 'host.docker.internal']);
+      });
+
+      it('should preserve domain order', () => {
+        const result = processLocalhostKeyword(
+          ['github.com', 'localhost', 'example.com'],
+          false,
+          undefined
+        );
+
+        expect(result.allowedDomains).toEqual(['github.com', 'example.com', 'host.docker.internal']);
+      });
+
+      it('should handle empty domains list', () => {
+        const result = processLocalhostKeyword(
+          [],
+          false,
+          undefined
+        );
+
+        expect(result.localhostDetected).toBe(false);
+        expect(result.allowedDomains).toEqual([]);
+      });
+    });
+  });
 });
diff --git a/src/cli.ts b/src/cli.ts
index bd699d19..971951c7 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -268,6 +268,70 @@ export function parseDnsServers(input: string): string[] {
   return servers;
 }
 
+/**
+ * Result of processing the localhost keyword in allowed domains
+ */
+export interface LocalhostProcessingResult {
+  /** Updated array of allowed domains with localhost replaced by host.docker.internal */
+  allowedDomains: string[];
+  /** Whether the localhost keyword was found and processed */
+  localhostDetected: boolean;
+  /** Whether host access should be enabled (if not already enabled) */
+  shouldEnableHostAccess: boolean;
+  /** Default port list to use if no custom ports were specified */
+  defaultPorts?: string;
+}
+
+/**
+ * Processes the localhost keyword in the allowed domains list.
+ * This function handles the logic for replacing localhost with host.docker.internal,
+ * preserving protocol prefixes, and determining whether to auto-enable host access
+ * and default development ports.
+ *
+ * @param allowedDomains - Array of allowed domains (may include localhost variants)
+ * @param enableHostAccess - Whether host access is already enabled
+ * @param allowHostPorts - Custom host ports if already specified
+ * @returns LocalhostProcessingResult with the processed values
+ */
+export function processLocalhostKeyword(
+  allowedDomains: string[],
+  enableHostAccess: boolean,
+  allowHostPorts: string | undefined
+): LocalhostProcessingResult {
+  const localhostIndex = allowedDomains.findIndex(d => 
+    d === 'localhost' || d === 'http://localhost' || d === 'https://localhost'
+  );
+
+  if (localhostIndex === -1) {
+    return {
+      allowedDomains,
+      localhostDetected: false,
+      shouldEnableHostAccess: false,
+    };
+  }
+
+  // Remove localhost and replace with host.docker.internal
+  const localhostValue = allowedDomains[localhostIndex];
+  const updatedDomains = [...allowedDomains];
+  updatedDomains.splice(localhostIndex, 1);
+  
+  // Preserve protocol if specified
+  if (localhostValue.startsWith('http://')) {
+    updatedDomains.push('http://host.docker.internal');
+  } else if (localhostValue.startsWith('https://')) {
+    updatedDomains.push('https://host.docker.internal');
+  } else {
+    updatedDomains.push('host.docker.internal');
+  }
+
+  return {
+    allowedDomains: updatedDomains,
+    localhostDetected: true,
+    shouldEnableHostAccess: !enableHostAccess,
+    defaultPorts: allowHostPorts ? undefined : '3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090',
+  };
+}
+
 /**
  * Escapes a shell argument by wrapping it in single quotes and escaping any single quotes within it
  * @param arg - Argument to escape
@@ -643,33 +707,24 @@ program
 
     // Handle special "localhost" keyword for Playwright testing
     // This makes localhost testing work out of the box without requiring manual configuration
-    const localhostIndex = allowedDomains.findIndex(d => 
-      d === 'localhost' || d === 'http://localhost' || d === 'https://localhost'
+    const localhostResult = processLocalhostKeyword(
+      allowedDomains,
+      options.enableHostAccess || false,
+      options.allowHostPorts
     );
-    if (localhostIndex !== -1) {
-      // Remove localhost and replace with host.docker.internal
-      const localhostValue = allowedDomains[localhostIndex];
-      allowedDomains.splice(localhostIndex, 1);
-      
-      // Preserve protocol if specified
-      if (localhostValue.startsWith('http://')) {
-        allowedDomains.push('http://host.docker.internal');
-      } else if (localhostValue.startsWith('https://')) {
-        allowedDomains.push('https://host.docker.internal');
-      } else {
-        allowedDomains.push('host.docker.internal');
-      }
-      
+
+    if (localhostResult.localhostDetected) {
+      allowedDomains = localhostResult.allowedDomains;
+
       // Auto-enable host access
-      if (!options.enableHostAccess) {
+      if (localhostResult.shouldEnableHostAccess) {
         options.enableHostAccess = true;
         logger.info('ℹ️  localhost keyword detected - automatically enabling host access');
       }
-      
+
       // Auto-configure common dev ports if not already specified
-      // Use specific popular development ports to avoid dangerous ports
-      if (!options.allowHostPorts) {
-        options.allowHostPorts = '3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090';
+      if (localhostResult.defaultPorts) {
+        options.allowHostPorts = localhostResult.defaultPorts;
         logger.info('ℹ️  localhost keyword detected - allowing common development ports (3000, 4200, 5173, 8080, etc.)');
         logger.info('   Use --allow-host-ports to customize the port list');
       }

From 079ab7808cc3d439c8186dd99537a2782d5f50be Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 4 Feb 2026 17:18:58 +0000
Subject: [PATCH 6/7] fix: add security warning for localhost keyword host
 access

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 package-lock.json | 4 ++--
 src/cli.ts        | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 5a3b233e..c37455db 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@github/agentic-workflow-firewall",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@github/agentic-workflow-firewall",
-      "version": "0.13.3",
+      "version": "0.13.4",
       "license": "MIT",
       "dependencies": {
         "chalk": "^4.1.2",
diff --git a/src/cli.ts b/src/cli.ts
index 1040fcbb..c0323a10 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -752,6 +752,7 @@ program
       // Auto-enable host access
       if (localhostResult.shouldEnableHostAccess) {
         options.enableHostAccess = true;
+        logger.warn('⚠️  Security warning: localhost keyword enables host access - agent can reach services on your machine');
         logger.info('ℹ️  localhost keyword detected - automatically enabling host access');
       }
 

From e7abfc20ab32b21ed41b9bf14b53b3c3b94b166e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 4 Feb 2026 17:20:38 +0000
Subject: [PATCH 7/7] test: verify security warning in localhost integration
 test

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
---
 tests/integration/localhost-access.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/integration/localhost-access.test.ts b/tests/integration/localhost-access.test.ts
index 591c2f81..917a3c0e 100644
--- a/tests/integration/localhost-access.test.ts
+++ b/tests/integration/localhost-access.test.ts
@@ -36,7 +36,8 @@ describe('Localhost Access', () => {
     });
 
     expect(result).toSucceed();
-    // Check that the logs show automatic host access enablement
+    // Check that the logs show security warning first, then automatic host access enablement
+    expect(result.stderr).toContain('Security warning: localhost keyword enables host access - agent can reach services on your machine');
     expect(result.stderr).toContain('localhost keyword detected - automatically enabling host access');
     expect(result.stderr).toContain('allowing common development ports');
   }, 120000);