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
83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# Contributing to Acauã
|
|
|
|
**English** · [Português](CONTRIBUTING.pt-BR.md)
|
|
|
|
Thanks for helping. The project is a pre-alpha skeleton, so the most useful
|
|
contributions right now are tests, fixtures, documentation and small,
|
|
well-scoped design corrections.
|
|
|
|
1. **Authorized monitoring only.** Acauã is defensive software for networks you
|
|
own or are explicitly authorized to observe. Do not add collection paths that
|
|
hide scope, retention or evidence.
|
|
2. **Evidence is part of the feature.** A detection change must state its
|
|
inputs, fixed-order reductions and intermediate values. A score without a
|
|
reproducible evidence record is not accepted.
|
|
3. **Be honest about what works.** If a feature is a stub, Linux-only or limited
|
|
to one Zeek log, say so in the README, the CLI help and the test.
|
|
4. **100% English codebase.** Source code, comments, scripts, workflows and
|
|
commit messages are English. The GUI and CLI remain bilingual (PT-BR and EN
|
|
through `i18n-en.js`).
|
|
|
|
## Workflow
|
|
|
|
```bash
|
|
scripts/install-hooks.sh
|
|
scripts/check.sh
|
|
scripts/check.sh --full
|
|
```
|
|
|
|
`check.sh` runs formatting, clippy with warnings as errors, UI translation
|
|
coverage, shell syntax, workflow YAML, SemVer consistency and the desktop check.
|
|
`--full` adds workspace tests and `cargo audit`.
|
|
|
|
The optional DuckDB feature is not part of the default check:
|
|
|
|
```bash
|
|
cargo check -p acaua-core --features duckdb
|
|
```
|
|
|
|
## Research
|
|
|
|
`research/` is an isolated Python workspace for scientific validation. It may
|
|
use astropy, scipy, networkx, pandas and notebooks. It must never be imported by
|
|
the Rust runtime, copied into a release or required to build the product.
|
|
|
|
## Detection rules
|
|
|
|
- Keep reductions in a fixed order when floating-point results are part of an
|
|
alert.
|
|
- Use a documented sentinel instead of `NaN` or a panic for degenerate inputs.
|
|
- Use Jensen-Shannon, not raw KL, when a distribution can contain zero
|
|
probability.
|
|
- Do not use JA4S/JA4H/JA4X/JA4SSH/JA4L by default: those variants carry a
|
|
non-OSI license. The client TLS JA4 fingerprint is the only default.
|
|
- Long connections need their own detector; they do not produce the short
|
|
intervals a beaconing score expects.
|
|
|
|
## Interface and translation
|
|
|
|
The interface source text is Portuguese. English comes from
|
|
`apps/gui/ui/i18n-en.js`, applied at runtime by `i18n.js`. When adding visible
|
|
text, run `node scripts/check-ui-i18n.mjs` and include the English pair.
|
|
|
|
## Documentation
|
|
|
|
Keep the pair: every `*.md` and `docs/*` file has an English version and a
|
|
Portuguese version (`*.pt-BR.md`, `docs/pt-BR/`). File names are translated only
|
|
when the word actually changes, as in `architecture.md` → `arquitetura.md`.
|
|
|
|
## Commits and releases
|
|
|
|
Commits follow Conventional Commits 1.0.0 in English (`feat:`, `fix:`, `chore:`,
|
|
`ci:`, `docs:`, `refactor:`, `test:`, `perf:`, `build:`). Versions follow SemVer
|
|
2.0.0 and are synchronized across the workspace, the desktop manifest and the
|
|
Tauri config.
|
|
|
|
Pushing a `v*` tag creates a Gitea Release from the matching `CHANGELOG.md`
|
|
section and attaches the Linux CLI packages plus the desktop bundles.
|
|
|
|
## License
|
|
|
|
By contributing, you agree to license under [MIT](LICENSE-MIT) **or**
|
|
[Apache-2.0](LICENSE-APACHE), like the rest of the project.
|