🕯️ BeaconSentry

Build Your Own AI-Driven Network C2 Beaconing & Exfiltration Detector — From Scratch

No signatures. No rulesets. Just math, statistics, and lightweight ML watching your wire.

Every rule-based IDS has a blind spot: the attack it's never seen before. BeaconSentry doesn't look for known-bad — it learns what normal looks like, and tells you the moment your network stops behaving like itself.

---

⚡ 3-Second Pitch

 $ python3 core/entropy_engine.py

 === Simulated DNS-tunneling burst (25 queries, same source) ===
   [LOW     ] f8a91cbe7710eae1998ecf8427e.exfil-c2.attacker-do  score= 15  ttp=['T1071.004']
   [MEDIUM  ] 6a1d9f0033bb887ceeaa1029fd8801.exfil-c2.attacker  score= 37  ttp=['T1071.004']
   [HIGH    ] 6a1d9f0033bb887ceeaa1029fd8801.exfil-c2.attacker  score= 62  ttp=['T1071.004','T1048.003']

That's real output, from real math, against a simulated exfiltration channel — zero signatures, zero YARA rules, zero threat-intel feed. Just Shannon entropy, adaptive baselining, and frequency analysis, escalating severity in real time as the pattern reveals itself.

This repo is the full masterclass behind that output — you build every module yourself, module by module, understanding the why behind every line.

---

🧠 Why This Exists

Signature-based tools (Suricata rulesets, YARA, static IOC feeds) are excellent at catching what's already been caught before. They are structurally blind to:

• Novel C2 frameworks using never-before-seen domains
• DNS tunneling tools that rotate domains faster than threat intel updates
• Beacon jitter specifically engineered to defeat fixed-interval detection
• "Living off the land" exfiltration over protocols nobody's writing rules for yet

BeaconSentry flips the model. Instead of asking "have I seen this exact bad thing before?", every module asks "does this behave like anything a human or a normal application would do?" — using the same class of math threat hunters use by hand, automated and run in real time.

---

🗺️ Architecture

flowchart LR
    A[("🌐 Live NIC Traffic")] --> B["BPF Filter\nudp/53, tcp/80"]
    B --> C["CaptureThread\nscapy.sniff()"]
    C --> D[("Bounded Raw\nPacket Queue\ndrop-oldest")]
    D --> E1["ParserWorker #1"]
    D --> E2["ParserWorker #2"]
    D --> E3["ParserWorker #N"]
    E1 & E2 & E3 --> F{{"Event Router"}}
    F -->|DNS Query| G["🧮 Shannon Entropy Engine"]
    F -->|Connection Timing| H["📈 Jitter & Beaconing Analyzer"]
    F -->|Feature Vector| I["🌲 Isolation Forest"]
    G --> J["MITRE ATT&CK Mapper"]
    H --> J
    I --> J
    J --> K["🎨 Rich CLI Dashboard"]
    J --> L[("alerts.jsonl")]

Loading

Design principle: the capture thread is kept microsecond-thin (copy bytes, timestamp, queue — nothing else). All parsing, math, and ML happen on worker threads, so a slow detector can never cause the NIC to drop packets. See core/packet_capture.py for the full rationale.

---

📊 Feature Matrix

Module	Technique	Detects	MITRE ATT&CK	Status
Entropy Engine	Shannon entropy + adaptive per-domain baseline + char-class heuristics	DNS tunneling, data exfil over DNS	T1071.004 T1048.003 T1568.002	✅ Phase 1 — this repo
Packet Capture Core	Threaded scapy sniff + BPF filter + async bridge	Live DNS/HTTP parsing substrate for every module above	—	✅ Phase 1 — this repo
Jitter & Beaconing Analyzer	Interval variance, autocorrelation, coefficient-of-variation scoring	C2 beaconing, including randomized/jittered sleep timers	T1071 T1029 T1571	🔜 Phase 2
Isolation Forest	scikit-learn unsupervised anomaly detection over flow features	Anomalous outbound flows, low-and-slow C2, novel behavior	T1071 T1567	🔜 Phase 3
Rich CLI Dashboard	Live terminal UI: sparkgraphs, alert feed, severity coloring	Human triage layer for everything above	—	🔜 Phase 4
MITRE Mapper & Reporter	TTP correlation + JSONL/Markdown incident export	Attack-narrative reconstruction across modules	—	🔜 Phase 5

---

🎨 Where This Is Headed: The Dashboard (Phase 4 Preview)

┌─ BeaconSentry // Live Behavioral Threat Detector ──────────────────────────────┐
│ uptime 00:42:17     pkts/s ▂▃▅▇█▆▄▂▁  1,204/s      mode: BEHAVIORAL (no sigs)│
├────────────────────────────────┬─────────────────────────────────────────────┤
│ 🧮 ENTROPY RADAR                │ 🚨 LIVE ALERT FEED                          │
│                                 │                                             │
│  attacker-domain.net    4.02 ▇▇│ [CRITICAL] DNS Tunneling    src 10.0.0.99   │
│  cdn.jsdelivr.net       2.11 ▂▂│   → exfil-c2.attacker-domain.net             │
│  google.com             1.84 ▁▁│   T1071.004 · T1048.003 · score 87/100      │
│                                 │                                             │
│                                 │ [HIGH]     Beacon Detected  src 10.0.0.44   │
│                                 │   → 45.33.x.x:443   interval 30s ±2s        │
│                                 │   T1071 · T1571 · jitter-score 0.94         │
├────────────────────────────────┴─────────────────────────────────────────────┤
│ 🌲 ISOLATION FOREST     anomaly score ▓▓▓▓▓▓▓░░░ 0.71     flows/min: 3,410    │
└────────────────────────────────────────────────────────────────────────────┘

(Mockup — built with the rich library in Phase 4. Star ⭐ / watch 👁️ the repo to get notified when it ships.)

---

🧩 MITRE ATT&CK Coverage

TTP	Technique	Detected By
T1071.004	Application Layer Protocol: DNS	Entropy Engine
T1048.003	Exfiltration Over Alternative Protocol (Non-C2, DNS)	Entropy Engine (frequency + entropy)
T1568.002	Dynamic Resolution: Domain Generation Algorithms	Entropy Engine (baseline deviation)
T1071	Application Layer Protocol (generic C2)	Beaconing Analyzer (Phase 2)
T1029	Scheduled Transfer	Beaconing Analyzer (Phase 2)
T1571	Non-Standard Port	Beaconing Analyzer (Phase 2)
T1567	Exfiltration Over Web Service	Isolation Forest (Phase 3)

---

🛠️ The Build-It-Yourself Roadmap

Each phase is a self-contained masterclass: read the module, understand the math, run the demo, then extend it.

• Phase 1 — Foundations (this repo, right now)
  • core/entropy_engine.py — Shannon entropy, adaptive baselining, composite scoring
  • core/packet_capture.py — threaded capture core, BPF filtering, async bridge
• Phase 2 — Time-Series Beaconing Detection
  • Interval extraction per source/destination pair
  • Coefficient-of-variation + autocorrelation to catch jittered beacons
• Phase 3 — Unsupervised Anomaly Detection
  • Flow feature engineering (byte ratios, packet timing, session duration)
  • IsolationForest training + live scoring pipeline
• Phase 4 — The Rich Dashboard
  • Live sparkgraphs, severity-colored alert feed, keyboard-driven triage
• Phase 5 — MITRE Mapping & Incident Export
  • Cross-module TTP correlation into a single attack narrative
  • JSONL + Markdown incident report generation

---

🚀 Quickstart

Try the entropy engine right now — no root, no network access required:

git clone https://github.com/<your-org>/beaconsentry.git
cd beaconsentry
python3 core/entropy_engine.py

Run live capture (requires root/CAP_NET_RAW — this touches real packets):

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
sudo python3 core/packet_capture.py

---

📁 Project Structure

beaconsentry/
├── core/
│   ├── entropy_engine.py     # Phase 1 — Shannon entropy DNS tunneling detector
│   └── packet_capture.py     # Phase 1 — threaded live traffic parsing core
├── requirements.txt
├── README.md
└── LICENSE

---

🧪 How the Entropy Engine Actually Works

Shannon entropy measures unpredictability. A human-typed subdomain like www or prod-api-eu follows language patterns — low entropy. A base32/hex-encoded exfil payload crammed into a label looks like f8a91cbe7710eae... — every character close to equally probable, high entropy.

But entropy alone false-positives on CDN hashes and S3 buckets. So BeaconSentry combines five independent weak signals into one composite score — deliberately harder to evade than tuning around a single threshold:

1. Raw + normalized Shannon entropy of the target label
2. Character-class anomalies (hex ratio, consonant-run patterns)
3. Structural anomalies (subdomain depth)
4. Adaptive statistical deviation — a self-learning baseline per root domain, so it calibrates to your network instead of a hardcoded number
5. Query frequency within a sliding window — one high-entropy query is noise; twenty to the same domain in two minutes is a drip channel

Read the fully-commented source in core/entropy_engine.py — every function explains the why, not just the what.

---

⚠️ Responsible Use

BeaconSentry is a defensive, educational tool. Only run it against traffic on networks you own or are explicitly authorized to monitor. The techniques here mirror what any competent blue team or detection engineer already does — this project just shows you how to build it yourself.

---

🤝 Contributing

Phases 2–5 are open for contributions — this is meant to be built with the community, not just consumed. Good first issues:

• Swap the naive eTLD+1 extraction for tldextract
• Add a publicsuffix2-backed root domain resolver
• Propose beaconing feature ideas for Phase 2

Open an issue or PR. If BeaconSentry helped you learn something, a ⭐ goes a long way toward getting Phases 2–5 built faster.

📜 License

MIT — see LICENSE.