docs: add PID tracking documentation for awf logs command

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

docs-site/src/content/docs/reference/cli-reference.md

@@ -197,6 +197,7 @@ awf logs [options]
 | `--format <format>` | string | `pretty` | Output format: `raw`, `pretty`, `json` |
 | `--source <path>` | string | auto | Path to log directory or `running` for live container |
 | `--list` | flag | `false` | List available log sources |
+| `--with-pid` | flag | `false` | Enrich logs with PID/process info (requires `-f`) |
 
 #### Output Formats
 
@@ -226,7 +227,35 @@ awf logs --source /tmp/squid-logs-1234567890
 
 # Stream from running container
 awf logs --source running -f
+
+# Follow logs with PID/process tracking
+awf logs -f --with-pid
+```
+
+#### PID Tracking
+
+The `--with-pid` flag enriches log entries with process information, correlating each network request to the specific process that made it.
+
+**Pretty format with PID:**
 ```
+[2024-01-01 12:00:00.123] CONNECT api.github.com → 200 (ALLOWED) [curl/7.88.1] <PID:12345 curl>
+```
+
+**JSON output includes additional fields:**
+```json
+{
+  "timestamp": 1703001234.567,
+  "domain": "github.com",
+  "pid": 12345,
+  "cmdline": "curl https://github.com",
+  "comm": "curl",
+  "inode": "123456"
+}
+```
+
+:::caution
+PID tracking only works with `-f` (follow mode) and requires Linux. Process information is only available while processes are running.
+:::
 
 :::note
 Log sources are auto-discovered in this order: running containers, `AWF_LOGS_DIR` environment variable, then preserved log directories in `/tmp/squid-logs-*`.

docs/logging_quickref.md

@@ -119,6 +119,44 @@ docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | \
   awk '{print $3}' | sort -u > blocked_domains.txt
 ```
 
+## PID/Process Tracking
+
+Correlate network requests with specific processes using `awf logs -f --with-pid`:
+
+```bash
+# Follow logs with PID tracking (real-time only)
+awf logs -f --with-pid
+
+# Example output:
+# [2024-01-01 12:00:00.123] CONNECT api.github.com → 200 (ALLOWED) [curl/7.88.1] <PID:12345 curl>
+```
+
+### JSON Output with PID
+
+```bash
+awf logs -f --with-pid --format json
+```
+
+**Additional fields when `--with-pid` is enabled:**
+| Field | Description |
+|-------|-------------|
+| `pid` | Process ID that made the request |
+| `cmdline` | Full command line of the process |
+| `comm` | Short command name (from `/proc/[pid]/comm`) |
+| `inode` | Socket inode for advanced correlation |
+
+### Limitations
+
+- **Real-time only**: PID tracking requires `-f` (follow mode)
+- **Linux only**: Requires `/proc` filesystem access
+- **Ephemeral**: Process must still be running; historical logs cannot be enriched
+
+### Use Cases
+
+- Identify which MCP server or tool made a specific request
+- Trace data exfiltration attempts to specific commands
+- Audit agent network behavior for compliance
+
 ## Decision Codes
 
 | Code | Meaning | Action |

docs/usage.md

@@ -519,6 +519,44 @@ awf logs -f --format json
 awf logs --source /tmp/squid-logs-1760987995318 --format raw
 ```
 
+### PID/Process Tracking
+
+Correlate network requests with the specific processes that made them using the `--with-pid` flag. This enables security auditing and forensic analysis.
+
+```bash
+# Follow logs with PID tracking (requires -f for real-time mode)
+awf logs -f --with-pid
+```
+
+**Pretty format output with PID:**
+```
+[2024-01-01 12:00:00.123] CONNECT api.github.com → 200 (ALLOWED) [curl/7.88.1] <PID:12345 curl>
+```
+
+**JSON format includes additional PID fields:**
+```json
+{
+  "timestamp": 1703001234.567,
+  "domain": "github.com",
+  "statusCode": 200,
+  "isAllowed": true,
+  "pid": 12345,
+  "cmdline": "curl https://github.com",
+  "comm": "curl",
+  "inode": "123456"
+}
+```
+
+**Important limitations:**
+- **Real-time only**: `--with-pid` requires `-f` (follow mode) because PID tracking reads the live `/proc` filesystem
+- **Linux only**: PID tracking requires the `/proc` filesystem (standard on Linux)
+- **Process must be running**: By the time historical logs are viewed, processes may have exited
+
+**Use cases:**
+- **Security auditing**: Identify which command or tool made each request
+- **Incident response**: Trace suspicious network activity to specific processes
+- **Debugging**: Correlate MCP server or tool behavior with network requests
+
 ### Troubleshooting with Logs
 
 **Find blocked requests:**