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
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# Contribuindo com o Acauã
|
|
|
|
[English](CONTRIBUTING.md) · **Português**
|
|
|
|
Obrigado por ajudar. O projeto é um esqueleto pré-alfa, então as contribuições
|
|
mais úteis agora são testes, fixtures, documentação e correções de projeto
|
|
pequenas e bem delimitadas.
|
|
|
|
1. **Só monitoramento autorizado.** O Acauã é software defensivo para redes
|
|
próprias ou com autorização explícita. Não adicione caminhos de coleta que
|
|
escondam escopo, retenção ou evidência.
|
|
2. **Evidência faz parte do recurso.** Uma mudança de detecção precisa declarar
|
|
entradas, reduções em ordem fixa e valores intermediários. Pontuação sem
|
|
registro reproduzível de evidência não é aceita.
|
|
3. **Seja honesto sobre o que funciona.** Se um recurso é stub, só roda no Linux
|
|
ou cobre apenas um log Zeek, diga isso no README, no `--help` e no teste.
|
|
4. **Código 100% em inglês.** Código-fonte, comentários, scripts, workflows e
|
|
mensagens de commit são em inglês. A GUI e a CLI continuam bilíngues (PT-BR e
|
|
EN via `i18n-en.js`).
|
|
|
|
## Fluxo
|
|
|
|
```bash
|
|
scripts/install-hooks.sh
|
|
scripts/check.sh
|
|
scripts/check.sh --full
|
|
```
|
|
|
|
O `check.sh` roda formatação, clippy com warnings como erro, cobertura de
|
|
tradução da UI, sintaxe de shell, YAML dos workflows, consistência de SemVer e a
|
|
checagem do desktop. O `--full` inclui testes do workspace e `cargo audit`.
|
|
|
|
A feature opcional DuckDB não entra na checagem padrão:
|
|
|
|
```bash
|
|
cargo check -p acaua-core --features duckdb
|
|
```
|
|
|
|
## Pesquisa
|
|
|
|
`research/` é um espaço Python isolado para validação científica. Ele pode usar
|
|
astropy, scipy, networkx, pandas e notebooks. Ele nunca deve ser importado pelo
|
|
runtime Rust, copiado para um release ou exigido para compilar o produto.
|
|
|
|
## Regras de detecção
|
|
|
|
- Mantenha reduções em ordem fixa quando resultados de ponto flutuante entram em
|
|
um alerta.
|
|
- Use um valor sentinela documentado em vez de `NaN` ou panic para entradas
|
|
degeneradas.
|
|
- Use Jensen-Shannon, não KL puro, quando uma distribuição pode ter probabilidade
|
|
zero.
|
|
- Não use JA4S/JA4H/JA4X/JA4SSH/JA4L por padrão: essas variantes têm licença
|
|
não-OSI. O JA4 de impressão digital de cliente TLS é o único padrão.
|
|
- Conexões longas precisam de detector próprio; elas não produzem os intervalos
|
|
curtos que uma pontuação de beaconing espera.
|
|
|
|
## Interface e tradução
|
|
|
|
O texto-fonte da interface é em português. O inglês vem de
|
|
`apps/gui/ui/i18n-en.js`, aplicado em tempo de execução por `i18n.js`. Ao
|
|
adicionar texto visível, rode `node scripts/check-ui-i18n.mjs` e inclua o par em
|
|
inglês.
|
|
|
|
## Documentação
|
|
|
|
Mantenha o par: todo arquivo `*.md` e `docs/*` tem versão em inglês e em
|
|
português (`*.pt-BR.md`, `docs/pt-BR/`). Nomes de arquivo só são traduzidos
|
|
quando a palavra muda de verdade, como `architecture.md` → `arquitetura.md`.
|
|
|
|
## Commits e releases
|
|
|
|
Os commits seguem Conventional Commits 1.0.0 em inglês (`feat:`, `fix:`,
|
|
`chore:`, `ci:`, `docs:`, `refactor:`, `test:`, `perf:`, `build:`). As versões
|
|
seguem SemVer 2.0.0 e ficam sincronizadas entre o workspace, o manifesto do
|
|
desktop e a configuração do Tauri.
|
|
|
|
Enviar uma tag `v*` cria uma Release no Gitea a partir da seção correspondente do
|
|
`CHANGELOG.md` e anexa os pacotes Linux da CLI e os bundles do desktop.
|
|
|
|
## Licença
|
|
|
|
Ao contribuir, você concorda em licenciar sob [MIT](LICENSE-MIT) **ou**
|
|
[Apache-2.0](LICENSE-APACHE), como o resto do projeto.
|