PCAP & Packet Forensics

Flowtriq captures packet-level evidence for every detected incident. PCAP data provides the definitive proof of what happened, who sent it, and what protocols were used. This guide covers how capture works, how to access PCAP data, and how to configure capture settings.

How PCAP Capture Works

The Flowtriq agent maintains a continuous packet capture that operates in two phases:

Pre-Attack Ring Buffer

The agent keeps a rolling ring buffer of the most recent 1,000 packets at all times. When an incident is declared, this buffer is flushed and preserved, giving you packet-level evidence from before the attack peaked. This is critical because it shows the attack ramping up and captures the initial vectors.

Attack Capture

Once an incident is opened, the agent starts a dedicated capture session that records all traffic for the duration of the attack. When the incident resolves, the ring buffer data and the attack capture are merged into a single PCAP file attached to the incident record.

Capture Modes

The pcap_mode setting in /etc/ftagent/config.json controls how packets are captured. You choose the mode during ftagent --setup or by editing the config file directly.

Scapy Mode (Default)

Uses Python's scapy library to capture and inspect packets in real time. Every packet passes through a Python callback, enabling:

Real-time per-packet analysis: source IPs, TTL values, TCP flags, DNS queries
In-memory ring buffer for instant pre-attack context
Live IOC pattern matching against threat intelligence feeds
Protocol-level classification as traffic arrives

"pcap_mode": "scapy"

Scapy mode requires the scapy Python package and root access. CPU usage scales with PPS. On most servers (under 10K PPS normally) this is well under 10% of a core.

tcpdump Mode

Uses the native tcpdump binary for packet capture. tcpdump runs at kernel speed in C, so CPU overhead is near zero regardless of traffic volume.

Near-zero CPU usage at any PPS, even during large attacks
Full packet fidelity: every packet is captured to disk
Ring buffer rotates every 30 seconds, keeps the last 3 files
On incident: starts a dedicated capture, merges ring + attack data on resolution
Falls back to scapy automatically if tcpdump cannot be installed

"pcap_mode": "tcpdump"

When to Use Each Mode

Scenario	Recommended Mode
Most servers (under 10K PPS baseline)	scapy (default)
High-traffic servers (10K+ PPS baseline)	tcpdump
Game servers, CDN edges, high-throughput proxies	tcpdump
OVH, Hetzner, or servers with frequent volumetric attacks	tcpdump
Servers where you need live IOC pattern matching	scapy

Switching Modes

To switch capture mode, edit the config and restart the agent:

# Edit config
sudo nano /etc/ftagent/config.json
# Change "pcap_mode" to "tcpdump" or "scapy"

# Restart agent
sudo systemctl restart ftagent

The agent auto-installs tcpdump and mergecap (for PCAP merging) if they are not already present.

PCAP from the Incident Detail Page

When an incident has a PCAP file attached, the incident detail page shows:

Capture filename (e.g., incident-12345.pcap)
File size
Download button that generates a time-limited download token

Downloading PCAP Files

Open the incident detail page.
In the PCAP section, click Download PCAP.
A secure download token is generated (valid for 15 minutes).
The download starts automatically. The token can only be used once.

The download token is also logged in the audit trail for security tracking.

PCAP Viewer

The dashboard includes a built-in PCAP viewer that displays key information from the capture without requiring Wireshark or other external tools:

Source and destination IP distribution
Protocol breakdown (TCP, UDP, ICMP, other)
TCP flag analysis (SYN, ACK, RST, FIN ratios)
Top source IPs with packet counts and confidence scores
Geographic distribution of source addresses
IOC (Indicator of Compromise) matches found in the packet data

Retention

PCAP files are stored on the node where the agent runs, in the directory specified by pcap_dir (default: /var/lib/ftagent/pcaps). Retention is managed at the workspace level. PCAP capture records in the dashboard include an expires_at timestamp after which download tokens can no longer be generated.

Configuring PCAP Settings

All PCAP settings live in /etc/ftagent/config.json:

Setting	Default	Description
pcap_enabled	true	Enable or disable packet capture entirely
pcap_mode	"scapy"	Capture engine: "scapy" or "tcpdump"
pcap_dir	/var/lib/ftagent/pcaps	Directory where PCAP files are stored

{
  "pcap_enabled": true,
  "pcap_mode":    "scapy",
  "pcap_dir":     "/var/lib/ftagent/pcaps"
}

Limited Mode (No PCAP)

If you run the agent with --limited (no root access), PCAP capture is disabled entirely. Limited mode monitors traffic using /proc/net/dev counters only. You still get PPS/BPS metrics and incident detection, but without packet-level forensics.

FAQ

How large are PCAP files?

File size depends on the attack duration and volume. A 60-second attack at 50K PPS produces roughly 30-50 MB of PCAP data. The dashboard shows the file size on the incident detail page.

Can I open PCAP files in Wireshark?

Yes. Downloaded PCAP files are in standard pcap format and can be opened directly in Wireshark, tcpdump, tshark, or any other packet analysis tool.

What if PCAP capture is not working?

Check these common causes:

Agent is running in limited mode (no root access)
pcap_enabled is set to false in the config
The scapy Python package is not installed (for scapy mode)
tcpdump is not installed and auto-install failed (for tcpdump mode)
Insufficient disk space in the PCAP directory