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: esqueleto pré-alfa. A estrutura do projeto, a documentação, o CI e os stubs que compilam existem. Os quatro pilares matemáticos de detecção, o parser real de logs Zeek, o armazenamento DuckDB e o motor de alertas estão em desenvolvimento e ainda não são distribuídos. Nada nesta página deve ser lido como promessa de que a detecção já funciona.

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 stubs da CLI	✅ compila
API Axum com rotas de health, status, alertas e análise	✅ stub
Dashboard web embutido	✅ shell da UI, servido 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	🚧 em desenvolvimento
Parser de logs Zeek	🚧 stub
Evidência e pontuação de alertas	🚧 stub
Releases publicadas	❌ nenhuma ainda

Os quatro pilares

Todos os quatro estão em desenvolvimento. O roadmap os mantém como trabalho futuro, não como recurso implementado.

1. Beaconing: periodicidade sobre timestamps de eventos com periodograma de Rayleigh/Schuster, e Lomb–Scargle generalizado só onde existe um y real.
2. Sessões persistentes: conexões longas que nunca produzem um Δt curto e ficariam invisíveis para um detector de beaconing.
3. Anomalias de protocolo: features determinísticas sobre logs de protocolo do Zeek, incluindo sinais de identidade e movimento lateral.
4. Fusão de evidências: combinação limitada e simétrica das pontuações dos pilares, com um registro de evidência reproduzível por alerta.

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.