feat: add --agent-base-image act for pre-built GitHub Actions parity

[Mossaka]

Summary

Add support for --agent-base-image act which uses the pre-built agent-act image from GHCR without requiring --build-local.

Changes

• CLI accepts act as a special value for --agent-base-image
• When act is specified, uses ghcr.io/githubnext/gh-aw-firewall/agent-act:latest
• Custom images (e.g., ghcr.io/catthehacker/ubuntu:runner-22.04) still require --build-local (now errors instead of silently warning)
• Added useAgentActImage flag to WrapperConfig
• Updated docker-manager to select agent-act image when flag is set
• Added tests for new functionality

Usage

# Use pre-built agent-act image with GitHub Actions parity
awf --agent-base-image act --allow-domains github.com -- your-command

# Still works: default minimal image
awf --allow-domains github.com -- your-command

# Still works: custom image with --build-local (requires source checkout)
awf --build-local --agent-base-image ghcr.io/catthehacker/ubuntu:runner-22.04 \
  --allow-domains github.com -- your-command

Test plan

• Unit tests for useAgentActImage in docker-manager
• Manual test: awf --agent-base-image act --allow-domains github.com -- curl https://github.com
• Verify error when using custom image without --build-local

Closes #395

🤖 Generated with Claude Code

[github-actions]

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

[github-actions]

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

[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.63%	77.42%	📉 -0.21%
Statements	77.71%	77.50%	📉 -0.21%
Functions	77.54%	77.54%	➡️ +0.00%
Branches	70.44%	70.31%	📉 -0.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/cli.ts	35.9% → 35.3% (-0.65%)	36.2% → 35.5% (-0.66%)
src/docker-manager.ts	79.3% → 79.4% (+0.06%)	78.6% → 78.7% (+0.06%)

---

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

[github-actions]

Smoke Test Results

• ✅ GitHub MCP: feat: add configurable agent base image for GitHub Actions runner parity #214, ci: use local awf build in smoke workflows #388
• ✅ Playwright: GitHub page title verified
• ✅ File Write: /tmp/gh-aw/agent/smoke-test-copilot-21270375845.txt
• ✅ Bash: File read successful

Status: PASS - @Mossaka

AI generated by Smoke Copilot

[github-actions]

Security Review: Supply Chain Validation Bypass

I've identified a security concern in this PR that introduces a supply chain security validation bypass.

Issue: Skipped Validation for agent-act Image

Location: src/cli.ts:690-693

Code:

// Special case: 'act' uses pre-built GHCR image (no --build-local needed)
if (options.agentBaseImage === 'act') {
  config.useAgentActImage = true;
  logger.info('Using pre-built agent-act image with GitHub Actions parity');
}

Problem:
When --agent-base-image act is specified, the code bypasses the validateAgentBaseImage() function entirely. This means:

1. The agent-act image from GHCR (ghcr.io/githubnext/gh-aw-firewall/agent-act:latest) is trusted implicitly
2. No validation is performed to ensure this image meets security requirements
3. Users can pull arbitrary versions without supply chain verification

Why This Matters:

• All other custom images go through validateAgentBaseImage() which validates against approved patterns
• The agent-act image contains additional tools and packages (GitHub Actions parity) which expand the attack surface
• Container image supply chain security is a critical defense layer in this firewall

Recommended Actions

1. Add validation for the act keyword - Ensure 'act' is explicitly validated even though it maps to a pre-built image:

   if (options.agentBaseImage === 'act') {
     // Validate that 'act' is an approved keyword
     config.useAgentActImage = true;
     logger.info('Using pre-built agent-act image with GitHub Actions parity');
   }

2. Document the trust model - Add a comment explaining why the agent-act image is trusted (e.g., "Built from this repository's Dockerfile via GitHub Actions release workflow")

3. Consider adding image digest pinning - For production use, consider allowing users to specify a digest:

   --agent-base-image act@sha256:...

Context

The existing validateAgentBaseImage() function (lines 127-145) is a security control that prevents arbitrary base images from being used. It validates against a strict allowlist of patterns (SAFE_BASE_IMAGE_PATTERNS). This PR creates a special case that sidesteps this validation.

While the agent-act image is likely safe (as it's built from this repository), the pattern of bypassing validation sets a concerning precedent. Future changes could introduce similar bypasses or users might expect other keywords to work without validation.

AI generated by Security Guard

[github-actions]

Smoke Test Results - Claude Engine

Last 2 Merged PRs:

• mossaka/log filtering #5: mossaka/log filtering
• Improve links in readme to AW project #1: Improve links in readme to AW project

Test Results:

• ✅ GitHub MCP: Retrieved PR data
• ✅ Playwright: Page title confirmed "GitHub · Change is constant. GitHub keeps you ahead. · GitHub"
• ✅ File Writing: Created test file successfully
• ✅ Bash Tool: Verified file content

Status: PASS

AI generated by Smoke Claude

[Mossaka]

Closing PR to reduce backlog. The work is tracked in issue #395 (which was closed as completed). Will revisit if needed.