Skip to content

README.md

Latest commit

 

History

History
272 lines (232 loc) · 12.4 KB

README.md

File metadata and controls

272 lines (232 loc) · 12.4 KB
Raw

Edge IDPS: Architecture, Setup, and Roadmap

This repository contains a vertical slice of a high‑performance Intrusion Detection and Prevention System (IDPS) designed for the edge. It unifies kernel‑fast enforcement via XDP with user‑space detection and policy, and supports AF_XDP capture on Linux for low‑latency ingestion. It also includes a Windows‑friendly harness for validation without a Linux NIC.

Quick Start

Linux (Edge Node)

  1. Install and enable the agent:
git clone <your repo> IDPS
cd IDPS/edge/deploy
bash install_linux.sh
sudo nano /etc/default/edge-agent   # set NIC, PCAP, TOKEN, paths
sudo systemctl start edge-agent
sudo systemctl status edge-agent
  1. Optional: ONNX CPU inference on the node:
sudo nano /etc/default/edge-agent
# set:
# ONNXRUNTIME_SHARED_LIBRARY_PATH=/usr/lib/libonnxruntime.so
# MODEL_PATH=/opt/models/model.onnx
# CLASS_LABELS=Benign,DDOS attack-HOIC
sudo systemctl restart edge-agent

Raspberry Pi (Generic XDP + live capture)

git clone <your repo> IDPS
cd IDPS/edge/deploy
bash install_rpi.sh
sudo systemctl start edge-agent

Windows/Validation Harness

Run the Python pipeline harness to drive end‑to‑end decisions and call the agent remotely (e.g., over Tailscale):

python edge/tools/pipeline_harness.py --ids http://127.0.0.1:5000/predict --agent http://<agent-ip>:8080 --token <TOKEN> --duration 30

Packaging (Install on any node)

  • Build a portable tarball:
bash edge/deploy/package_node.sh
# output: dist/edge-agent-node.tar.gz
  • Install on a target node:
scp dist/edge-agent-node.tar.gz <user>@<node>:/tmp/
ssh <user>@<node> 'mkdir -p ~/edge && tar -xzf /tmp/edge-agent-node.tar.gz -C ~/edge && bash ~/edge/edge-agent/install.sh'
ssh <user>@<node> 'sudo nano /etc/default/edge-agent && sudo systemctl start edge-agent'

Container (Docker)

  • Build the agent image:
cd edge/agent
docker build -t edge-agent:latest .

Kubernetes (DaemonSet)

  • Deploy across a cluster as a privileged DaemonSet:
kubectl create ns edge-security
kubectl apply -f edge/deploy/k8s-daemonset.yaml -n edge-security

Notes:

  • Uses hostNetwork and privileged container to allow XDP attach.
  • Mounts /var/lib/idps on host for blocklist snapshot persistence.

Architecture Overview

The system separates the fast path (kernel enforcement and packet capture) from user‑space detection and policy. High‑confidence detections update a TTL blocklist stored in the kernel’s eBPF maps for O(1) drop decisions.

                +----------------------+           +---------------------+
Ingress NIC --->|  XDP Program         |--drop---->|  Kernel Drop (XDP) |
                |  (xdp_blocklist.c)   |           +---------------------+
                |    - Check blocklist |
                |    - Redirect to     |
                |      AF_XDP (if XSK) |
                +----------+-----------+
                           |
                           | redirect (XSKMAP)
                           v
                +----------------------+
                | AF_XDP Socket(s)     |  (Linux)         +-------------------+
                +----------+-----------+------------------>| PacketTap         |
                           |                               |  - Flow events    |
                           |                               |  - 5‑tuples       |
                           v                               +----+--------------+
                +----------------------+                        |
                | Flow Table           |<-----------------------+
                |  - IATs, sizes       |   events
                +----------+-----------+
                           |
                           v
                +----------------------+      +-----------------------------+
                | Feature Builder       |---->|  Model Inference            |
                |  (CICFlowMeter‑like)  |     |  - ONNX runtime (edge)      |
                +----------+-----------+     |  - or Python microservice   |
                           |                 +--------------+--------------+
                           v                                |
                +----------------------+                    |
                | Policy / Decision     |<------------------+
                |  - Thresholds, TTL    |
                |  - Evidence gating    |
                +----------+-----------+
                           |
                           v
                +----------------------+
                | Blocklist Update     |
                |  - eBPF maps via     |
                |    XdpLoader         |
                |  - Snapshot JSON     |
                +----------------------+

Data Flow

  • Capture: Packets are captured via AF_XDP (Linux) or pcap/live fallback; flow events are formed with timestamps, lengths, direction, and header sizes.
  • Features: CICFlowMeter‑style aggregations compute IAT stats, per‑direction sizes and counts, header metrics, and active/idle windows.
  • Inference: Local ONNX runtime (if configured) or a Python microservice evaluates features and returns class + confidence.
  • Policy: High‑precision classes with sufficient evidence cause the source IP to be added to the blocklist with a TTL.
  • Enforcement: XDP drops packets for any blocked source in O(1); otherwise redirects to AF_XDP or passes to the stack.
  • Persistence: Blocklist entries with TTLs are saved to a JSON snapshot and restored on agent startup.

Repository Structure

edge/
├── bpf/
│   └── xdp_blocklist.c          # Kernel XDP program: drop/redirect/pass with XSKMAP/qidconf_map
├── agent/
│   ├── cmd/
│   │   └── edge-agent/
│   │       └── main.go          # Entry: capture → features → inference → policy → blocklist updates; HTTP APIs
│   ├── core/
│   │   ├── xdp_loader.go        # Attach program, manage eBPF maps, AF_XDP registration, TTL snapshot
│   │   ├── packet_tap.go        # AF_XDP / pcap / live capture and emission of FlowEvent
│   │   ├── flow.go              # Flow table, state aggregation, TTL eviction
│   │   ├── features.go          # Feature vector builder (CICFlowMeter‑like)
│   │   ├── model_infer.go       # ONNX edge inference with microservice fallback
│   │   ├── *_test.go            # Unit tests for features, eviction, inference fallback
│   │   └── (others as added)
│   └── go.mod                   # Go module (includes onnxruntime_go)
├── ids_service/
│   ├── server.py                # Flask microservice for /predict (optional fallback)
│   └── test_server.py           # Unit tests for microservice behavior
├── tools/
│   ├── pipeline_harness.py      # Windows‑friendly harness to drive predictions and /block
│   └── attacks/
│       └── attack_runner.py     # Simple HOIC/UDP flood generators for validation
└── deploy/
    ├── install_linux.sh         # Linux install: build XDP object, build agent, systemd setup
    ├── edge-agent.service       # Systemd unit (memlock, restart)
    ├── edge-agent.env           # Linux env defaults
    ├── install_rpi.sh           # Raspberry Pi install (generic XDP + live capture)
    ├── edge-agent-rpi.env       # Pi env defaults (live:eth0)
    ├── package_node.sh          # Build portable tarball with agent + XDP + installer
    └── k8s-daemonset.yaml       # Kubernetes DaemonSet manifest (privileged, hostNetwork)
edge/agent/
├── Dockerfile                   # Container build for edge-agent + XDP object
documentation/
├── current-architecture.md      # Brief architecture notes
├── next-steps.md                # Planned work items
└── what-we-are-doing.md         # Goals and scope

Key Files

  • XDP Program: xdp_blocklist.c
  • Agent Entrypoint: main.go
  • XDP Loader + Maps + Snapshot: xdp_loader.go
  • Capture (AF_XDP/pcap/live): packet_tap.go
  • Flow State + Eviction: flow.go
  • Features: features.go
  • ONNX / Fallback Inference: model_infer.go
  • Harness: pipeline_harness.py
  • Microservice: server.py

HTTP APIs (Agent)

  • /block?ip=IP&ttl=SECONDS — Adds IP to blocklist; requires Authorization: Bearer if TOKEN is set.
  • /unblock?ip=IP — Removes IP from blocklist; requires token if set.
  • /stats — Returns drops, passes, and map size; requires token if set.
  • /metrics — Basic metrics; requires token if set.

Configuration

  • NIC: Interface name (e.g., ens18, eth0).
  • PCAP: One of:
    • afxdp:<nic> — AF_XDP capture (Linux, driver support required).
    • live:<nic> — Live capture fallback.
    • <path>.pcap — PCAP replay mode.
  • BLOCKLIST_SNAPSHOT: Path to JSON snapshot (e.g., /var/lib/idps/blocklist.json).
  • XDP_OBJ: Path to compiled XDP object (e.g., /usr/local/lib/idps/xdp_blocklist.o).
  • TOKEN: Bearer token to protect control endpoints.
  • ONNXRUNTIME_SHARED_LIBRARY_PATH (optional), MODEL_PATH (optional), CLASS_LABELS (optional).
  • FLOW_TTL: Seconds to retain inactive flows in the table (default 120).

What’s Implemented

  • Unified kernel enforcement and AF_XDP redirect:
    • XSKMAP and qidconf_map integrated in XDP program.
    • AF_XDP socket registration via loader; single attach point for drop/redirect/pass.
  • Blocklist persistence:
    • JSON snapshot of IPv4/IPv6 with TTLs; restored at agent startup.
    • Automatic saves on /block, /unblock, and policy‑driven decisions.
  • ONNX edge inference with remote fallback:
    • Uses yalue/onnxruntime_go on Linux/Windows when configured.
    • Falls back to Python microservice /predict when unavailable.
  • Flow table eviction:
    • TTL‑based eviction loop to prevent unbounded memory usage.
  • Tests and harness:
    • Go unit tests for features, eviction, and inference fallback.
    • Python tests for the microservice.
    • Pipeline harness to drive decisions from Windows/Linux.
  • Deployment scripts:
    • Linux and Raspberry Pi installers and systemd unit.

What’s Left / Roadmap

  • Multi‑queue AF_XDP:
    • Enumerate RX queues, register XSK per queue, and enable qidconf_map across queues.
  • QinQ VLAN support:
    • Extend XDP parser to handle stacked VLAN tags robustly.
  • Observability:
    • Prometheus metrics for latencies, decision‑to‑enforcement timing, AF_XDP ring stats.
    • Structured, rotated detection logs with IP/class/confidence/TTL.
  • Endpoint Hardening:
    • Add rate limiting, optional mTLS or IP allowlist on /block and /unblock.
  • Feature Parity:
    • Complete CICFlowMeter metrics: TCP flag distributions, subflows, payload‑aware metrics.
  • Control Plane:
    • Minimal orchestrator service: subscribe to events, apply global rules, call /block on nodes.
    • Optional Redis/Kafka integration for rule fan‑out beyond a single node.
  • Packaging:
    • Systemd hardening with capability bounding set and non‑root service user by default.
    • Debian package for agent + bpf object.

Validation Paths

  • Local tests:
    • Go: go test ./edge/agent/core/...
    • Python (IDS): python edge/ids_service/test_server.py
  • End‑to‑end:
    • Start the agent, run pipeline_harness.py to drive predictions and verify /stats and snapshot persistence.

Attack Replication (Lab Only)

  • HOIC‑style HTTP flood:
    • python3 edge/tools/attacks/attack_runner.py --mode hoic --host <agent-ip> --port 8080 --threads 100 --duration 60
  • UDP flood:
    • python3 edge/tools/attacks/attack_runner.py --mode udp --host <agent-ip> --port 53 --threads 200 --duration 60
  • Slowloris (Metasploit):
    • msfconsole -q -x "use auxiliary/dos/http/slowloris; set RHOST <agent-ip>; set RPORT 8080; run -j"
  • SYN flood (hping3):
    • sudo hping3 -S -p 8080 -c 1000 <agent-ip>

Always run in a closed lab or virtual network you control.

Siddhant Bhasin Production