From 461e2e63c6bd588785b2b30532af69c39fc567ac Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Fri, 13 Mar 2026 06:37:15 +0000 Subject: [PATCH] docs: fix iptables logging references after simplification - Correct LOG rule attribution from setup-iptables.sh to src/host-iptables.ts (FW_BLOCKED_UDP, FW_BLOCKED_OTHER are host-level DOCKER-USER chain rules) - Remove FW_DNS_QUERY section from logging quickref (prefix no longer exists) - Remove incorrect docker exec awf-agent dmesg commands (host kernel logs are not visible from inside the container) - Remove incorrect --log-uid reference (flag not used in host-iptables.ts) - Remove stale UID=0 field from iptables log example - Remove stale line number reference (src/squid-config.ts:40) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 15 ++++++--------- docs/logging_quickref.md | 28 ++++------------------------ docs/troubleshooting.md | 5 +---- 3 files changed, 11 insertions(+), 37 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2e74e23ec..a25b73234 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 %Hs %Ss:%Sh %ru "%{User-Agent}>h" ``` @@ -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 @@ -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`) diff --git a/docs/logging_quickref.md b/docs/logging_quickref.md index 7bc367dbb..bc4d003f9 100644 --- a/docs/logging_quickref.md +++ b/docs/logging_quickref.md @@ -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 @@ -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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 93a8dd1d6..6d41eb4d7 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -234,14 +234,11 @@ sudo cat /tmp/squid-logs-/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