ConnTracker

ConnTracker is an XDP/eBPF-based connection tracking and fingerprinting system that replicates Linux conntrack behavior in the kernel, exposes metrics via a user-space HTTP server, and enables TCP fingerprint collection for OS and stack identification.

Features

• eBPF/XDP Packet Processing: High-performance in-kernel connection tracking using a custom TCP state machine.
• Connection Control: Configurable threshold-based packet dropping with Count–Min Sketch tracking and Bloom filter banning.
• TCP Fingerprinting: Extracts TCP option sequences (MSS, SACK, TS, Window-Scale, etc.) into a BPF map for user-space analysis.
• User-Space Daemon: Loads YAML-based IP/MAC configuration, attaches the XDP program, and serves real-time statistics over HTTP (port 8888).
• Metrics & Logging: Per-CPU packet/byte counters, flow counts, and signature tracking via libbpf maps with console logs and HTTP endpoints.

Prerequisites

• Linux Kernel ≥ 5.6 with eBPF and XDP support
• clang/llvm, libbpf, bpftool, libelf, zlib development headers
• GNU make (or CMake)
• cyaml for YAML parsing in user-space
• argparse library for CLI options

 sudo apt install clang llvm libelf-dev libpcap-dev gcc-multilib build-essential linux-headers-$(uname -r) linux-tools-common linux-tools-generic tcpdump
 sudo apt install python3
 pip3 install -r lab_1/requirements.txt

Building

1. Clone the repository:

   git clone https://github.com/osmandagli/conntracker.git
   cd conntracker

2. Build eBPF objects and user-space binary:

make all

Configuration

1. Edit the config.yaml to list the IPs, TCP ports, and destination MAC addresses:

ips:
- ip: "192.168.1.10"
  port: 80
  mac: "aa:bb:cc:dd:ee:ff"

Running

1. Attach and run the XDP program via the user-space loader:

sudo ./conntrack \
  --c config.yaml \
  --t 50 \
  --iface1 <client1> \
  --iface2 <server> \
  --iface3 <client2> \
  --iface4 <client3> \
  --log_level 3

Once started, statistics appear on the console, and an HTTP endpoint is served at http://localhost:8888/ metrics.

HTTP API

GET /api/stats: Returns JSON with packet/byte rates and active connections.

GET /api/banned: Lists banned IPs.

DELETE /api/banned/ip: Removes the connection from the banned list.