Problem
When AWF containers fail to start (e.g., Squid crashes on startup in DinD environments), there are no diagnostic logs — docker logs output, container exit codes, and mount info are never captured. Debugging requires customers to manually add diagnostic steps to their workflows.
Context
Original report: github/gh-aw#25548
A customer on ARC runners with DinD sidecars hit a Squid container crash (exit code 1) where the Squid access logs were empty (Squid never started). Diagnosing the root cause required multiple back-and-forth rounds.
Root Cause
The current cleanup lifecycle in src/cli.ts and src/docker-manager.ts calls docker compose down -v and removes the work directory, discarding all docker logs output and container state. There is no mechanism to capture container-level operational logs (stdout/stderr from entrypoints) before teardown.
The --keep-containers flag preserves containers but requires the user to know in advance they need it, and doesn't help for automated CI failures.
Proposed Solution
Add a --diagnostic-logs flag (off by default) to src/cli.ts that, when enabled and AWF exits with a non-zero code, collects container-level diagnostics before teardown:
- In
src/cli.ts: Add --diagnostic-logs option to the Commander program definition.
- In
src/docker-manager.ts: Add a collectDiagnostics(workDir, auditDir) function that runs:
docker logs awf-squid → diagnostics/squid-container.logdocker logs awf-agent → diagnostics/agent-container.logdocker logs awf-iptables-init → diagnostics/iptables-init.log (if exists)docker inspect --format '\{\{.State.ExitCode}}' awf-squid awf-agent → diagnostics/exit-codes.txtdocker inspect --format '\{\{json .Mounts}}' awf-agent → diagnostics/agent-mounts.json- Sanitized docker-compose.yml (strip env var values containing tokens/keys) →
diagnostics/docker-compose-sanitized.yml
- Call
collectDiagnostics in the error/signal cleanup path (src/cli.ts:95-103, 122-126) when --diagnostic-logs is set and exit code is non-zero.
- Write to
\$\{workDir}/diagnostics/ (preserved if --keep-containers, or moved alongside squid-logs).
- Security: Never collect raw env var values, full
docker inspect JSON, or /etc/shadow; sanitize the compose file before writing.
Generated by Firewall Issue Dispatcher · ● 2.1M · ◷
Problem
When AWF containers fail to start (e.g., Squid crashes on startup in DinD environments), there are no diagnostic logs —
docker logsoutput, container exit codes, and mount info are never captured. Debugging requires customers to manually add diagnostic steps to their workflows.Context
Original report: github/gh-aw#25548
A customer on ARC runners with DinD sidecars hit a Squid container crash (exit code 1) where the Squid access logs were empty (Squid never started). Diagnosing the root cause required multiple back-and-forth rounds.
Root Cause
The current cleanup lifecycle in
src/cli.tsandsrc/docker-manager.tscallsdocker compose down -vand removes the work directory, discarding alldocker logsoutput and container state. There is no mechanism to capture container-level operational logs (stdout/stderr from entrypoints) before teardown.The
--keep-containersflag preserves containers but requires the user to know in advance they need it, and doesn't help for automated CI failures.Proposed Solution
Add a
--diagnostic-logsflag (off by default) tosrc/cli.tsthat, when enabled and AWF exits with a non-zero code, collects container-level diagnostics before teardown:src/cli.ts: Add--diagnostic-logsoption to the Commander program definition.src/docker-manager.ts: Add acollectDiagnostics(workDir, auditDir)function that runs:docker logs awf-squid→diagnostics/squid-container.logdocker logs awf-agent→diagnostics/agent-container.logdocker logs awf-iptables-init→diagnostics/iptables-init.log(if exists)docker inspect --format '\{\{.State.ExitCode}}' awf-squid awf-agent→diagnostics/exit-codes.txtdocker inspect --format '\{\{json .Mounts}}' awf-agent→diagnostics/agent-mounts.jsondiagnostics/docker-compose-sanitized.ymlcollectDiagnosticsin the error/signal cleanup path (src/cli.ts:95-103, 122-126) when--diagnostic-logsis set and exit code is non-zero.\$\{workDir}/diagnostics/(preserved if--keep-containers, or moved alongside squid-logs).docker inspectJSON, or/etc/shadow; sanitize the compose file before writing.