How shemayon/adids-advanced-drone-intrusion-detection-system-2026 works
1. What this repository is
A-DIDS is a drone-network intrusion detection system organized as a flow-based ML pipeline: network packets are captured or loaded from datasets, reconstructed into bidirectional flows, converted into feature vectors, scored by trained models, and optionally exposed through a FastAPI service.
2. Core runtime path
The main production path is:
live packets or PCAP input → flow reconstruction → feature extraction → model inference → alert/API response.
The repo is built around keeping that path fast enough for real-time detection, with the trained model artifacts stored under models/ and reused by inference components.
3. Offline data engineering boundary
The offline side is centered on data_pipeline.py, pcap_processor.py, modules/data_loader.py, and the data/ tree.
This layer converts the ISOT Drone Dataset from raw captures and CSVs into model-ready features, likely normalizing the dataset into the 19-feature flow representation referenced in the README.
4. Training and evaluation boundary
Model lifecycle is handled by train_model.py, train_multiclass.py, benchmark_models.py, harden_model.py, and validation scripts such as validate_mixed_traffic.py.
This is where the XGBoost-based detector is trained, evaluated, benchmarked, and hardened, with outputs persisted as model.pkl, model_multiclass.pkl, and model_hardened.pkl.
5. Online inference boundary
inference_engine.py appears to be the central scoring layer used by both the API and live sniffer.
It is the boundary between feature vectors and predictions, returning class labels, confidence, and latency. This is the point where the system switches from packet handling to ML decisioning.
6. Live capture and streaming ingestion
live_sniffer.py is the real-time capture front end.
It uses Scapy-based packet sniffing to reconstruct bidirectional 5-tuple flows in a sliding window, then finalizes flows and immediately passes them into inference. This is the live operational entry point rather than a batch-processing tool.
7. API deployment boundary
api/app.py exposes the detector as a FastAPI microservice.
It accepts feature vectors over REST, loads the model artifact, and returns prediction metadata. This makes the IDS consumable by external systems such as a ground-control station, dashboard, or another orchestration service.
8. Auxiliary intelligence and defense modules
The modules/ directory contains specialized subsystems that extend the core detector:
xai_engine.py for explainability, zero_day_detector.py for anomaly detection, adversarial_engine.py for FGSM-style hardening, falcon_intelligence.py and tactical_briefing.py for decision summarization, and kinetic_response.py / ids_engine.py for mitigation-oriented orchestration.
These are best treated as decision-support and defense layers around the core classifier, not the core data path itself.
9. Simulation and coordination layers
Several modules model higher-level defense concepts rather than direct packet processing: rf_phy_layer.py, swarm_consensus.py, federated_swarm.py, temporal_memory.py, apex_engine.py, and vlm_verifier.py.
The README frames these as tactical or research extensions, so in an architecture diagram they belong in a separate optional layer above the detector, representing simulated physical-layer correlation, distributed alert consensus, or agent-style reasoning.
10. Configuration and shared assets
config/config.py centralizes settings, while models/ stores serialized artifacts and results/ plus RESULTS.md capture benchmark/stress-test outputs.
This creates a clear separation between code, configuration, trained artifacts, and evaluation evidence.
11. Validation and reproducibility tooling
The scripts/ folder contains end-to-end and phase checks (full_system_test.py, verify_phase1.py, verify_phase2.py, generate_demo_data.py), indicating the repo is designed to validate the whole pipeline rather than only train a model.
These scripts are the integration layer that exercises data prep, inference, and system behavior under mixed traffic.
12. Key architectural summary
If you draw the diagram, the most important boundaries are:
data ingestion/training on one side, real-time inference/API in the middle, and optional defense/explainability/coordination modules on the other.
The main dependencies are from raw traffic or dataset files into flow features, then into a trained XGBoost model, with FastAPI and live sniffer acting as the two operational front ends.
Main entry points: inference_engine.py Inference engine · data_pipeline.py Data pipeline · model.pkl Model artifacts · README.md A-DIDS
Components 22
Offline pipeline
Dataset ingestion, flow reconstruction, feature generation, and model training.
- Data loader · Loads and normalizes raw dataset inputs for downstream processing.
modules/data_loader.py - PCAP processor · Reconstructs packets into bidirectional flows from capture files.
pcap_processor.py - Data pipeline · Converts captures and CSV data into model-ready flow features.
data_pipeline.py - Train model · Trains the main detector model artifact.
train_model.py - Multiclass train · Trains the multiclass detector variant.
train_multiclass.py - Benchmarking · Compares trained models and records performance results.
benchmark_models.py - Hardening · Builds a hardened model variant for robustness.
harden_model.py
Online detection
Real-time capture, inference, and API serving.
- Inference engine · Turns feature vectors into predictions, confidence, and latency.
inference_engine.py - Live sniffer · Captures live traffic, assembles flows, and forwards them for scoring.
live_sniffer.py - FastAPI app · REST API for submitting features and returning predictions.
api/app.py
Defense layers
Explainability, anomaly detection, mitigation, and coordination extensions.
- Explainability · Explains model decisions for operators and analysts.
modules/xai_engine.py - Zero-day detect · Adds novelty or anomaly-based detection around the classifier.
modules/zero_day_detector.py - Adversarial defense · Supports FGSM-style hardening and robustness checks.
modules/adversarial_engine.py - IDS orchestration · Coordinates detection and mitigation-oriented subsystems.
modules/ids_engine.py - Kinetic response · Represents response actions after detection or escalation.
modules/kinetic_response.py - Swarm consensus · Models distributed alert agreement across agents or nodes.
modules/swarm_consensus.py - Falcon intel · Summarizes findings into operator-friendly intelligence.
modules/falcon_intelligence.py - Tactical briefing · Formats detection outputs into actionable briefings.
modules/tactical_briefing.py
Ops and assets
Configuration, artifacts, and validation tooling.
- A-DIDS · Drone-network intrusion detection system organized around a flow-based ML pipeline.
README.md - Config · Central configuration for runtime and pipeline behavior.
config/config.py - Model artifacts · Persisted detector artifacts used by inference and deployment.
models/model.pkl - Validation scripts · End-to-end and phase checks that exercise the full system.
scripts/full_system_test.py
Connections 24
- A-DIDS → Data pipeline: defines pipeline · Documents the offline flow from dataset to features.
- A-DIDS → Inference engine: centers on · Describes inference as the main scoring boundary.
- A-DIDS → FastAPI app: exposes via · Surfaces detection as a service.
- Data loader → PCAP processor: feeds · Loads raw dataset inputs for packet/flow processing.
- PCAP processor → Data pipeline: reconstructs flows · Transforms captures into bidirectional flow records.
- Data pipeline → Train model: produces features for · Generates model-ready vectors used in training.
- Data pipeline → Multiclass train: produces features for · Supports the multiclass training path.
- Train model → Model artifacts: writes · Persists the main trained model artifact.
- Multiclass train → Model artifacts: writes · Persists the multiclass model artifact.
- Hardening → Model artifacts: writes · Produces a hardened model artifact.
- Benchmarking → Model artifacts: evaluates · Compares stored model variants.
- Model artifacts → Inference engine: loads · Provides the serialized model used for scoring.
- Live sniffer → Inference engine: streams to · Sends reconstructed live flows for immediate scoring.
- FastAPI app → Inference engine: calls · Uses the inference layer to generate predictions.
- Inference engine → Explainability: explains with · Can pair predictions with explanations.
- Inference engine → Zero-day detect: augments with · Can be combined with anomaly detection.
- Adversarial defense → Hardening: supports · Provides robustness-oriented hardening logic.
- IDS orchestration → Kinetic response: triggers · Coordinates mitigation after detection.
- Swarm consensus → IDS orchestration: feeds consensus · Contributes distributed agreement signals.
- Falcon intel → Tactical briefing: summarizes into · Turns detector output into operator briefings.
- Validation scripts → Data pipeline: tests · Exercises dataset and feature preparation.
- Validation scripts → Inference engine: tests · Validates scoring behavior under mixed traffic.
- Config → Data pipeline: configures · Supplies shared runtime and pipeline settings.
- Config → FastAPI app: configures · Supplies API/runtime settings.