mrcord77/beacon-hunterErkennt phi-strukturierte C2-Beacons, die RITA und standardmäßige auf Regelmäßigkeit basierende Detektoren umgehen.
Erkennung nichtperiodischer strukturierter C2-Kommunikation mittels additiver Rekurrenz
Beacon Hunter erkennt Command-and-Control-Beaconing, das eine Phi-kompatible additive Rekurrenzplanung verwendet – ein wachsendes, nichtperiodisches Zeitmuster, bei dem jedes Intervall zwischen zwei Verbindungen (ICI) ungefähr der Summe der beiden vorherigen entspricht. Diese Familie umgeht absichtlich auf Regelmäßigkeit basierende Detektoren (RITA, AC-Hunter), bleibt jedoch durch einen Zwei-Gatter-Rekurrenztest strukturell identifizierbar.
„Ein Beacon muss nicht periodisch sein, um strukturiert zu sein."
Beacon Hunter Zwei-Gatter-Pipeline: Gate 1 filtert nach Phi-Verhältnis-Clustering, Gate 2 testet die additive Rekurrenzstruktur.
pip install -r requirements.txt
# Run on a Zeek conn.log
python beacon_hunter.py /path/to/conn.log
# Reproduce all paper results
python run_full_evaluation.py --quick # ~2 min, skips full evidence suite
python run_full_evaluation.py # ~5 min, full pipeline
# Run unit tests
pytest tests/
# End-to-end validation (verifies paper claims)
python validate.py
Beacon Hunter ist eine Zwei-Gatter-Pipeline, die auf Zeek-Verbindungslogs arbeitet.
Gate 1 — Verhältnistest
Gruppiert Verbindungen vom selben Quell-/Ziel-Paar und berechnet aufeinanderfolgende Interverbindungsintervall (ICI)-Verhältnisse. Besteht, wenn das mittlere Verhältnis nahe Phi (φ = 1.618) innerhalb ±0.20 liegt und die Verhältnisvariabilität (CV) unter 0.50 liegt. Minimum: 5 Intervalle.
Gate 2 — Additiver Rekurrenztest
Testet, ob ICI[n+2] ≈ ICI[n+1] + ICI[n] über alle aufeinanderfolgenden Tripel gilt, unter Verwendung des mittleren relativen Fehlers gegenüber einer 500-Iterationen-Permutationsnullhypothese. Besteht, wenn der mittlere Fehler < 0.20 und p < 0.05. Dieses Gate lehnt Potenzgesetz-Wachstum (Residuum 0.40) und exponentielles Backoff (0.56) ab, die Gate 1 zufällig bestehen.
Klassifikationslabels
| Label | Bedeutung |
|---|---|
ADDITIVE_RECURRENCE_BEACON | Beide Gatter bestanden — Phi-kompatibler Zeitplan mit wachsenden Intervallen |
JITTERED_BEACON | Periodisch mit Jitter — besteht Verhältnis-Gate, fällt bei Rekurrenz durch |
REGULAR_BEACON | Beacon mit konstantem Intervall |
BACKGROUND | Keine Beaconing-Struktur erkannt |
INSUFFICIENT_DATA | Weniger als 5 Intervalle |
Akzeptanzhülle: geometrische Verhältnisse in [1,45; 1,80], empirisch durch Grenzbereichsdurchlauf bestätigt.
beacon_hunter_github/
├── beacon_hunter.py # CLI detector — entry point
├── detectors.py # Pure stateless gate functions (556 lines)
├── validate.py # 32-check end-to-end validation
├── run_full_evaluation.py # One-command reproduction pipeline
├── requirements.txt # Pinned dependencies
├── evidence/
│ ├── evidence_suite.py # All 6 evaluation batteries (Experiments A-J)
│ ├── rita_comparison.py # RITA-style periodicity baseline + real RITA comparison
│ ├── roc_and_ci.py # ROC curve (AUC=0.900) + Wilson CI
│ ├── generate_figures.py # Figures 1-7 (PNG + PDF)
│ └── *.json # Pre-computed results
├── data/
│ ├── pcaps/ # Ground-truth PCAPs (see Dataset Notes below)
│ └── zeek/ # Zeek conn.log files
├── figures/ # fig1-fig8 PNG + PDF (sequential)
├── paper/ # Full paper with appendices A-G
├── reports/ # Beacon Hunter output reports + real RITA v5.1.2 output
├── tests/
│ └── test_detectors.py # 34 unit tests (34/34 pass)
├── tools/
│ ├── fib_beacon_client.py # Fibonacci beacon traffic generator
│ ├── fib_beacon_server.py
│ └── uwf_to_connlog.py # UWF-ZeekData22 parquet → Zeek conn.log converter
└── archive/ # Deprecated scripts (legacy_detectors.py, old scanners)
| Skript | Experimente | Ausgabe |
|---|---|---|
evidence/evidence_suite.py | A (synthetisch), B (Labor-PCAP), C (AC-Jitter), E (Adversarial-Batterie), F (Jitter-Durchlauf), G (Längensensitivität), H (Nullverteilung), I (Phi-Grenze), J (Logistische Abbildung) | evidence_results.json |
evidence/roc_and_ci.py | G.5 (ROC, AUC=0.900), G (Wilson-KI [0.992, 1.000]) | roc_results.json |
evidence/rita_comparison.py | D (RITA-artiger Basislinienvergleich) | rita_comparison_results.json |
evidence/generate_figures.py | Abbildungen 1-7 | figures/fig*.png/pdf |
| Datei | Typ | Beschreibung |
|---|---|---|
data/pcaps/fib_beacon_validation.pcapng | Grundwahrheit | Im Labor generierter Fibonacci-Beacon-PCAP; verwendet in Experiment B |
data/pcaps/jit_var_d30_j0_1h.pcap | Grundwahrheit | 30s konstantes Beacon, 0% Jitter, 1 Stunde |
data/pcaps/jit_var_d30_j10_1h.pcap | Grundwahrheit | 30s Beacon, 10% Jitter, 1 Stunde |
data/pcaps/jit_var_d30_j99_1h.pcap | Grundwahrheit | 30s Beacon, 99% Jitter (reines Rauschen), 1 Stunde |
data/zeek/delay_var_d30_j25_combined.log | Real + injiziert | 2-stündiges Enterprise-Zeek-conn.log mit injiziertem 30s+25% Jitter-Beacon |
data/zeek/delay_var_d30_j25_24h_combined.log | Real + injiziert | 24-Stunden-Version von oben |
reports/rita_output_v5.1.2_24h.txt | Echter RITA-Ausgabe | Tatsächlicher RITA v5.1.2 Binärausgabe auf dem 24h-Datensatz (100 Flows bewertet) |
Für die UWF-ZeekData22-Auswertung: Herunterladen von https://datasets.uwf.edu/data/ und Konvertieren mit tools/uwf_to_connlog.py.
| Experiment | Ergebnis |
|---|---|
| Synthetische Erkennung (Exp A) | 3/3 Beacon-Klassen korrekt, 0 FP |
| Labor-PCAP (Exp B) | ADDITIVE_RECURRENCE_BEACON, rec_err=0.000, p<0.002 |
| Jitter-Durchlauf (Exp F) | 100% Erkennung bis 20% Jitter; Abfall bei 30% |
| Potenzgesetz vs. exponentielles Backoff (Exp E) | Residuen 0.40 und 0.56 > Schwellwert 0.20; korrekt abgelehnt |
| ROC AUC (Exp G.5) | 0.900; TPR=1.000 bei FPR=0.071 |
| Echt-RITA v5.1.2 auf verjittertem Beacon | 0,617 Niedriger Schweregrad (beide Tools erkennen; unterschiedliche Klassifikation) |
| UWF-ZeekData22 (1M Flows, benign) | 0/12.083 analysierte Flows als ARB markiert — 0,00% FPR |
| Logistische-Abbildungs-Batterie (Exp J) | Rein logistisch: 0% Erkennung; phi-verzerrt ≤20% Rauschen: 100% |
| Phi-Grenzbereichsdurchlauf (Exp I) | Akzeptanzfenster [1,45; 1,80] bestätigt |
Diese Ergebnisse stammen von der Ausführung von Beacon Hunter auf echtem Unternehmensverkehr:
Echt-RITA v5.1.2 Vergleich (reports/rita_output_v5.1.2_24h.txt):
Beide Tools erkennen das 30-Sekunden-verjitterte periodische Beacon. RITA bewertet es mit 0,617 Niedrigem Schweregrad unter 50 anderen Kritischen/Hohen Alarmen. Beacon Hunter klassifiziert es als JITTERED_BEACON. Ein reiner additiver Rekurrenzzeitplan erzielt bei RITA unter 0,35 — analytisch in Anhang A bewiesen, empirisch bestätigt.
UWF-ZeekData22 (1 Million echte Unternehmensverbindungen):
0/12.083 analysierte Flows als ADDITIVE_RECURRENCE_BEACON markiert in der benignen Woche. 0/1.995 in der Recon/Discovery-Angriffswoche (korrekt — Portscans sind kein Beaconing). Alle 4 injizierten Fibonacci-Beacons bei 0–25% Jitter erkannt.
24-stündiger Enterprise-Zeek-Hintergrund:
1/243 analysierte Flows markiert — IPv6 NDP bei 34% Analysten-Triage-Heuristik, marginal und protokollbedingt.
Siehe EXPECTED_RESULTS.md für die erwarteten exakten numerischen Ausgaben.
# Quick verification of all paper claims:
python validate.py
# Full pipeline (generates all outputs from scratch):
python run_full_evaluation.py
# Expected: 32/32 validation checks pass, ROC AUC=0.900, jitter 20%=100% detection
Wenn Sie diese Arbeit verwenden, zitieren Sie bitte das begleitende Paper:
Cordero, A. (2026). Detecting Non-Periodic Structured C2 Beaconing via Additive Recurrence. RepoSignal.io LLC. https://doi.org/10.5281/zenodo.20431555
AGPL-3.0. Siehe LICENSE.
Kommerzielle Lizenzierung erhältlich über RepoSignal.io LLC.