Lucas RayanandClaude Sonnet 5
1b974bb90d
Acauã: Network Detection & Threat Hunting, heuristic analysis over a rolling 7-day window using deterministic math (time series, graph theory, information theory) instead of opaque ML models. Third product in the Ciberfauna ecosystem, alongside Guará and Sabiá. Follows the ecosystem's established conventions: OpenWolf project memory, bilingual PT-BR/EN docs and UI, Gitea Actions CI/CD on the same self-hosted runners, Conventional Commits, SemVer, logo and productName handling, MIT OR Apache-2.0 licensing. Architecture decision (made with the project owner after a dedicated consultation, not the original blueprint's suggested stack): Rust throughout, not Python/FastAPI/React. Most of the statistics (Bowley skew, MADM, Shannon entropy, PCR, Z-score, novel-edge detection, pivot chains) reduces to SQL over an embedded DuckDB/Parquet store; only the spectral analysis and graph centrality need host-language code, and both have workable Rust crates. Documented in full, including six corrections to the original blueprint's math (Rayleigh/Schuster instead of a degenerate Lomb-Scargle over bare timestamps, an explicit sentinel for Bowley skew's Q3=Q1 case, Jensen-Shannon instead of unbounded KL, a dedicated long-connection detector, JA4 vs. JA4+ licensing caution, deterministic per-alert evidence), in docs/architecture.md. Skeleton only: crates/acaua-core has the four detection pillars, fusion, storage, zeek log parsing and the updater as typed stubs that compile and return a clear "skeleton" status rather than real detection logic — that is separate, future work. crates/acaua-cli has serve/analyze/doctor/update. apps/gui is a minimal Tauri shell. Also already includes the one-click desktop self-update mechanism shared with Guará and Sabiá (AppImage/.deb/Windows installer), even with no release published yet, for consistency across the ecosystem. No Gitea repository exists for this project yet; this is a local-only commit. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VAyr8d7HuAdUGB6aA5xmDD
148 lines
6.4 KiB
Markdown
148 lines
6.4 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: 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 e desktop:** `acaua serve` roda ingestão contínua, agendador, API e a
|
||
UI embutida; o app Tauri abre um dataset local ou conversa com um `serve`
|
||
remoto.
|
||
- **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 |
|
||
| Shell desktop e UI vanilla | ✅ shell, sem screenshots reais |
|
||
| Documentação e workflows de CI/release | ✅ |
|
||
| Quatro pilares de detecção | 🚧 em desenvolvimento |
|
||
| Parser de logs Zeek | 🚧 stub |
|
||
| Armazenamento DuckDB/Parquet e TTL de 7 dias | 🚧 reservado, feature desligada por padrão |
|
||
| 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](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 opcional com Docker é
|
||
documentada para laboratório e pesquisa.
|
||
|
||
## Instalação
|
||
|
||
Ainda não há releases publicadas. Compile do código:
|
||
|
||
```bash
|
||
cargo build --release -p acaua-cli
|
||
./target/release/acaua --help
|
||
```
|
||
|
||
É preciso Rust 1.80+. O app desktop precisa das dependências de sistema do Tauri
|
||
para a sua plataforma.
|
||
|
||
## 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 a UI embutida. O `update`
|
||
usa o mesmo modelo de Gitea Releases + SHA-256 do Guará e do Sabiá.
|
||
|
||
## App desktop
|
||
|
||
O app Tauri é um shell para a mesma UI usada pelo `serve`. Ele tem um painel dos
|
||
quatro pilares, um campo de caminho de dataset, um painel de alertas e
|
||
configurações de idioma e tema. Ele **ainda não** renderiza resultados de
|
||
detecção. Veja **[docs/pt-BR/interface.md](docs/pt-BR/interface.md)**.
|
||
|
||
## Desenvolvimento
|
||
|
||
```bash
|
||
cargo test --workspace
|
||
cargo clippy --workspace --all-targets
|
||
node scripts/check-ui-i18n.mjs
|
||
scripts/check.sh
|
||
```
|
||
|
||
O backend DuckDB opcional é compilado com `--features duckdb`; ele fica desligado
|
||
por padrão para o esqueleto continuar rápido de verificar. 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á binário, instalador ou asset de release publicado.
|
||
- A GUI não tem screenshots reais porque ainda não há nada para renderizar.
|
||
- NetFlow/IPFIX é um modo degradado por projeto; ele não substitui os logs de
|
||
protocolo do Zeek em todos os pilares.
|
||
- O projeto mira Linux para o daemon e para o pipeline de release do CI. O app
|
||
desktop segue a mesma matriz Tauri dos projetos irmãos.
|
||
|
||
## Para onde vai
|
||
|
||
Resumo do [ROADMAP](ROADMAP.pt-BR.md):
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Feito** | Workspace, stubs de CLI/API, shell da GUI, documentação, workflows de CI/release |
|
||
| **Próximo** | Implementação dos pilares 1 e 2 com fixtures determinísticas; parser Zeek real |
|
||
| **Depois** | Armazenamento DuckDB/Parquet, TTL, pilares 3 e 4, fusão de evidências, visão de dataset no desktop |
|
||
| **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.
|