acaua/README.md

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.log and 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.
• Server daemon and web dashboard: acaua serve runs continuous ingestion, scheduling, the API and the embedded web UI, distributed 100% via Docker.
• 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
Embedded web dashboard	✅ UI shell, served by daemon
Documentation and CI/release workflows	✅
Docker multi-arch image and compose deployment	✅
DuckDB analytical store	✅ official prebuilt library linked
Four detection pillars	🚧 under development
Zeek log parser	🚧 stub
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.

1. Beaconing: periodicity on event timestamps with a Rayleigh/Schuster periodogram, and generalized Lomb–Scargle only where a real y exists.
2. Persistent sessions: long connections that never produce a short Δt and would otherwise stay invisible to a beaconing detector.
3. Protocol anomalies: deterministic features over Zeek protocol logs, including identity and lateral-movement signals.
4. 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 Docker Compose deployment isolates the daemon in an unprivileged, read-only container with dropped capabilities.

Install

Run via Docker Compose (recommended for operators):

cp .env.example .env
docker compose pull && docker compose up -d

Or build and run locally with Docker:

docker compose up -d --build

To compile from source natively (Rust 1.88+ required):

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

Supported platform matrix for published container images: linux/amd64 and linux/arm64.

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 web UI. update checks for new versions and guides container image updates.

Development

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

See CONTRIBUTING.md and docs/architecture.md.

Known limits

• The detection engine, Zeek parser and storage layer are stubs.
• There is no published release image yet.
• NetFlow/IPFIX is a degraded input mode by design; it cannot replace the Zeek protocol logs for every pillar.
• The project targets Linux container environments (linux/amd64, linux/arm64).

Where it's going

Summary of the ROADMAP:

Done	Workspace, CLI/API stubs, web dashboard, Docker containerization, CI/release workflows
Next	Pillar 1 and 2 implementations with deterministic fixtures; real Zeek parser
Later	Full Parquet partitioning, TTL pruning, pillar 3 and 4, evidence fusion
Not planned	Opaque AI scoring, a required cloud service, Python in the shipped runtime

License

MIT or Apache-2.0, your choice.