acaua/README.pt-BR.md

Acauã

Caça determinística a ameaças em rede.
NDR com Zeek como entrada principal · local-first · uso autorizado.

Terminal · Interface · Arquitetura · Docker · Suporte · Roadmap · Changelog

English · Português

---

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.

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):

cp .env.example .env
docker compose pull && docker compose up -d

Ou compilar e rodar localmente com Docker:

docker compose up -d --build

Para compilar do código nativamente (requer Rust 1.88+):

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

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

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 e 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:

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 ou Apache-2.0, à sua escolha.