awf-debug-tools

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

# Auto-discover logs and show all domains
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py
 
# Show only blocked domains
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only
 
# Filter by domain
python

Run Automated Diagnostics

Inspect Container Status

Test Domain Reachability

Common Workflows

Workflow 1: Debugging Blocked Requests

When a command fails due to blocked domain:

Workflow 2: Container Health Check

When containers aren't starting or behaving unexpectedly:

Workflow 3: Agent Automated Debugging

For agents to diagnose issues without human intervention:

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

Example 2: Diagnose Issues

Example 3: Test Domain

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:

Permission denied on logs:

No logs found:

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