Skip to main content

​
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.

​
Quick Start

1

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/
2

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
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
3

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.
4

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
5

Verify System Status

Check that all components are running and communicating:
tail -f /vagrant/logs/lab/firewall-agent.log
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'

​
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:
1

Check Crypto Pipeline

Verify encrypted communication is working:
grep "crypto_errors" /vagrant/logs/lab/firewall-metrics.json
# Should show: "crypto_errors": 0
2

Verify Blocking Actions

Check that IPs are being added to IPSet:
sudo ipset list ml_defender_blacklist_test -t
# Shows: Number of entries: <count>
3

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

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
Symptoms: crypto_errors > 0 in metricsSolution:
  1. Verify etcd is running and accessible
  2. Check crypto token path in configs: 
    grep "crypto_token_path" firewall-acl-agent/config/firewall.json
  3. Restart both ml-detector and firewall-agent to re-sync keys
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)
Symptoms: Zero events in logsChecklist:
  1. ✅ etcd_server running?
  2. ✅ firewall-acl-agent connected to ZMQ?
  3. ✅ synthetic_ml_output_injector running?
  4. ✅ 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us