AWF Debug Tools

A collection of practical Python scripts that help agents efficiently debug and operate the awf firewall. These scripts reduce verbose Docker/log output by 80%+ and provide actionable insights instead of raw data dumps.

Why These Scripts?

Problem: Docker commands and log files are verbose and hard for agents to parse. Diagnosing issues requires 10+ manual commands and produces noisy output that wastes tokens.

Solution: One script replaces 5-10 manual commands with clean, filtered output optimized for agent consumption. All scripts support JSON format for easy parsing.

Available Scripts

All scripts are located in .claude/skills/awf-debug-tools/scripts/:

1. parse-squid-logs.py - Parse Squid logs and extract blocked domains with counts
2. diagnose-awf.py - Run automated diagnostic checks on container health and configuration
3. inspect-containers.py - Show concise container status without verbose docker output
4. test-domain.py - Test if specific domain is reachable through the firewall

Quick Start

Parse Logs to Find Blocked Domains

bash
1# Auto-discover logs and show all domains
2python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py
3
4# Show only blocked domains
5python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only
6
7# Filter by domain
8python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --domain github.com
9
10# Show top 10, JSON output
11python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --top 10 --format json

Run Automated Diagnostics

bash
1# Quick health check
2python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py
3
4# Detailed output
5python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --verbose
6
7# JSON output for agent parsing
8python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --format json

Inspect Container Status

bash
1# Inspect all containers
2python .claude/skills/awf-debug-tools/scripts/inspect-containers.py
3
4# Specific container only
5python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --container awf-squid
6
7# Show only logs
8python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --logs-only
9
10# JSON output
11python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --format json

Test Domain Reachability

bash
1# Test if domain is allowed
2python .claude/skills/awf-debug-tools/scripts/test-domain.py github.com
3
4# Test blocked domain with fix suggestion
5python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix
6
7# Check allowlist only (no log lookup)
8python .claude/skills/awf-debug-tools/scripts/test-domain.py api.github.com --check-allowlist
9
10# JSON output
11python .claude/skills/awf-debug-tools/scripts/test-domain.py github.com --format json

Common Workflows

Workflow 1: Debugging Blocked Requests

When a command fails due to blocked domain:

bash
1# 1. Run diagnostics to check overall health
2python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py
3
4# 2. Parse logs to find which domains were blocked
5python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only
6
7# 3. Test specific domain and get fix suggestion
8python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix
9
10# 4. Apply the suggested fix
11sudo awf --allow-domains github.com,npmjs.org 'your-command'

Workflow 2: Container Health Check

When containers aren't starting or behaving unexpectedly:

bash
1# 1. Check container status and recent logs
2python .claude/skills/awf-debug-tools/scripts/inspect-containers.py
3
4# 2. Run full diagnostics
5python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --verbose
6
7# 3. If issues found, check Squid logs for errors
8python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

Workflow 3: Agent Automated Debugging

For agents to diagnose issues without human intervention:

bash
1# Run all checks with JSON output
2python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --format json | jq .
3
4# Parse blocked domains
5python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only --format json | jq .
6
7# Test each blocked domain
8python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --format json | jq .

Output Formats

All scripts support two output formats:

• table/text (default): Human-readable format with clear sections and alignment
• json: Machine-readable format optimized for agent parsing

Use --format json to get structured output that's easy to parse programmatically.

Exit Codes

All scripts use consistent exit codes:

• 0: Success (no issues found, domain allowed, etc.)
• 1: Issues found (blocked domains, failed checks, domain blocked)
• 2: Error (missing logs, invalid arguments, etc.)

No Dependencies

All scripts use Python 3.8+ stdlib only. No pip install required. They work out of the box on any system with Python 3.8+.

Script Reference

parse-squid-logs.py

Purpose: Extract blocked domains from Squid logs with counts and statistics.

Key Options:

• --blocked-only - Show only blocked domains
• --domain DOMAIN - Filter by specific domain
• --top N - Show top N domains by request count
• --format {table,json} - Output format

Auto-discovers logs from running containers, preserved logs, or work directories.

diagnose-awf.py

Purpose: Run automated diagnostic checks and report issues with fixes.

Checks:

• Container status (running/stopped/missing)
• Container health (Squid healthcheck)
• Network connectivity (Squid reachable from agent)
• DNS configuration
• Squid config validation
• Common issues (port conflicts, orphaned containers)

Key Options:

• --verbose - Show detailed check output
• --format {text,json} - Output format

inspect-containers.py

Purpose: Show concise container status without verbose docker output.

Shows:

• Container status and exit codes
• IP addresses and network info
• Health check status
• Top 5 processes
• Recent logs (last 5 lines)

Key Options:

• --container NAME - Inspect specific container only
• --logs-only - Show only recent logs
• --tail N - Number of log lines (default: 5)
• --format {text,json} - Output format

test-domain.py

Purpose: Test if domain is reachable through the firewall.

Checks:

• If domain is in Squid allowlist
• If domain appears in recent Squid logs
• Whether requests were allowed or blocked

Key Options:

• --check-allowlist - Only check allowlist, don't check logs
• --suggest-fix - Show suggested --allow-domains flag
• --format {text,json} - Output format

Integration with Existing Skills

• For manual debugging commands, see the debug-firewall skill
• For MCP Gateway integration, see the awf-mcp-gateway skill
• For general troubleshooting, see docs/troubleshooting.md

Performance

All scripts are designed for fast execution:

• parse-squid-logs.py: <2 seconds for typical log files
• diagnose-awf.py: <3 seconds for all checks
• inspect-containers.py: <2 seconds for both containers
• test-domain.py: <1 second for domain check

Examples

Example 1: Find Blocked Domains

bash
1$ python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only
2
3Blocked Domains (sorted by count):
4
5  Domain                  Blocked  Allowed  Total
6  =================================================
7  registry.npmjs.org      45       0        45
8  example.com             12       0        12
9
10Total requests: 1234
11Blocked: 57 (4.6%)
12Allowed: 1177 (95.4%)

Example 2: Diagnose Issues

bash
1$ python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py
2
3AWF Diagnostic Report
4========================================
5[✓] Containers: awf-squid (running), awf-agent (exited:0)
6[✓] Health: Squid healthy
7[✓] Network: awf-net exists ([{Subnet:172.30.0.0/24 Gateway:172.30.0.1}])
8[✓] Connectivity: Squid reachable on 172.30.0.10:3128
9[✓] DNS: DNS servers: 127.0.0.11, 8.8.8.8, 8.8.4.4
10[✓] Config: 3 domains in allowlist (github.com, .github.com, api.github.com)
11
12Summary: All checks passed ✓

Example 3: Test Domain

bash
1$ python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix
2
3Testing: npmjs.org
4
5[✗] Allowlist check: Not in allowlist
6[✗] Reachability: Blocked (403 TCP_DENIED:HIER_NONE)
7[✗] Status: BLOCKED
8
9Suggested fix:
10  awf --allow-domains github.com,npmjs.org 'your-command'

Tips for Agents

1. Use JSON output for easy parsing: --format json | jq .
2. Chain commands to get complete picture: diagnose → parse logs → test domain
3. Check exit codes to determine if action needed (0 = ok, 1 = issues)
4. Use --suggest-fix to get ready-to-use awf commands
5. Scripts auto-discover logs - no need to specify paths in most cases

Troubleshooting

Script not found:

bash
1# Use absolute path
2python /home/mossaka/developer/gh-aw-repos/gh-aw-firewall/.claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

Permission denied on logs:

bash
1# Squid logs require sudo to read
2sudo python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --log-file /tmp/squid-logs-*/access.log

No logs found:

bash
1# Run awf first to generate logs
2sudo awf --allow-domains github.com 'curl https://api.github.com'
3
4# Then parse
5python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

Future Enhancements

Planned scripts for future versions:

• analyze-traffic.py - Analyze traffic patterns over time
• generate-allowlist.py - Auto-generate allowlist from logs
• cleanup-awf.py - Clean up orphaned resources
• benchmark-awf.py - Performance testing utilities