Lucas RayanandClaude Sonnet 5
c64bbbf775
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
149 lines
6.7 KiB
Markdown
149 lines
6.7 KiB
Markdown
<p align="center"><img src="logo.png" width="300" alt="Acauã"></p>
|
||
<h1 align="center">Acauã</h1>
|
||
<p align="center">Caça determinística a ameaças em rede.<br>NDR com Zeek como entrada principal · local-first · uso autorizado.</p>
|
||
|
||
<p align="center"><a href="docs/pt-BR/cli.md">Terminal</a> · <a href="docs/pt-BR/interface.md">Interface</a> · <a href="docs/pt-BR/arquitetura.md">Arquitetura</a> · <a href="docs/pt-BR/docker.md">Docker</a> · <a href="docs/pt-BR/suporte.md">Suporte</a> · <a href="ROADMAP.pt-BR.md">Roadmap</a> · <a href="CHANGELOG.pt-BR.md">Changelog</a></p>
|
||
|
||
<p align="center"><a href="README.md">English</a> · <b>Português</b></p>
|
||
|
||
---
|
||
|
||
**Estado: pré-lançamento (versão inicial).** A estrutura do projeto, a documentação,
|
||
o CI, a ingestão de `conn.log` e `dns.log` do Zeek, o armazenamento analítico DuckDB/Parquet
|
||
e as versões iniciais dos pilares 1 a 4 estão implementados e validados contra
|
||
tráfego público. Ingestão contínua automática e persistência de alertas entre reinícios
|
||
estão planejadas para os próximos lançamentos.
|
||
|
||
O Acauã é um motor de caça a ameaças em rede construído em torno de evidência
|
||
determinística, não de um modelo opaco. O objetivo é responder não só "isto
|
||
parece suspeito", mas "estas entradas exatas, com estes valores intermediários,
|
||
produziram esta pontuação".
|
||
|
||
- **Determinístico por projeto:** reduções em ordem fixa, sentinelas
|
||
documentados e um registro JSON de evidência para cada alerta futuro.
|
||
- **Local-first:** o armazenamento analítico mora dentro do processo; nenhum
|
||
banco externo e nenhuma telemetria por padrão.
|
||
- **Zeek como entrada principal:** `dns.log`, `ssl.log`, `conn.log` e os logs de
|
||
protocolo necessários para identidade e movimento lateral. NetFlow/IPFIX é um
|
||
modo degradado documentado, nunca apresentado como equivalente. Suricata EVE
|
||
JSON é uma entrada secundária opcional.
|
||
- **Daemon servidor e dashboard web:** `acaua serve` roda ingestão contínua,
|
||
agendador, API e o dashboard web embutido, distribuído 100% via Docker.
|
||
- **Pesquisa fora do produto:** `research/` é um espaço Python isolado para
|
||
validação científica e fixtures. Ele nunca é compilado, empacotado ou
|
||
distribuído.
|
||
|
||
## O que existe hoje
|
||
|
||
| Área | Estado |
|
||
|---|---|
|
||
| Workspace Rust e CLI (`acaua`) | ✅ funcional |
|
||
| API Axum com rotas de health, status, alertas e análise | ✅ funcional |
|
||
| Dashboard web embutido | ✅ UI servida pelo daemon |
|
||
| Documentação e workflows de CI/release | ✅ |
|
||
| Imagem Docker multi-arch e deployment com Compose | ✅ |
|
||
| Armazenamento analítico DuckDB | ✅ biblioteca oficial pré-compilada linkada |
|
||
| Quatro pilares de detecção (P1–P4) | ✅ versão inicial |
|
||
| Parser de logs Zeek (`conn.log`, `dns.log`) | ✅ funcional |
|
||
| Evidência e pontuação de alertas | ✅ JSON determinístico + fusão noisy-OR |
|
||
| Releases publicadas | ❌ nenhuma ainda |
|
||
|
||
## Os quatro pilares
|
||
|
||
Todos os quatro pilares estão implementados em sua **versão inicial (v1)** e validados contra fixtures sintéticas e capturas públicas:
|
||
|
||
1. **Beaconing (Pilar 1 v1.2):** periodicidade sobre timestamps de eventos com periodograma de
|
||
Rayleigh/Schuster limitado ao intervalo observado, portão de significância por regularidade e exclusões de infraestrutura.
|
||
2. **Sessões persistentes (Pilar 2 v1.0):** conexões TCP longas encadeadas através de timeouts de inatividade do Zeek (gap de até 3600s sem novo SYN), score logarítmico de persistência e rastreamento de PCR e tentativas falhas.
|
||
3. **Anomalias de protocolo (Pilar 3 v1.0):** capacidade determinística de informação (entropia de Shannon $\times$ caracteres de subdomínios únicos por hora UTC) em consultas DNS para detectar tunelamento.
|
||
4. **Fusão de evidências (Pilar 4 v1.0):** combinação noisy-OR ponderada por host ($w_1=w_2=w_3=0.75$) com evidência determinística em JSON e ordenação de prioridade.
|
||
|
||
As decisões de projeto por trás desses pilares, incluindo as seis correções ao
|
||
blueprint original, estão em **[docs/pt-BR/arquitetura.md](docs/pt-BR/arquitetura.md)**.
|
||
|
||
## Uso autorizado
|
||
|
||
O Acauã é software defensivo para redes próprias ou para redes que você tem
|
||
autorização explícita para monitorar. Capturar ou analisar tráfego de terceiros
|
||
sem permissão pode ser ilegal. O operador é responsável por escopo, privacidade e
|
||
retenção.
|
||
|
||
O daemon escuta em `127.0.0.1` por padrão. A implantação via Docker Compose
|
||
isola o daemon em um container não privilegiado, somente leitura e sem capabilities.
|
||
|
||
## Instalação
|
||
|
||
Executar via Docker Compose (recomendado para operadores):
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
docker compose pull && docker compose up -d
|
||
```
|
||
|
||
Ou compilar e rodar localmente com Docker:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Para compilar do código nativamente (requer Rust 1.88+):
|
||
|
||
```bash
|
||
scripts/fetch-libduckdb.sh ~/.cache/acaua/duckdb
|
||
export DUCKDB_LIB_DIR=~/.cache/acaua/duckdb LD_LIBRARY_PATH=~/.cache/acaua/duckdb
|
||
cargo build --release -p acaua-cli
|
||
./target/release/acaua --help
|
||
```
|
||
|
||
Matriz de plataformas suportadas para as imagens publicadas: `linux/amd64` e `linux/arm64`.
|
||
|
||
## Começando
|
||
|
||
```bash
|
||
acaua doctor
|
||
acaua serve --bind 127.0.0.1:8787 --data-dir .acaua
|
||
acaua analyze /var/log/zeek/current --json
|
||
acaua update
|
||
```
|
||
|
||
O `analyze` hoje valida o diretório e devolve um relatório de esqueleto; ele
|
||
ainda não lê logs Zeek. O `serve` expõe a API stub e o dashboard web embutido.
|
||
O `update` checa por versões novas e orienta a atualização da imagem do container.
|
||
|
||
## Desenvolvimento
|
||
|
||
```bash
|
||
scripts/fetch-libduckdb.sh ~/.cache/acaua/duckdb
|
||
export DUCKDB_LIB_DIR=~/.cache/acaua/duckdb LD_LIBRARY_PATH=~/.cache/acaua/duckdb
|
||
cargo test --workspace
|
||
cargo clippy --workspace --all-targets
|
||
node scripts/check-ui-i18n.mjs
|
||
scripts/check.sh --full
|
||
```
|
||
|
||
Veja **[CONTRIBUTING.pt-BR.md](CONTRIBUTING.pt-BR.md)** e
|
||
**[docs/pt-BR/arquitetura.md](docs/pt-BR/arquitetura.md)**.
|
||
|
||
## Limites conhecidos
|
||
|
||
- O motor de detecção, o parser Zeek e a camada de armazenamento são stubs.
|
||
- Não há imagem de release publicada ainda.
|
||
- NetFlow/IPFIX é um modo degradado por projeto; ele não substitui os logs de
|
||
protocolo do Zeek em todos os pilares.
|
||
- O projeto mira ambientes de container Linux (`linux/amd64`, `linux/arm64`).
|
||
|
||
## Para onde vai
|
||
|
||
Resumo do [ROADMAP](ROADMAP.pt-BR.md):
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Feito** | Workspace, stubs de CLI/API, dashboard web, containerização Docker, workflows de CI/release |
|
||
| **Próximo** | Implementação dos pilares 1 e 2 com fixtures determinísticas; parser Zeek real |
|
||
| **Depois** | Particionamento Parquet completo, limpeza por TTL, pilares 3 e 4, fusão de evidências |
|
||
| **Fora de plano** | Pontuação por IA opaca, serviço de nuvem obrigatório, Python no runtime distribuído |
|
||
|
||
## Licença
|
||
|
||
[MIT](LICENSE-MIT) ou [Apache-2.0](LICENSE-APACHE), à sua escolha.
|