feat: add localhost keyword for playwright testing

[Copilot]

Playwright tests against local dev servers required manual configuration of host access, domain mapping, and port allowlists. The localhost keyword now auto-configures this setup.

Changes

CLI Enhancement (src/cli.ts)

• localhost in --allow-domains automatically:
  • Maps to host.docker.internal (preserves http:// / https:// prefixes)
  • Enables --enable-host-access
  • Allows common dev ports: 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
  • User override via --allow-host-ports still respected

Container Fix (containers/agent/setup-iptables.sh)

• Removed multiport module from port range rules (not supported by iptables DNAT)

Testing (tests/integration/localhost-access.test.ts)

• 8 test cases covering auto-enable, protocol prefixes, custom ports, host resolution

Documentation

• Added Playwright guide to docs-site
• Updated README, usage docs, and AGENTS.md

Usage

# Before
sudo awf \
  --enable-host-access \
  --allow-domains host.docker.internal \
  --allow-host-ports 3000,8080 \
  -- npx playwright test

# After
sudo awf --allow-domains localhost,playwright.dev -- npx playwright test

Security warnings maintained for host access. Custom port lists still supported via --allow-host-ports.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Playwright testing</issue_title>
<issue_description>Texting a localhost web site should work out of the box.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Playwright testing #102

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

🎬 THE END — Smoke Claude MISSION: ACCOMPLISHED! The hero saves the day! ✨

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

[github-actions]

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	77.98%	77.23%	📉 -0.75%
Statements	78.05%	77.32%	📉 -0.73%
Functions	77.77%	77.36%	📉 -0.41%
Branches	71.70%	70.64%	📉 -1.06%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
src/cli.ts	40.1% → 37.8% (-2.24%)	40.3% → 38.0% (-2.24%)

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[github-actions]

Smoke Test Results

Last 2 merged PRs:

• fix(deps): update js-yaml to 3.14.2 (CVE fix) #424: fix(deps): update js-yaml to 3.14.2 (CVE fix)
• chore: remove unused release workflow files #423: chore: remove unused release workflow files

✅ GitHub MCP
✅ Playwright (title: "GitHub · Change is constant. GitHub keeps you ahead. · GitHub")
✅ File writing
✅ Bash tool

Status: PASS

cc @Copilot @Mossaka

AI generated by Smoke Copilot

[github-actions]

Smoke Test Results (Claude Engine)

GitHub MCP:

• fix(deps): update js-yaml to 3.14.2 (CVE fix) #424: fix(deps): update js-yaml to 3.14.2 (CVE fix)
• chore: remove unused release workflow files #423: chore: remove unused release workflow files

Tests:
✅ GitHub MCP - Retrieved last 2 merged PRs
✅ Playwright - Verified page title "GitHub · Change is constant. GitHub keeps you ahead. · GitHub"
✅ File Writing - Created /tmp/gh-aw/agent/smoke-test-claude-21374333874.txt
✅ Bash Tool - Verified file contents

Status: PASS

AI generated by Smoke Claude

[github-actions]

Security Review: Localhost Keyword Feature

I've reviewed PR #427 for security implications. The implementation is generally sound with proper validation, but I found one security concern that should be addressed before merge.

---

🔴 Security Issue: Port 8888 in Default Port List

File: src/cli.ts (line 665)

Issue: The default localhost port list includes port 8888, which is commonly used by Jupyter Notebook/JupyterLab servers:

options.allowHostPorts = '3000,3001,4000,4200,5000,5173,8000,8080,8081,8888,9000,9090';

Security Risk:

• Jupyter servers provide arbitrary code execution capabilities via notebooks
• If a user has a Jupyter server running on their host machine while using the firewall, the localhost keyword would automatically grant AI agents access to it
• This creates an unintended privilege escalation path where an agent could execute Python code on the host

Recommendation:

1. Remove port 8888 from the default list, OR
2. Add port 8888 to DANGEROUS_PORTS constant in src/squid-config.ts to block it entirely

Suggested fix:

// Remove 8888 from this line:
options.allowHostPorts = '3000,3001,4000,4200,5000,5173,8000,8080,8081,9000,9090';

Users who genuinely need Jupyter access can explicitly specify --allow-host-ports 8888 with full awareness of the security implications.

---

✅ Security Aspects That Are Safe

1. Port validation works correctly - All ports go through the existing DANGEROUS_PORTS check in squid-config.ts which blocks SSH (22), databases (3306, 5432, etc.), and other sensitive services

2. iptables bug fix is legitimate - The removal of -m multiport from DNAT rules (line 177 in setup-iptables.sh) is a valid fix since multiport doesn't support port ranges in DNAT context

3. Protocol preservation - HTTP/HTTPS prefixes are correctly preserved when mapping localhost to host.docker.internal

4. User override capability - Users can still customize with --allow-host-ports to override defaults

5. Host access intentional - The automatic enablement of --enable-host-access is documented with appropriate security warnings

---

Verdict

Conditional approval - Safe to merge after removing port 8888 from the default list. All other aspects of the implementation maintain the firewall's security posture.

AI generated by Security Guard