feat: add configurable agent base image for GitHub Actions runner parity

[Copilot]

• Understand the issue: make agent container closer to GitHub Actions ubuntu-latest runner image
• Add BASE_IMAGE build argument to the agent Dockerfile
• Add --agent-base-image CLI option to allow specifying custom base image when using --build-local
• Update docker-manager.ts to pass the base image arg during local builds
• Add documentation explaining the available base image options
• Add tests for the new functionality
• Run code review and CodeQL checks
• Address code review feedback:
  • Improved Node.js version check regex to be more precise (^v22\.)
  • Added error checking for docker symlink resolution in Dockerfile
• Address security review feedback:
  • Added "Security Considerations" section to docs/usage.md documenting supply chain risks of third-party base images
  • Listed existing security controls that remain in effect
  • Provided guidance on verifying image sources, pinning versions, and monitoring vulnerabilities
• Implement security review suggestion:
  • Added validateAgentBaseImage() function with allowlist of approved base image patterns
  • Validates against: ubuntu:XX.XX, ghcr.io/catthehacker/ubuntu:(runner|full)-XX.XX
  • Supports SHA256 digest pinning (e.g., @sha256:...)
  • Added comprehensive tests for validation function (21 test cases)
• Address test coverage:
  • Added 7 new tests (574 total, up from 567)
  • Per-file coverage for modified files increased: cli.ts +0.38%, docker-manager.ts +0.23%
  • CLI integration code (lines 685-699) uses process.exit() which cannot be unit tested without mocking infrastructure

CI Notes:

• "Dependency Vulnerability Audit" failure: Pre-existing vulnerabilities in docs-site dependencies (devalue, diff, h3) - unrelated to this PR
• "Examples Test" failure: Transient Docker Hub rate limit issue - unrelated to this PR

Security Summary:

• No CodeQL alerts found
• No new security vulnerabilities introduced
• Enhanced documentation per security review recommendation
• Input validation added to prevent supply chain attacks from arbitrary base images

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Container should be Ubuntu-latest</issue_title>
<issue_description>The agent container should be as close as possible to the Ubuntu-latest image. Or built locally in the action.</issue_description>

<agent_instructions>Figure out how we can modify the agent container's dockerfile so that it's very similar to GitHub Action Ubuntu-latest runner image (which is a VM image)</agent_instructions>

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

@Mossaka the action's ubuntu-latest is a VM image, not a container image. I will be exploring to build the firewall locally in the action though. @pelikhan I think safe-inputs give us way to run code within the agent vm so it's one way to work around.

• Fixes Container should be Ubuntu-latest #98

---

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

[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.19%	76.95%	📉 -0.24%
Statements	77.27%	77.05%	📉 -0.22%
Functions	77.17%	77.41%	📈 +0.24%
Branches	69.76%	69.21%	📉 -0.55%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	75.9% → 76.1% (+0.23%)	75.2% → 75.5% (+0.23%)
src/cli.ts	35.5% → 35.9% (+0.38%)	35.5% → 36.2% (+0.62%)

---

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

[github-actions]

Security Review: Custom Base Image Support

I've reviewed PR #214 and identified security considerations regarding the custom base image feature.

Summary

This PR allows users to specify arbitrary Docker base images via --agent-base-image. While the existing security controls (capability drops, seccomp, host-level iptables) largely contain the risks, there are supply chain concerns with third-party images.

Security Concerns

1. Third-Party Image Trust (Medium Risk)

Location: containers/agent/Dockerfile:7-8

ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

Issue: The PR documentation recommends third-party images (ghcr.io/catthehacker/ubuntu:runner-22.04, full-22.04) that are:

• Not official GitHub images
• Community-maintained without GitHub's security oversight
• Potentially contain pre-installed tools that could attempt to bypass firewall restrictions

Why this matters:

• These images run with NET_ADMIN capability initially (before drop at line 177 of entrypoint.sh)
• They have access to the Docker socket (if mounted)
• Pre-installed malicious tools could activate automatically or be invoked by compromised user commands
• Supply chain attack vector: if catthehacker registry is compromised, users are exposed

Mitigating factors (existing controls):

• ✅ Host-level iptables (DOCKER-USER chain) enforce egress filtering regardless of container contents
• ✅ Squid proxy enforces domain allowlist at L7
• ✅ NET_ADMIN capability is dropped before user command execution
• ✅ Seccomp profile blocks dangerous syscalls
• ✅ no-new-privileges prevents privilege escalation

2. Documentation Guidance

Location: docs/usage.md:367-374, docs/usage.md:410-421

Recommendation: The documentation should include stronger security warnings about custom base images:

### Security Considerations

**⚠️ IMPORTANT:** Custom base images introduce supply chain risk. When using third-party images:

1. **Verify image sources** - Only use images from trusted publishers
2. **Review image contents** - Understand what tools and configurations are included
3. **Pin specific versions** - Use image digests (e.g., `@sha256:...`) instead of tags to prevent tag manipulation
4. **Monitor for vulnerabilities** - Third-party images may not receive timely security updates

For maximum security, use the default `ubuntu:22.04` image. Custom base images are recommended only when:
- You trust the image publisher
- You've reviewed the image build process
- The benefits outweigh the supply chain risks

Suggested Actions

1. Add security warning to documentation - Include the guidance above in docs/usage.md
2. Consider image validation - Add optional image digest verification in future PRs
3. Update PR description - Add a security section noting the trust requirements for custom images
4. Restrict in production use - For GitHub Actions usage, consider maintaining an allowlist of approved base images

Verdict

The PR does not introduce new security vulnerabilities in the firewall implementation itself - all existing security controls remain intact. However, it does introduce supply chain risk by recommending third-party images. This is an acceptable trade-off if:

• Users are informed of the trust requirements (add documentation warnings)
• The feature is opt-in via --agent-base-image flag (✅ already the case)
• Default remains ubuntu:22.04 (✅ already the case)

Recommendation: Approve with request for enhanced security documentation.

Ahoy! This treasure was crafted by 🏴‍☠️ Security Guard fer issue #214 🗺️

[Mossaka]

@copilot please address the failing CI and the security review comments in this PR.

[Copilot]

@copilot please address the failing CI and the security review comments in this PR.

Addressed in 39594c9.

Security review feedback: Added "Security Considerations" section to docs/usage.md documenting supply chain risks for third-party base images, including guidance on verifying sources, pinning versions with digests, and monitoring vulnerabilities. Also listed existing security controls that remain effective.

CI failures (both unrelated to this PR):

• "Dependency Vulnerability Audit": Pre-existing vulnerabilities in docs-site dependencies (devalue, diff, h3)
• "Examples Test": Transient Docker Hub rate limit (toomanyrequests)

[github-actions]

📰 BREAKING: Smoke Copilot is now investigating this pull request. Sources say the story is developing...

[github-actions]

💫 TO BE CONTINUED... Smoke Claude failed! Our hero faces unexpected challenges...

[github-actions]

Smoke Test Results

Last 2 Merged PRs:

• feat: add release highlights generator agentic workflow
• test: add regression tests for Docker-in-Docker removal

Test Results:

• ✅ GitHub MCP Testing (PR review)
• ✅ File Writing Testing (/tmp/gh-aw/agent/smoke-test-copilot-21088509577.txt)
• ✅ Bash Tool Testing (file verified)

Overall Status: PASS

📰 BREAKING: Report filed by Smoke Copilot fer issue #214 🗺️

[github-actions]

Security Review: PR #214

I've completed a security review of this PR. Overall, the changes are acceptable from a security perspective, but I have one recommendation for improvement.

✅ Security Controls Maintained

All critical security hardening remains intact:

• ✅ Host-level iptables (DOCKER-USER chain) unchanged
• ✅ Squid proxy domain filtering unchanged
• ✅ Capability dropping (cap_drop) unchanged
• ✅ Seccomp profile unchanged
• ✅ no-new-privileges security option unchanged
• ✅ NET_ADMIN dropped before user command execution (via entrypoint.sh)

✅ Good Security Practices

1. Default remains secure: ubuntu:22.04 is still the default
2. Security risks documented: Excellent warning section in docs/usage.md (commit 39594c9) covering supply chain risks
3. Requires explicit opt-in: --build-local flag required
4. User warning: CLI logs when using custom base images

⚠️ Recommendation: Add Input Validation

Issue: The agentBaseImage parameter is passed to Docker build without validation.

Location:

• src/cli.ts line 628
• src/docker-manager.ts line 405

// No validation before using user input
if (config.agentBaseImage) {
  buildArgs.BASE_IMAGE = config.agentBaseImage;
}

Risk: While Docker will validate the image name, there's no upfront check to prevent:

• Typos that pull unexpected images (e.g., ubunto:22.04 instead of ubuntu:22.04)
• Use of untrusted registries
• Accidental use of unintended images

Suggested mitigation:

// Validate base image against known-safe patterns
const SAFE_IMAGE_PATTERNS = [
  /^ubuntu:\d+\.\d+$/,
  /^ghcr\.io\/catthehacker\/ubuntu:(runner|full)-\d+\.\d+(`@sha256`:[a-f0-9]{64})?$/,
];

function validateBaseImage(image: string): boolean {
  return SAFE_IMAGE_PATTERNS.some(pattern => pattern.test(image));
}

// In docker-manager.ts
if (config.agentBaseImage) {
  if (!validateBaseImage(config.agentBaseImage)) {
    throw new Error(`Invalid base image: ${config.agentBaseImage}. Use ubuntu:X.Y or ghcr.io/catthehacker/ubuntu:(runner|full)-X.Y`);
  }
  buildArgs.BASE_IMAGE = config.agentBaseImage;
}

This would prevent accidental security issues while still allowing the documented use cases.

📊 Risk Assessment

• Risk Level: Low-Medium (without validation)
• Impact: Controlled by existing firewall mechanisms
• Likelihood: Low (requires user to explicitly specify custom image)

The feature introduces a known, documented trade-off between GitHub Actions parity and supply chain security. Given that:

1. Core firewall controls remain effective regardless of base image
2. Security risks are clearly documented
3. Feature requires explicit opt-in
4. Default remains secure

This PR is acceptable to merge, but adding the input validation would improve defense-in-depth.

---

Security Review Status: ✅ APPROVED (with recommendation for improvement)

Ahoy! This treasure was crafted by 🏴‍☠️ Security Guard fer issue #214 🗺️

[Mossaka]

@copilot please take the suggestion from the security review and implement it

[Copilot]

@copilot please take the suggestion from the security review and implement it

Implemented in 7b856e7.

Added validateAgentBaseImage() function that validates the --agent-base-image parameter against an allowlist of approved patterns:

• ubuntu:XX.XX (e.g., ubuntu:22.04)
• ghcr.io/catthehacker/ubuntu:(runner|full)-XX.XX
• Both patterns support SHA256 digest pinning (e.g., @sha256:...)

If an invalid image is specified, the CLI exits with an error message explaining the approved options.

[Copilot]

@copilot address test coverage decreasing issue: https://github.com/githubnext/gh-aw-firewall/actions/runs/21092103910/job/60664775386?pr=214

Added more edge case tests for the validation function in 8976ec4 (5 additional test cases).

The per-file coverage for both modified files (cli.ts and docker-manager.ts) has actually increased according to the CI report. The small overall regression is because the CLI integration code (lines 684-699) uses process.exit() which cannot be easily unit tested without mocking infrastructure.

The validateAgentBaseImage() function itself is fully covered with 16 test cases covering valid images, invalid images, edge cases, and error messages.

[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.19%	76.95%	📉 -0.24%
Statements	77.27%	77.05%	📉 -0.22%
Functions	77.17%	77.41%	📈 +0.24%
Branches	69.76%	69.21%	📉 -0.55%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	75.9% → 76.1% (+0.23%)	75.2% → 75.5% (+0.23%)
src/cli.ts	35.5% → 35.9% (+0.38%)	35.5% → 36.2% (+0.62%)

---

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

[Mossaka]

@copilot please bump up the test coverage: https://github.com/githubnext/gh-aw-firewall/actions/runs/21092298632/job/60683405279?pr=214

[Copilot]

@copilot please bump up the test coverage: https://github.com/githubnext/gh-aw-firewall/actions/runs/21092298632/job/60683405279?pr=214

Added more tests in c87c634:

• 7 new tests (574 total, up from 567)
• 21 comprehensive tests for validateAgentBaseImage() covering all regex patterns
• 2 additional docker-manager tests for agentBaseImage

Per-file coverage for modified files has increased (+0.38% for cli.ts, +0.23% for docker-manager.ts). The small overall regression (-0.24%) is due to the CLI integration code (lines 685-699) which uses process.exit() - this pattern cannot be unit tested without mocking infrastructure, similar to other CLI error paths in the codebase.

[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.88%	77.63%	📉 -0.25%
Statements	77.94%	77.71%	📉 -0.23%
Functions	77.29%	77.54%	📈 +0.25%
Branches	71.00%	70.44%	📉 -0.56%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	79.1% → 79.3% (+0.19%)	78.4% → 78.6% (+0.19%)
src/cli.ts	35.5% → 35.9% (+0.38%)	35.5% → 36.2% (+0.62%)

---

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

[github-actions]

Security Review: Base Image Validation Scope

I've reviewed this PR for security implications and found one concern regarding the base image validation allowlist:

⚠️ Security Issue: Overly Permissive Version Pattern

Location: src/cli.ts lines 111-119

Code:

const SAFE_BASE_IMAGE_PATTERNS = [
  // Official Ubuntu images (e.g., ubuntu:22.04, ubuntu:24.04)
  /^ubuntu:\d+\.\d+$/,
  // ... other patterns
];

Problem:
The regex ^\d+\.\d+$ accepts any two-digit version number, including:

• Very old, unsupported versions with known vulnerabilities (e.g., ubuntu:14.04, ubuntu:16.04)
• Future versions that don't exist yet (e.g., ubuntu:99.99)
• Non-LTS versions that receive shorter support windows

Risk:
Users could specify outdated Ubuntu versions with unpatched security vulnerabilities, undermining the firewall's security posture even though network filtering remains active.

Suggested Fix:
Restrict to currently supported Ubuntu LTS versions only:

const SAFE_BASE_IMAGE_PATTERNS = [
  // Official Ubuntu LTS images (20.04, 22.04, 24.04 only)
  /^ubuntu:(20\.04|22\.04|24\.04)$/,
  // catthehacker runner images
  /^ghcr\.io\/catthehacker\/ubuntu:(runner|full)-(20\.04|22\.04|24\.04)$/,
  // With SHA256 digest pinning
  /^ghcr\.io\/catthehacker\/ubuntu:(runner|full)-(20\.04|22\.04|24\.04)@sha256:[a-f0-9]{64}$/,
  /^ubuntu:(20\.04|22\.04|24\.04)@sha256:[a-f0-9]{64}$/,
];

This limits the allowlist to currently supported LTS versions (20.04 ESM through April 2025, 22.04 through April 2027, 24.04 through April 2029).

✅ Security Controls Verified

The following security controls remain intact and are not weakened by this PR:

• ✅ iptables rules in setup-iptables.sh unchanged
• ✅ Capability dropping (NET_ADMIN) in entrypoint.sh unchanged
• ✅ Squid proxy configuration unchanged
• ✅ Seccomp profile unchanged
• ✅ Host-level DOCKER-USER chain filtering unchanged
• ✅ Input validation added for base images (though scope needs tightening per above)

---

Recommendation: Please restrict the version pattern to supported LTS versions only before merging.

AI generated by Security Guard

[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]

Smoke Test Results (Run ID: 21269309104)

Last 2 Merged PRs:

• ci: use local awf build in smoke workflows #388: ci: use local awf build in smoke workflows
• chore: update gh aw #387: chore: update gh aw

✅ GitHub MCP: Retrieved recent PRs
✅ Playwright: Page title verified
✅ File Writing: Test file created
✅ Bash Tool: File read successful

Status: PASS

cc: @Mossaka

AI generated by Smoke Copilot

[github-actions]

Smoke Test Results (Claude)

Last 2 merged PRs:

• feat: add gh CLI, robust user creation, and act image support
• ci: use local awf build in smoke workflows

Test Results:

• ✅ GitHub MCP: Retrieved PRs successfully
• ✅ Playwright: Page title verified ("GitHub · Change is constant. GitHub keeps you ahead. · GitHub")
• ✅ File Write: Created /tmp/gh-aw/agent/smoke-test-claude-21269309152.txt
• ✅ Bash: File read back successfully

Overall: PASS

AI generated by Smoke Claude

[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.88%	77.63%	📉 -0.25%
Statements	77.94%	77.71%	📉 -0.23%
Functions	77.29%	77.54%	📈 +0.25%
Branches	71.00%	70.44%	📉 -0.56%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	79.1% → 79.3% (+0.19%)	78.4% → 78.6% (+0.19%)
src/cli.ts	35.5% → 35.9% (+0.38%)	35.5% → 36.2% (+0.62%)

---

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

[github-actions]

Smoke Test Results ✅

GitHub MCP: ✅

• ci: use local awf build in smoke workflows #388: ci: use local awf build in smoke workflows
• chore: update gh aw #387: chore: update gh aw

Playwright: ✅ Page title: "GitHub · Change is constant. GitHub keeps you ahead. · GitHub"
File Write: ✅ Created and verified smoke test file
Bash Tool: ✅ File read successful

Overall Status: PASS

cc @Mossaka

AI generated by Smoke Copilot

[github-actions]

Smoke Test Results - Claude Engine

Last 2 Merged PRs:

• ci: use local awf build in smoke workflows #388: ci: use local awf build in smoke workflows
• chore: update gh aw #387: chore: update gh aw

Test Results:

• ✅ GitHub MCP: Retrieved merged PRs
• ✅ Playwright: Page loaded (title contains "GitHub")
• ✅ File Writing: Test file created successfully
• ✅ Bash Tool: File verification successful

Overall Status: PASS

AI generated by Smoke Claude

[github-actions]

🧪 Smoke Test Results (Copilot)

Last 2 Merged PRs:

• feat: add configurable agent base image for GitHub Actions runner parity #214: feat: add configurable agent base image for GitHub Actions runner parity
• ci: use local awf build in smoke workflows #388: ci: use local awf build in smoke workflows

✅ GitHub MCP - Retrieved PR data
✅ Playwright - Page title contains "GitHub"
✅ File Writing - Created test file
✅ Bash Tool - Verified file contents

Status: PASS 🎉

cc: @Mossaka

AI generated by Smoke Copilot