From 461e2e63c6bd588785b2b30532af69c39fc567ac Mon Sep 17 00:00:00 2001
From: GitHub Copilot <copilot@github.com>
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 %<a:%<p %rv %rm %>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-<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
