AI-Powered Network Security with Explainable Machine Learning
A modern, Python-based Network Intrusion Detection System using Google's Agent2Agent (A2A) Protocol, ONNX ML models, and explainable AI for real-time threat detection and analysis.
- 🤖 Agent2Agent Protocol - Google's A2A protocol with gRPC streaming
- 🧠 ML-Powered Detection - ONNX models for attack classification
- 📊 Real-time Dashboard - Vue.js security monitoring UI
- 🔍 Explainable AI - Feature importance and human-readable explanations
- ⚙️ Configurable - YAML-based configuration (3-minute collection intervals)
- ☸️ Kubernetes Ready - Production-grade Helm charts
- 🔄 Auto-scaling - HPA for classifier and UI components
flowchart LR
subgraph Network
A[Traffic Capture]
end
subgraph Python Agents
B[nDPI Collector Agent]
C[Classifier Agent]
end
subgraph ML & AI
D[ONNX Models]
E[Anomaly Detection]
F[Risk Assessment]
end
subgraph UI
G[Vue.js Dashboard]
end
A -->|Packets| B
B -->|A2A Protocol/gRPC| C
C --> D
C --> E
C --> F
C -->|Results| G
- Python 3.11+ - For ML/AI agents
- uv - Python package manager (or pip)
- Docker - For containerization (optional)
- Kubernetes - For production deployment (optional)
- Node.js 18+ - For UI development (optional)
cd agent
uv pip install -e ".[all]"
# Or with pip
pip install -e ".[all]"# Test with synthetic data
python main.py --mode test# Process a PCAP file
python main.py --mode pcap --pcap /path/to/traffic.pcap --interval 60# Capture live traffic (requires sudo)
sudo python main.py --mode live --interface eth0 --interval 180Receives flows and performs ML-based classification:
# Run standalone classifier
python main.py --mode classifier --port 50051Features:
- ONNX model inference
- Attack type detection (DoS, DDoS, port scan, malware, etc.)
- Anomaly detection
- Risk scoring (0-1 scale)
- Explainable AI with feature importance
Collects network flows and sends to classifier:
# Run standalone collector
python main.py --mode collector --config config/ndpi_agent.yamlFeatures:
- Packet capture (live/PCAP)
- Flow aggregation (configurable interval)
- nDPI protocol detection
- Batch processing
- Alert management
Real-time threat visualization:
cd agent/ui
npm install
npm run devFeatures:
- Real-time threat alerts
- Risk level visualization
- Threat details and explanations
- Recommended actions
- Filter by risk level
Edit agent/config/ndpi_agent.yaml:
# Collection interval (seconds)
collection_interval: 180 # 3 minutes
# Classifier connection
classifier_agent_url: "grpc://localhost:50051"
# Alert settings
alert_threshold: 0.7 # Risk score 0-1
auto_block: false # Enable auto-blocking
# Processing
batch_size: 100
max_concurrent_requests: 10config/ndpi_agent.yaml- Default configurationconfig/ndpi_agent_live.yaml- Live capture optimizedconfig/ndpi_agent_pcap.yaml- PCAP analysis optimized
Build Docker images:
# Classifier
docker build -t jozoppi/classifier:1.0 -f docker/Dockerfile.classifier .
# Collector
docker build -t jozoppi/ndpi-collector:1.0 -f docker/Dockerfile.collector .
# UI
docker build -t jozoppi/nids-ui:1.0 -f docker/Dockerfile.ui ./agent/uiDeploy to Kubernetes cluster:
cd infra/helm
# Install Helm chart
helm install agentic-nids ./agentic-nids \
--namespace nids \
--create-namespace
# Access UI
kubectl get svc agentic-nids-ui -n nidsServices Exposed:
- UI: LoadBalancer on port 80 (accessible externally)
- Classifier: ClusterIP on port 50051 (internal gRPC)
- Collector: ClusterIP on port 8000 (internal)
See infra/README.md for detailed deployment guide.
- Agent README - Classifier agent details
- nDPI Integration - Collector agent guide
- Kubernetes Deployment - Infrastructure guide
# Quick synthetic test
python main.py --mode test
# PCAP analysis
python main.py --mode pcap --pcap data/sample.pcap
# Live capture
sudo python main.py --mode live --interface eth0- Network Monitoring - Real-time threat detection
- PCAP Analysis - Offline traffic analysis
- Security Research - ML model evaluation
- Incident Response - Threat investigation
- Compliance - Security audit trails
- DoS/DDoS - Denial of Service attacks
- Port Scan - Network reconnaissance
- Brute Force - Authentication attacks
- Malware - C&C communication
- Botnet - Coordinated attacks
- SQL Injection - Database attacks
- XSS - Cross-site scripting
- Probe - Network mapping
The system uses ONNX format for ML models:
- Primary Model: Flow classifier (XGBoost/Random Forest)
- Anomaly Detection: Isolation Forest
- Risk Assessment: Ensemble scoring
See agent/README.md for model training guide.
agentic-nids/
├── agent/ # Python agents
│ ├── classifier_agent_a2a.py # Classifier (A2A server)
│ ├── ndpi_collector_agent.py # Collector (A2A client)
│ ├── main.py # Main entry point
│ ├── config/ # YAML configurations
│ ├── ui/ # Vue.js dashboard
│ └── pyproject.toml # Python dependencies
├── infra/ # Kubernetes infrastructure
│ └── helm/ # Helm charts
│ └── agentic-nids/
├── nDPI/ # nDPI library (submodule)
└── README.md # This file
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
- Network policies enabled by default
- Pod security contexts
- Read-only root filesystem
- Non-root user execution
- TLS/HTTPS support
Research Papers:
- Large Language Models for Network Intrusion Detection
- Explainable Network Intrusion Detection using LLMs
- ChatIDS: Explainable Cybersecurity
Technologies:
MIT License - See LICENSE file for details
Agentic NIDS Team
- nDPI team for deep packet inspection library
- Google for A2A Protocol
- ONNX Runtime team
- Open source ML/security community
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Full Docs
Built with ❤️ for Network Security