Agent Setup

Requirements

Linux (any distro with /proc/net/dev)
Python 3.8 or higher
Root access (required for full mode - not needed with --limited)
Network interface with inbound traffic to monitor

Installation

pip install ftagent --break-system-packages
sudo ftagent --setup

Configuration file

The setup wizard creates /etc/ftagent/config.json (chmod 600):

{
  "api_key":           "ft_live_your_key_here",
  "node_uuid":         "your-node-uuid",
  "api_base":          "https://flowtriq.com/api/v1",
  "interface":         "auto",
  "pcap_enabled":      true,
  "pcap_mode":         "scapy",
  "pcap_dir":          "/var/lib/ftagent/pcaps",
  "dynamic_threshold": true,
  "auto_update":       true,
  "log_file":          "/var/log/ftagent.log",
  "log_level":         "INFO"
}

PCAP Capture Modes

The pcap_mode setting controls how the agent captures packets for analysis and incident forensics. You can 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 live analysis of source IPs, TTL values, TCP flags, IOC pattern matching, and protocol breakdown as traffic arrives.

Real-time per-packet analysis: source IPs, TTLs, protocol flags, DNS queries
In-memory ring buffer for instant pre-attack context when an incident opens
Live IOC pattern matching against threat intel feeds
Best for most servers with normal traffic levels

"pcap_mode": "scapy"

Scapy mode requires the scapy Python package (pip install scapy) 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. The agent auto-installs tcpdump via your system package manager if it is not present.

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
Best for high-traffic servers, game servers, CDN nodes, or servers that regularly handle 10K+ PPS

"pcap_mode": "tcpdump"

When to switch to tcpdump

Consider switching to tcpdump mode if:

Your server normally handles high traffic (10K+ PPS baseline)
You are seeing high CPU usage from the agent during attacks
You run game servers, CDN edge nodes, or high-throughput proxies
You operate on OVH, Hetzner, or other dedicated servers that see frequent volumetric attacks

To switch, edit /etc/ftagent/config.json, set "pcap_mode": "tcpdump", and restart:

sudo systemctl restart ftagent

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

Systemd service

The setup wizard installs a systemd service. Manage it with:

sudo systemctl enable  ftagent   # start on boot
sudo systemctl start   ftagent   # start now
sudo systemctl status  ftagent   # check status
sudo journalctl -u ftagent -f    # tail logs

Flags

--setup: Interactive setup wizard
--test: Trigger a synthetic detection event
--update: Check for agent updates and install interactively
--no-update-check: Skip the automatic update check on startup
--install-service: Install the systemd service unit
--config PATH: Use a custom config file path (default: /etc/ftagent/config.json)
--version: Print the agent version and exit
--limited: Run without root: no packet capture, PCAP, IOC matching, or TCP flag analysis

Auto-Updates

The agent checks for updates once per day on startup (non-blocking, logs only). To update interactively:

sudo ftagent --update

This checks GitHub for the latest release, shows the version diff, and prompts to install. Handles --break-system-packages automatically for system Python (Debian 12+, Ubuntu 23.04+).

To disable the startup check, pass --no-update-check or set "auto_update": false in the config.

Limited mode

By default the agent requires root for packet capture (tcpdump or scapy). If you cannot grant root, use --limited to run the agent without any root-level functionality.

pip install ftagent --break-system-packages
ftagent --setup --limited

Limited mode monitors traffic using /proc/net/dev counters only. It still reports PPS/BPS metrics, heartbeats, and triggers incident detection via baseline deviation - but the following features are unavailable:

PCAP capture and download
Protocol-level classification (TCP flags, UDP vs TCP breakdown)
IOC pattern matching
Source IP analysis and geo-distribution

The --limited flag is stored in the config file so you only need to pass it once during setup. The systemd service does not need root when running in limited mode:

systemctl --user enable  ftagent   # no sudo required
systemctl --user start   ftagent
systemctl --user status  ftagent

Limited mode does not use tcpdump or scapy at runtime. The agent automatically skips all packet capture features when running with --limited.