Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 6 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -609,12 +609,12 @@ The firewall implements comprehensive logging at two levels:
### Key Files

- `src/squid-config.ts` - Generates Squid config with custom `firewall_detailed` logformat
- `containers/agent/setup-iptables.sh` - Configures iptables LOG rules for rejected traffic
- `src/host-iptables.ts` - Configures host-level iptables LOG rules for rejected traffic
- `src/squid-config.test.ts` - Tests for logging configuration

### Squid Log Format

Custom format defined in `src/squid-config.ts:40`:
Custom format defined in `src/squid-config.ts`:
```
logformat firewall_detailed %ts.%03tu %>a:%>p %{Host}>h %<a:%<p %rv %rm %>Hs %Ss:%Sh %ru "%{User-Agent}>h"
```
Expand All @@ -633,12 +633,10 @@ Captures:

### iptables Logging

Two LOG rules in `setup-iptables.sh`:
Two LOG rules in `src/host-iptables.ts` (applied on the host via the DOCKER-USER chain):

1. **Line 80** - `[FW_BLOCKED_UDP]` prefix for blocked UDP traffic
2. **Line 95** - `[FW_BLOCKED_OTHER]` prefix for other blocked traffic

Both use `--log-uid` flag to capture process UID.
1. `[FW_BLOCKED_UDP]` prefix for blocked UDP traffic
2. `[FW_BLOCKED_OTHER]` prefix for other blocked traffic

### Testing Logging

Expand All @@ -661,5 +659,4 @@ docker exec awf-squid cat /var/log/squid/access.log
- Squid logs use Unix timestamps (convert with `date -d @TIMESTAMP`)
- Decision codes: `TCP_DENIED:HIER_NONE` = blocked, `TCP_TUNNEL:HIER_DIRECT` = allowed
- SNI is captured via CONNECT method for HTTPS (no SSL inspection)
- iptables logs go to kernel buffer (view with `dmesg`)
- PID not directly available (UID can be used for correlation)
- iptables logs go to kernel buffer on the **host** (view with `sudo dmesg | grep FW_BLOCKED`)
28 changes: 4 additions & 24 deletions docs/logging_quickref.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,37 +98,17 @@ docker exec awf-squid grep "TCP_TUNNEL\|TCP_MISS" /var/log/squid/access.log
```

### Non-HTTP Traffic (iptables)

These logs are generated by host-level iptables rules in the DOCKER-USER chain and appear in the **host** kernel log, not inside the container:

```bash
# From host (requires sudo)
sudo dmesg | grep FW_BLOCKED

# From agent container
docker exec awf-agent dmesg | grep FW_BLOCKED

# Using journalctl (systemd)
sudo journalctl -k | grep FW_BLOCKED
```

### DNS Query Logging (Audit Trail)
```bash
# View all DNS queries made by containers
sudo dmesg | grep FW_DNS_QUERY

# Using journalctl (systemd)
sudo journalctl -k | grep FW_DNS_QUERY

# Real-time DNS query monitoring
sudo dmesg -w | grep FW_DNS_QUERY

# Count DNS queries by destination
sudo dmesg | grep FW_DNS_QUERY | grep -oP 'DST=\K[^ ]+' | sort | uniq -c | sort -rn

# Show DNS queries to specific resolver (e.g., 8.8.8.8)
sudo dmesg | grep FW_DNS_QUERY | grep 'DST=8.8.8.8'
```

**Note:** DNS queries are logged for audit trail purposes. This helps detect potential DNS tunneling attempts or unusual DNS activity. The log prefix `[FW_DNS_QUERY]` is used to identify DNS traffic.

## Log Format

### Squid Log Entry
Expand All @@ -153,7 +133,7 @@ timestamp client_ip:port domain dest_ip:port proto method status decision url us

**Example (blocked UDP):**
```
[1234567.890] [FW_BLOCKED_UDP] IN= OUT=eth0 SRC=172.20.98.20 DST=1.1.1.1 PROTO=UDP SPT=12345 DPT=443 UID=0
[1234567.890] [FW_BLOCKED_UDP] IN= OUT=eth0 SRC=172.20.98.20 DST=1.1.1.1 PROTO=UDP SPT=12345 DPT=443
```

## Common Queries
Expand Down
5 changes: 1 addition & 4 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,14 +234,11 @@ sudo cat /tmp/squid-logs-<timestamp>/access.log

### Checking iptables Logs

Blocked UDP and non-standard protocols are logged to kernel logs:
Blocked UDP and non-standard protocols are logged to the **host** kernel log via the DOCKER-USER chain:

```bash
# From host (requires sudo)
sudo dmesg | grep FW_BLOCKED

# From within container
docker exec awf-agent dmesg | grep FW_BLOCKED
```

## Network Issues
Expand Down
Loading