0 Fork 0

Files

T

Lucas RayanandClaude Sonnet 5 c64bbbf775 feat: implement Pillars 2-4 and fix a production false-positive in Pillar 1

Pillar 1 v1.1 (shipped earlier) flagged benign browsing bursts as
beaconing: on short captures, grid periods longer than the observed
span never complete a cycle, so significance saturates to 1 and the
score sticks at exactly 0.5. v1.2 caps the grid at a third of the
observed span, requires a minimum number of completed cycles, and
excludes protocols that are periodic by nature (NTP, DNS, mDNS,
ICMP). Validated against 300 seeds per scenario: false positives on
bursty traffic drop from the 290-300/300 that v1.1 produced to 0/300,
with every beacon-detection scenario scoring unchanged.

Add Pillar 2 (persistent/long-lived sessions, with Zeek's fragmented
TCP sessions rejoined after a 5-minute gap), Pillar 3 (DNS tunneling
via Shannon-entropy information volume per subdomain per hour; the
Jensen-Shannon divergence was measured and does not separate tunnels
from benign CDN subdomains, so it stays in the evidence at zero
weight instead of in the score), and Pillar 4 (deterministic
noisy-OR fusion across the three pillars).

The fusion formula was validated against 8 labeled real-traffic
vectors (IoT-23, CTU-Normal) with tolerance <= 1e-4. A known
limitation is kept, not hidden: a benign Philips HUE bulb's strict
periodic polling and a 21.9h session score it above three real C2
hosts. No weight or threshold was tuned to mask this; it is
documented in the architecture docs instead.

Also fixes real bugs found along the way: ingest_dir's partition
count summed file names instead of distinct dates, DuckDB errors
were counted as bad rows, /api/alerts always returned an empty list
regardless of the last analysis, and the dashboard still claimed
every pillar was unimplemented.

Restores four design corrections that were missing from
docs/architecture.md (KL to Jensen-Shannon, the persistent-session
detector, the JA4 licensing boundary, and deterministic reduction
order), and catalogs the public datasets used for validation
(IoT-23, CTU-Normal, Mendeley DTQBC) with their licenses and SHA-256
checksums under research/validation/.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VAyr8d7HuAdUGB6aA5xmDD

2026-11-01 00:28:54 -03:00

2.8 KiB

Raw Blame History

Terminal

English · Português

O binário acaua atua tanto como utilitário de linha de comando quanto como daemon de segundo plano. Esta página descreve os comandos disponíveis no motor.

acaua <command> [options]

Comandos:
  serve    Inicia a API e o dashboard web embutido
  analyze  Analisa um diretório de logs do Zeek
  doctor   Verifica o ambiente local
  update   Checa por releases disponíveis

`acaua serve`

Inicia a API HTTP e o dashboard web embutido.

acaua serve --bind 127.0.0.1:8787 --data-dir .acaua

Opção	Padrão	Significado
`--bind`	`127.0.0.1:8787`	Endereço de escuta
`--data-dir`	`.acaua`	Diretório de dados e arquivos de execução

O bind padrão restringe-se a loopback. Expô-lo em uma rede exige um proxy reverso com autenticação. A API está documentada em arquitetura.md.

`acaua analyze`

acaua analyze /var/log/zeek/current
acaua analyze /var/log/zeek/current --json

Valida o diretório alvo, ingere tráfego do conn.log e dns.log em partições Parquet e executa os algoritmos de detecção de ameaças dos pilares 1 a 4. A saída legível para humanos relata métricas de sumário, alertas individuais e a seção de classificação hosts: (top 10 por score de prioridade):

diretório: /var/log/zeek/current
logs lidos: 2
registros: 10450
alertas: 2
  [0.850] Beaconing detected: 192.168.1.50:any -> 198.51.100.1:443 (period ~14400s, score 0.850)
  [0.600] Persistent session: 192.168.1.50 -> 198.51.100.1:443 (6.0h, score 0.600)
hosts:
  [0.784] 192.168.1.50       0.850/0.600/0.000
estado: ok

`acaua doctor`

acaua doctor
acaua doctor --json

Executa checagens de ambiente:

zeek: verifica zeek --version ou detecta execução em container (ACAUA_RUNTIME=container).
curl: confirma disponibilidade de download HTTP.
duckdb: confirma linkagem dinâmica contra a libduckdb.so em tempo de execução.
research: valida o isolamento do workspace de pesquisa.

`acaua update`

acaua update

Consulta a API de Releases do Gitea, compara a última tag com a versão em execução e imprime instruções de atualização (docker compose pull && docker compose up -d quando em container).

Códigos de saída

Código	Significado
`0`	Sucesso
`1`	Erro em tempo de execução (caminho inválido, erro de consulta, I/O)
`2`	Uso inválido de linha de comando (clap)

Ambiente

Variável	Significado
`ACAUA_RUNTIME`	Definida como `container` em imagens Docker para adaptar checagens
`DUCKDB_LIB_DIR`	Caminho do diretório contendo `libduckdb.so` em compilação nativa
`LD_LIBRARY_PATH`	Caminho de busca de bibliotecas compartilhadas para `libduckdb.so`

2.8 KiB Raw Blame History

Terminal

acaua serve

acaua analyze

acaua doctor

acaua update