Quick Start

Prerequisites

ML Defender requires a Linux system with kernel 6.1.0+ for eBPF/XDP support.

System Requirements

OS: Debian 12 (Bookworm) or Ubuntu 22.04+
Kernel: 6.1.0 or higher (for eBPF)
RAM: 8GB minimum (16GB recommended)
CPU: 4+ cores
Network: Dual-NIC recommended for gateway mode

Install Dependencies

On Debian/Ubuntu, install all required packages:

sudo apt-get update
sudo apt-get install -y \
    build-essential cmake git \
    libzmq3-dev libprotobuf-dev protobuf-compiler \
    libjsoncpp-dev libssl-dev liblz4-dev \
    libgrpc++-dev libetcd-cpp-api-dev \
    ipset iptables python3 python3-pip

# Kernel headers for eBPF
sudo apt-get install -y linux-headers-$(uname -r)

For production deployments, see the Installation Guide for detailed dependency installation and optimization.

Clone Repository

Clone the ML Defender repository and navigate to the source directory:

git clone https://github.com/yourusername/ml-defender.git
cd ml-defender

Verify the repository structure:

ls -l
# You should see: ml-detector/, firewall-acl-agent/, etcd-server/, sniffer/, tools/

Build Components

Build all ML Defender components using the build script:

./scripts/build_all.sh

Or build components individually:

cd firewall-acl-agent/build
cmake .. && make -j4

cd ml-detector/build
cmake .. && make -j4

cd sniffer
make

cd etcd-server/build
cmake .. && make -j4

Verify binaries were created:

ls -lh firewall-acl-agent/build/firewall-acl-agent
ls -lh ml-detector/build/ml-detector
ls -lh sniffer/build/sniffer
ls -lh etcd-server/build/etcd_server

Start etcd Server

Start the etcd server for distributed configuration and crypto key exchange:

Terminal 1

cd etcd-server/build
sudo ./etcd_server

Expected output:

[INFO] etcd server started on port 2379
[INFO] Heartbeat monitoring enabled (30s interval)
[INFO] Auto-restart enabled for managed services

The etcd server manages crypto seed exchange between ml-detector and firewall-agent using ChaCha20-Poly1305 encryption.

Start Firewall Agent

In a new terminal, start the firewall ACL agent:

Terminal 2

cd firewall-acl-agent/build
sudo ./firewall-acl-agent -c ../config/firewall.json

Expected output:

[INFO] IPSet ml_defender_blacklist_test created (max: 1000 IPs)
[INFO] IPTables chain ML_DEFENDER_TEST initialized
[INFO] ZMQ subscriber connected to tcp://localhost:5572
[INFO] ChaCha20-Poly1305 decryption enabled
[INFO] Ready to process ML detection events

Verify System Status

Check that all components are running and communicating:

tail -f /vagrant/logs/lab/firewall-agent.log

sudo ipset list ml_defender_blacklist_test

sudo iptables -L ML_DEFENDER_TEST -v -n

pgrep -a firewall-acl-agent
pgrep -a etcd_server

Healthy system indicators:

✅ etcd_server running on port 2379
✅ firewall-acl-agent connected to ZMQ
✅ IPSet created with 0 blocked IPs initially
✅ No crypto/decompression errors in logs

Test with Synthetic Data

Generate synthetic attack events to test the complete pipeline:

Build Synthetic Injector

cd tools/build
cmake .. && make -j4

Inject Attack Events

Generate 1000 events at 50 events/second:

./synthetic_ml_output_injector 1000 50

Parameters:

1000: Total number of events to generate
50: Events per second rate

Monitor Blocking Activity

watch -n 1 'sudo ipset list ml_defender_blacklist_test | head -20'

tail -f /vagrant/logs/lab/firewall-metrics.json | jq '.'

cd /vagrant && bash scripts/monitor_lab.sh

Expected Results

After injecting synthetic events:

IPSet Statistics:
  - IPs blocked: 118 (initial batch)
  - Crypto errors: 0
  - Decompression errors: 0
  - Parse errors: 0

Performance:
  - Throughput: 42-364 events/sec (tested)
  - CPU usage: 41-54% (stress test)
  - Memory: 127MB RSS (under load)

IPSet has a capacity limit (default: 1000 IPs). When full, new IPs are queued. See Configuration for tuning.

Verify Detection Pipeline

Confirm the complete pipeline is operational:

Check Crypto Pipeline

Verify encrypted communication is working:

grep "crypto_errors" /vagrant/logs/lab/firewall-metrics.json
# Should show: "crypto_errors": 0

Verify Blocking Actions

Check that IPs are being added to IPSet:

sudo ipset list ml_defender_blacklist_test -t
# Shows: Number of entries: <count>

Test Actual Blocking

Verify IPTables DROP rules are active:

sudo iptables -L ML_DEFENDER_TEST -v -n --line-numbers

Expected output:

Chain ML_DEFENDER_TEST (1 references)
num   pkts bytes target     prot opt in     out     source               destination
1        0     0 DROP       all  --  *      *       0.0.0.0/0            0.0.0.0/0            match-set ml_defender_blacklist_test src

Stop Services

Gracefully shut down all components:

# Stop firewall agent
sudo pkill -9 firewall-acl-agent

# Stop etcd server
sudo pkill -9 etcd_server

# Clean up IPSet (optional)
sudo ipset destroy ml_defender_blacklist_test

# Clean up IPTables chain (optional)
sudo iptables -F ML_DEFENDER_TEST
sudo iptables -X ML_DEFENDER_TEST

Next Steps

Installation Guide

Detailed installation for production environments, Docker, and Vagrant

Configuration

Configure components, tune performance, and customize detection thresholds

Architecture

Understand the ML pipeline, crypto transport, and eBPF packet capture

Gateway Mode

Deploy dual-NIC gateway mode to protect entire networks

Troubleshooting

etcd server fails to start

Symptoms: Port 2379 already in useSolution:

# Check what's using port 2379
sudo lsof -i :2379

# Kill existing etcd process
sudo pkill etcd

# Restart
cd etcd-server/build && sudo ./etcd_server

Crypto errors in logs

Symptoms: crypto_errors > 0 in metricsSolution:

Verify etcd is running and accessible

Check crypto token path in configs:

grep "crypto_token_path" firewall-acl-agent/config/firewall.json

Restart both ml-detector and firewall-agent to re-sync keys

IPSet capacity errors

Symptoms: ipset_failures increasing rapidlySolution: Increase IPSet capacity in firewall.json:

"ipsets": {
  "blacklist": {
    "max_elements": 5000,  // Increase from 1000
    "timeout": 3600
  }
}

Then destroy and recreate:

sudo ipset destroy ml_defender_blacklist_test
# Restart firewall-acl-agent (auto-creates with new capacity)

No events being processed

Symptoms: Zero events in logsChecklist:

✅ etcd_server running?
✅ firewall-acl-agent connected to ZMQ?
✅ synthetic_ml_output_injector running?

✅ Check ZMQ endpoint matches:

grep endpoint firewall-acl-agent/config/firewall.json
# Should show: "endpoint": "tcp://localhost:5572"

Success! You now have ML Defender running with encrypted transport and autonomous blocking.

Overview

Getting Started

Components

Operations

Security

Quick Start

Prerequisites

System Requirements

Install Dependencies

Quick Start

Test with Synthetic Data

Build Synthetic Injector

Inject Attack Events

Monitor Blocking Activity

Expected Results

Verify Detection Pipeline

Stop Services

Next Steps

Installation Guide

Configuration

Architecture

Gateway Mode

Troubleshooting

​Prerequisites

​System Requirements

​Install Dependencies

​Quick Start

​Test with Synthetic Data

​Build Synthetic Injector

​Inject Attack Events

​Monitor Blocking Activity

​Expected Results

​Verify Detection Pipeline

​Stop Services

​Next Steps

Installation Guide

Configuration

Architecture

Gateway Mode

​Troubleshooting

Prerequisites

System Requirements

Install Dependencies

Quick Start

Test with Synthetic Data

Build Synthetic Injector

Inject Attack Events

Monitor Blocking Activity

Expected Results

Verify Detection Pipeline

Stop Services

Next Steps

Troubleshooting