🔍 BGP Anomaly Detector

AI-Powered Border Gateway Protocol Anomaly Detection — Identifying malicious BGP route changes using Isolation Forest, rule-based overrides, and Claude AI explanations.

---

📌 Overview

BGP (Border Gateway Protocol) is the routing protocol that holds the internet together — and it's notoriously vulnerable to hijacks, route leaks, and misconfiguration. This project detects anomalous BGP updates using a combination of:

• 🤖 Isolation Forest — unsupervised ML anomaly detection
• 📏 Rule-based overrides — high-confidence signal detection
• 🧠 Claude AI — natural language explanations of detected anomalies
• 📊 Streamlit Dashboard — real-time visualisation

---

🎯 Detected Anomaly Types

Anomaly	Description
hijack	Unauthorised AS originating a prefix it doesn't own
route_leak	Routes propagated beyond intended scope
moas	Multiple Origin AS — same prefix announced by multiple ASes
deaggregation	Prefix split into smaller subnets to manipulate routing

---

🏗️ Architecture

┌─────────────────────────────────────┐
│         BGP UPDATE FEED             │
│   (Simulated / RIPE Stat API)       │
└──────────────┬──────────────────────┘
               │
       ┌───────▼──────────────┐
       │   FEATURE EXTRACTOR  │
       │  • AS path length    │
       │  • Origin AS         │
       │  • Prefix length     │
       │  • MOAS detection    │
       │  • Path anomalies    │
       └───────┬──────────────┘
               │
       ┌───────▼──────────────┐
       │   DETECTION ENGINE   │
       │  Isolation Forest    │
       │  + Rule Overrides    │
       │  Auto-calibrated     │
       │  threshold (2nd %ile)│
       └───────┬──────────────┘
               │
       ┌───────▼──────────────┐
       │    CLAUDE AI LAYER   │
       │  Natural language    │
       │  explanations with   │
       │  prompt caching      │
       └───────┬──────────────┘
               │
       ┌───────▼──────────────┐
       │  STREAMLIT DASHBOARD │
       │  Real-time alerts    │
       └──────────────────────┘

---

📊 Performance

Metric	Value
Average F1 Score	~87%
Attack Recall	96–100% across seeds
Threshold calibration	Auto (2nd percentile of training scores)

---

🛠️ Tech Stack

Component	Technology
ML Model	scikit-learn Isolation Forest
Feature Engineering	pandas, numpy
AI Explanations	anthropic (claude-sonnet-4-6) with prompt caching
Dashboard	streamlit, plotly
Real Data	RIPE Stat API

---

📁 Project Structure

bgp_anomaly_detector/
├── data/
│   ├── simulator.py      # BGP update simulator with injected anomalies
│   └── fetcher.py        # RIPE Stat API integration for real BGP data
├── features/
│   └── extractor.py      # Stateful FeatureExtractor (ML + rule features)
├── detection/
│   └── anomaly.py        # Isolation Forest + rule-based overrides
├── llm/
│   └── explainer.py      # Claude API with prompt caching + fallback
├── app.py                # Streamlit real-time dashboard
├── main.py               # CLI entry point
├── config.py             # Shared configuration
├── requirements.txt
└── .env.example          # API key template

---

🚀 Getting Started

1. Clone & Install

git clone https://github.com/singhananya0043/bgp_anomaly_detector.git
cd bgp_anomaly_detector
pip install -r requirements.txt

2. Configure API Key (optional)

cp .env.example .env
# Add your Anthropic API key to .env:
# ANTHROPIC_API_KEY=sk-ant-...

3. Run

# CLI — simulated BGP data
python -X utf8 main.py

# Launch Streamlit dashboard
python -X utf8 main.py --dashboard

# Use real RIPE Stat API data
python -X utf8 main.py --real

---

🔑 Key Design Decisions

• Separate ML features (stable, non-temporal) from rule-based features (temporal) to avoid train/test score distribution drift
• Auto-calibrate IF threshold to 2nd percentile of training scores per run
• Rule-based overrides for high-confidence signals: origin_mismatch, new_moas_origin, path_loop, path_len_over_8, private_origin_as
• Prompt caching on Claude system prompt to reduce API costs on repeated calls

---

🔮 Roadmap

• Live BGP stream integration (BGPStream / RouteViews)
• LSTM-based sequence anomaly detection
• Historical anomaly timeline view
• Slack / email alerting for critical hijacks
• Docker containerisation

---

📄 License

This project is licensed under the MIT License.

---

Built with 🔍 and 🤖 by singhananya0043