Beacon Hunter

Detectando C2 Estruturado Não Periódico via Recorrência Aditiva

O Beacon Hunter detecta beaconing de comando e controle que usa agendamento de recorrência aditiva compatível com phi — um padrão de temporização crescente e não periódico onde cada intervalo entre conexões é aproximadamente igual à soma dos dois anteriores. Essa família evade detectores baseados em regularidade (RITA, AC-Hunter) por design, enquanto permanece estruturalmente identificável através de um teste de recorrência de dois portões.

"Um beacon não precisa ser periódico para ser estruturado."

Início Rápido

Pipeline de dois portões do Beacon Hunter: Gate 1 filtra por agrupamento de razão phi, Gate 2 testa estrutura de recorrência aditiva.

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

Como Funciona

O Beacon Hunter é um pipeline de dois portões que opera em logs de conexão do Zeek.

Gate 1 — Teste de Razão
Agrupa conexões do mesmo par origem/destino e calcula as razões consecutivas de intervalos entre conexões (ICI). Passa se a razão média estiver próxima de phi (φ = 1.618) dentro de ±0,20 e a variabilidade da razão (CV) estiver abaixo de 0,50. Mínimo: 5 intervalos.

Gate 2 — Teste de Recorrência Aditiva
Testa se ICI[n+2] ≈ ICI[n+1] + ICI[n] é válido em todos os triplos consecutivos, usando erro relativo médio contra um nulo de permutação de 500 iterações. Passa se o erro médio < 0,20 e p < 0,05. Este portão rejeita crescimento de lei de potência (residual 0,40) e backoff exponencial (0,56) que passam no Gate 1 por coincidência.

Rótulos de classificação

Envelope de aceitação: razões geométricas em [1.45, 1.80], confirmado empiricamente por varredura de limites.

Arquitetura

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)

Pipeline de Evidências

Notas do Dataset

Para avaliação UWF-ZeekData22: baixe de https://datasets.uwf.edu/data/ e converta usando tools/uwf_to_connlog.py.

Resultados Principais

Validação Operacional

Estes resultados são da execução do Beacon Hunter contra tráfego empresarial real:

Comparação com RITA real v5.1.2 (reports/rita_output_v5.1.2_24h.txt):
Ambas as ferramentas detectam o beacon periódico com jitter de 30 segundos. RITA atribui a ele 0.617 de severidade baixa entre 50 outros alertas Críticos/Alto. Beacon Hunter o classifica como JITTERED_BEACON. Um agendamento de recorrência aditiva puro pontua abaixo de 0.35 no RITA — comprovado analiticamente no Apêndice A, confirmado empiricamente.

UWF-ZeekData22 (1 milhão de conexões empresariais reais):
0/12.083 fluxos analisados sinalizados como ADDITIVE_RECURRENCE_BEACON na semana benigna. 0/1.995 na semana de ataque Recon/Descoberta (correto — varreduras de porta não são beaconing). Todos os 4 beacons Fibonacci injetados detectados com 0–25% de jitter.

Background empresarial Zeek de 24 horas:
1/243 fluxos analisados sinalizado — IPv6 NDP em 34% de heurística de triagem do analista, marginal e atribuível ao protocolo.

Reprodução

Consulte EXPECTED_RESULTS.md para as saídas numéricas exatas esperadas.

# 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

Limitações

• Nenhum malware real confirmado usando agendamento compatível com phi (modelo de ameaça é teórico)
• Taxa de falsos positivos caracterizada em dois conjuntos de dados reais; avaliação em escala empresarial de várias semanas permanece trabalho futuro
• Superfície de detecção é estreita por design — o detector visa uma família de temporização estrutural

Citação

Se você usar este trabalho, por favor, cite o artigo acompanhante:

Cordero, A. (2026). Detecting Non-Periodic Structured C2 Beaconing via Additive Recurrence. RepoSignal.io LLC. https://doi.org/10.5281/zenodo.20431555

Licença

AGPL-3.0. Veja LICENSE.

Licenciamento comercial disponível através da RepoSignal.io LLC.