Skip to content

Commit bca2ac2

Browse files
MossakaMossaka
authored
feat: add firewall debugging skill to agents (#180)
Signed-off-by: Jiaxiao (mossaka) Zhou <duibao55328@gmail.com>
1 parent 487b454 commit bca2ac2

2 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎.claude/skills/debug-firewall/SKILL.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
name: debug-firewall
3+
description: Debug the AWF firewall by inspecting Docker containers (awf-squid, awf-agent), analyzing Squid access logs, checking iptables rules, and troubleshooting blocked domains or network issues.
4+
allowed-tools: Bash(docker:*), Bash(sudo:*), Bash(dmesg:*), Bash(ls:*), Bash(cat:*), Read
5+
---
6+
7+
# AWF Firewall Debugging Skill
8+
9+
Use this skill when you need to debug the awf firewall, inspect container state, analyze traffic, or troubleshoot network issues.
10+
11+
## Container Information
12+
13+
**Container Names:**
14+
- `awf-squid` - Squid proxy container (IP: 172.30.0.10)
15+
- `awf-agent` - Agent execution container (IP: 172.30.0.20)
16+
17+
**Network:** `awf-net` (subnet: 172.30.0.0/24)
18+
19+
## Quick Debugging Commands
20+
21+
### Check Container Status
22+
```bash
23+
docker ps | grep awf
24+
docker inspect awf-squid --format='{{.State.Running}}'
25+
docker inspect awf-agent --format='{{.State.ExitCode}}'
26+
```
27+
28+
### View Logs
29+
```bash
30+
# Real-time logs
31+
docker logs -f awf-squid
32+
docker logs -f awf-agent
33+
34+
# Squid access log (traffic decisions)
35+
docker exec awf-squid cat /var/log/squid/access.log
36+
37+
# Docker wrapper log (intercepted docker commands)
38+
docker exec awf-agent cat /tmp/docker-wrapper.log
39+
```
40+
41+
### Analyze Traffic
42+
43+
**Squid Decision Codes:**
44+
- `TCP_TUNNEL:HIER_DIRECT` = ALLOWED (HTTPS)
45+
- `TCP_MISS:HIER_DIRECT` = ALLOWED (HTTP)
46+
- `TCP_DENIED:HIER_NONE` = BLOCKED
47+
48+
```bash
49+
# Find blocked domains
50+
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u
51+
52+
# Count blocked by domain
53+
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort | uniq -c | sort -rn
54+
55+
# All unique domains accessed
56+
docker exec awf-squid awk '{print $3}' /var/log/squid/access.log | sort -u
57+
58+
# Real-time blocked traffic
59+
docker exec awf-squid tail -f /var/log/squid/access.log | grep --line-buffered TCP_DENIED
60+
```
61+
62+
### Inspect iptables Rules
63+
```bash
64+
# Host-level firewall chain
65+
sudo iptables -t filter -L FW_WRAPPER -n -v
66+
67+
# Agent container NAT rules (redirects to Squid)
68+
docker exec awf-agent iptables -t nat -L OUTPUT -n -v
69+
70+
# Kernel logs for blocked non-HTTP traffic
71+
sudo dmesg | grep "FW_BLOCKED"
72+
```
73+
74+
### Network Inspection
75+
```bash
76+
# Network details
77+
docker network inspect awf-net
78+
79+
# Test Squid connectivity
80+
docker exec awf-agent nc -zv 172.30.0.10 3128
81+
82+
# DNS configuration
83+
docker exec awf-agent cat /etc/resolv.conf
84+
```
85+
86+
### View Configuration
87+
```bash
88+
# Squid config
89+
docker exec awf-squid cat /etc/squid/squid.conf
90+
91+
# Docker compose config
92+
cat /tmp/awf-*/docker-compose.yml
93+
94+
# Agent environment
95+
docker exec awf-agent env | grep -E "PROXY|DNS"
96+
```
97+
98+
## Preserved Logs Locations
99+
100+
**With `--keep-containers`:** Logs remain at work directory
101+
- Squid: `/tmp/awf-<timestamp>/squid-logs/access.log`
102+
- Agent: `/tmp/awf-<timestamp>/agent-logs/` (only if Copilot CLI logs exist)
103+
104+
**Normal execution:** Logs moved after cleanup
105+
- Squid: `/tmp/squid-logs-<timestamp>/access.log`
106+
- Agent: `/tmp/awf-agent-logs-<timestamp>/`
107+
108+
```bash
109+
# Find work directories and preserved logs
110+
ls -ldt /tmp/awf-* /tmp/squid-logs-* 2>/dev/null | head -5
111+
112+
# View Squid logs from work dir (with --keep-containers)
113+
sudo cat /tmp/awf-*/squid-logs/access.log
114+
115+
# View preserved Squid logs (after normal cleanup)
116+
sudo cat $(ls -t /tmp/squid-logs-*/access.log 2>/dev/null | head -1)
117+
```
118+
119+
## Debug Mode Workflow
120+
121+
```bash
122+
# 1. Run with debug logging and keep containers
123+
sudo awf \
124+
--allow-domains github.com \
125+
--log-level debug \
126+
--keep-containers \
127+
'curl https://api.github.com'
128+
129+
# 2. Inspect containers (they remain running)
130+
docker ps | grep awf
131+
docker logs awf-squid
132+
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log
133+
134+
# 3. Check iptables
135+
sudo iptables -t filter -L FW_WRAPPER -n
136+
137+
# 4. Manual cleanup when done
138+
docker rm -f awf-squid awf-agent
139+
docker network rm awf-net
140+
```
141+
142+
## Common Issues
143+
144+
**Domain blocked unexpectedly:**
145+
```bash
146+
# Check exact domain being requested
147+
docker exec awf-squid tail -20 /var/log/squid/access.log
148+
# Look at the Host header (3rd column) - may need subdomain allowlisted
149+
```
150+
151+
**DNS resolution failing:**
152+
```bash
153+
# Check DNS servers in use
154+
docker exec awf-agent cat /etc/resolv.conf
155+
# Verify DNS allowed in iptables
156+
sudo dmesg | grep "FW_DNS"
157+
```
158+
159+
**Docker-in-docker issues:**
160+
```bash
161+
# Check wrapper interception
162+
docker exec awf-agent cat /tmp/docker-wrapper.log
163+
# Verify network injection
164+
docker exec awf-agent grep "INJECTING" /tmp/docker-wrapper.log
165+
```
166+
167+
## Cleanup
168+
169+
```bash
170+
# Manual cleanup
171+
./scripts/ci/cleanup.sh
172+
173+
# Or individually:
174+
docker rm -f awf-squid awf-agent
175+
docker network rm awf-net
176+
sudo iptables -t filter -F FW_WRAPPER 2>/dev/null
177+
sudo iptables -t filter -X FW_WRAPPER 2>/dev/null
178+
rm -rf /tmp/awf-*
179+
```

‎.github/skills/debug-firewall‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.claude/skills/debug-firewall

0 commit comments

Comments
 (0)