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
5.9 KiB
Acauã
Deterministic network threat hunting.
Zeek-first NDR research · local-first · authorized use.
Terminal · Interface · Architecture · Docker · Support · Roadmap · Changelog
English · Português
Status: pre-alpha skeleton. The project structure, documentation, CI and compiling stubs exist. The four mathematical detection pillars, the real Zeek parser, DuckDB storage and the alert engine are under development and are not shipped yet. Nothing on this page should be read as a claim that detection already works.
Acauã is a network threat hunting engine built around deterministic evidence, not an opaque model. The goal is to answer not only "this looks suspicious" but "these exact inputs, with these intermediate values, produced this score".
- Deterministic by design: fixed-order reductions, documented sentinels and a JSON evidence record for every future alert.
- Local-first: the analytical store is embedded in the process; no external database and no telemetry by default.
- Zeek-first:
dns.log,ssl.log,conn.logand the protocol logs needed for identity and lateral-movement analysis. NetFlow/IPFIX is a documented degraded mode, never presented as equivalent. Suricata EVE JSON is an optional secondary input. - Daemon and desktop:
acaua serveruns continuous ingestion, scheduling, the API and the embedded UI; the Tauri app opens a local dataset or talks to a remoteserve. - Research stays outside the product:
research/is an isolated Python workspace for scientific validation and fixtures. It is never compiled, packaged or released.
What exists today
| Area | State |
|---|---|
| Rust workspace and CLI stubs | ✅ compiles |
| Axum API with health, status, alerts and analyze routes | ✅ stub |
| Desktop shell and vanilla UI | ✅ shell, no real screenshots |
| Documentation and CI/release workflows | ✅ |
| Four detection pillars | 🚧 under development |
| Zeek log parser | 🚧 stub |
| DuckDB/Parquet storage and 7-day TTL | 🚧 reserved, feature disabled by default |
| Alert evidence and scoring | 🚧 stub |
| Published releases | ❌ none yet |
The four pillars
All four are under development. The roadmap keeps them as future work, not as implemented features.
- Beaconing: periodicity on event timestamps with a Rayleigh/Schuster
periodogram, and generalized Lomb–Scargle only where a real
yexists. - Persistent sessions: long connections that never produce a short
Δtand would otherwise stay invisible to a beaconing detector. - Protocol anomalies: deterministic features over Zeek protocol logs, including identity and lateral-movement signals.
- Evidence fusion: bounded, symmetric combination of pillar scores with a reproducible evidence record per alert.
The design decisions behind these pillars, including the six corrections to the original blueprint, are in docs/architecture.md.
Authorized use
Acauã is defensive software for networks you own or are explicitly authorized to monitor. Capturing or analyzing third-party traffic without permission may be illegal. The operator is responsible for scope, privacy and retention.
The daemon binds to 127.0.0.1 by default. The optional Docker deployment is
documented for lab and research use.
Install
There are no published releases yet. Build from source:
cargo build --release -p acaua-cli
./target/release/acaua --help
Rust 1.80+ is required. The desktop app needs the Tauri system dependencies for your platform.
Getting started
acaua doctor
acaua serve --bind 127.0.0.1:8787 --data-dir .acaua
acaua analyze /var/log/zeek/current --json
acaua update
analyze currently validates the directory and returns a skeleton report; it
does not parse Zeek logs yet. serve exposes the stub API and the embedded UI.
update uses the same Gitea Releases + SHA-256 model as Guará and Sabiá.
Desktop app
The Tauri app is a shell for the same UI used by serve. It has a dashboard for
the four pillars, a dataset path field, an alerts panel and settings for language
and theme. It does not render detection results yet. See
docs/interface.md.
Development
cargo test --workspace
cargo clippy --workspace --all-targets
node scripts/check-ui-i18n.mjs
scripts/check.sh
The optional DuckDB backend is compiled with --features duckdb; it is disabled
by default so the skeleton stays fast to check. See
CONTRIBUTING.md and
docs/architecture.md.
Known limits
- The detection engine, Zeek parser and storage layer are stubs.
- There is no published binary, installer or release asset.
- The GUI has no real screenshots because there is nothing to render yet.
- NetFlow/IPFIX is a degraded input mode by design; it cannot replace the Zeek protocol logs for every pillar.
- The project targets Linux for the daemon and the CI release pipeline. The desktop app follows the same Tauri platform matrix as the sibling projects.
Where it's going
Summary of the ROADMAP:
| Done | Workspace, CLI/API stubs, GUI shell, documentation, CI/release workflows |
| Next | Pillar 1 and 2 implementations with deterministic fixtures; real Zeek parser |
| Later | DuckDB/Parquet storage, TTL, pillar 3 and 4, evidence fusion, desktop dataset view |
| Not planned | Opaque AI scoring, a required cloud service, Python in the shipped runtime |
License
MIT or Apache-2.0, your choice.