chore: initial project skeleton
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
This commit is contained in:
Lucas RayanandClaude Sonnet 5 committed
commit
1b974bb90d
95 files changed
+12016
No files matched your search
@@ -0,0 +1,177 @@
|
||||
# Architecture
|
||||
|
||||
**English** · [Português](pt-BR/arquitetura.md)
|
||||
|
||||
Acauã is a single Rust product: one daemon/CLI, one shared core, one embedded
|
||||
web UI and one Tauri shell. The shipped runtime has no Python and no external
|
||||
database. This document records the structural decisions and the six
|
||||
corrections applied to the original blueprint.
|
||||
|
||||
## Stack
|
||||
|
||||
| Layer | Choice | Why |
|
||||
|---|---|---|
|
||||
| Core, CLI and daemon | Rust 2021 | One toolchain, memory safety, no runtime dependency |
|
||||
| HTTP API | Axum + Tokio + Tower HTTP | Small async surface, easy to embed |
|
||||
| UI | Vanilla HTML/CSS/JS | No frontend build step, assets embedded in the binary |
|
||||
| Desktop | Tauri 2 | Native window over the same UI |
|
||||
| Analytical store | DuckDB + Parquet (optional `duckdb` feature) | Embedded, columnar, local-first |
|
||||
| Scientific validation | Python in `research/` only | astropy/scipy/networkx for fixtures, never shipped |
|
||||
|
||||
The workspace has two crates: `acaua-core` and `acaua-cli`. The GUI lives in
|
||||
`apps/gui`, **outside** the Cargo workspace, as in Guará and Sabiá. The spec
|
||||
mentioned `version.workspace = true` for the desktop manifest; keeping the GUI
|
||||
outside the workspace makes that impossible, so `check.sh` enforces SemVer
|
||||
equality across `Cargo.toml`, `acaua-cli/Cargo.toml`, the desktop manifest and
|
||||
`tauri.conf.json` instead. This is a deliberate deviation, not an oversight.
|
||||
|
||||
## Components
|
||||
|
||||
```
|
||||
Zeek logs ──► acaua-core::zeek ──► normalized events ──► storage
|
||||
│
|
||||
├──► pillar1 (beaconing)
|
||||
├──► pillar2 (persistent sessions)
|
||||
├──► pillar3 (protocol anomalies)
|
||||
└──► pillar4 (fusion) ──► alerts + evidence
|
||||
│
|
||||
acaua-cli ──► axum API ──► embedded UI ◄── Tauri shell ─────────────┘
|
||||
```
|
||||
|
||||
- `zeek`: bounded parser and path confinement. It must never follow a symlink
|
||||
outside the dataset root.
|
||||
- `storage`: DuckDB/Parquet writer with a seven-day TTL. Disabled by default so
|
||||
the skeleton does not require a C++ build.
|
||||
- `pillar1`–`pillar4`: pure functions over normalized events. They return
|
||||
scores plus evidence, never only a float.
|
||||
- `fusion`: fixed-order, bounded combination. It must be symmetric and
|
||||
reproducible.
|
||||
- `doctor`: local environment checks; no network calls except an explicit
|
||||
update check.
|
||||
- `update`: Gitea Releases client for the CLI only.
|
||||
|
||||
## The six corrections
|
||||
|
||||
### 1. Rayleigh/Schuster, not pure Lomb–Scargle
|
||||
|
||||
Event timestamps are a one-dimensional point process: there is no `y` value to
|
||||
fit. The primary periodogram is therefore Rayleigh/Schuster:
|
||||
|
||||
```text
|
||||
P(f) = |sum_k exp(2*pi*i*f*t_k)|^2 / N
|
||||
```
|
||||
|
||||
Generalized Lomb–Scargle is used only when a real `y` exists (for example bytes per bucket).
|
||||
This avoids inventing a dependent variable and keeps the null distribution
|
||||
honest.
|
||||
|
||||
### 2. Bowley skew with an explicit sentinel
|
||||
|
||||
The Bowley coefficient uses quartiles. When `Q3 == Q1`, the denominator is zero;
|
||||
the implementation returns a documented sentinel (`0.0` with an
|
||||
`degenerate_quartiles` evidence flag) instead of `NaN`, infinity or a panic. The
|
||||
sentinel is part of the alert record, not a silent fallback.
|
||||
|
||||
### 3. Jensen–Shannon, not raw KL
|
||||
|
||||
KL diverges when the reference distribution has a zero where the observed
|
||||
distribution does not. Fusion uses Jensen–Shannon, which is symmetric, bounded
|
||||
and defined for zero-probability bins with a small documented smoothing floor.
|
||||
This makes the score comparable across pillars and safe for sparse protocol
|
||||
histograms.
|
||||
|
||||
### 4. Persistent sessions get their own detector
|
||||
|
||||
A connection that stays open for hours never produces a short inter-arrival
|
||||
time, so a beaconing detector can miss it entirely. Pillar 2 scores duration,
|
||||
idle gaps and repeated long-lived flows directly. The two pillars may both fire;
|
||||
fusion treats that as separate evidence, not double counting of the same signal.
|
||||
|
||||
### 5. JA4 license caution
|
||||
|
||||
The client TLS JA4 fingerprint is usable. JA4S, JA4H, JA4X, JA4SSH and JA4L
|
||||
carry a non-OSI license and are **not** enabled by default. Any future use needs
|
||||
an explicit licensing decision and a documented opt-in. The default feature set
|
||||
must remain redistributable under MIT/Apache-2.0.
|
||||
|
||||
### 6. Determinism and per-alert JSON evidence
|
||||
|
||||
Every alert carries a JSON record: dataset hash, code version, pillar, inputs,
|
||||
intermediate values, sentinels, weights and final score. Reductions run in a
|
||||
fixed order; no hash-map iteration or thread scheduling may change a score.
|
||||
Given the same input and version, the evidence must be byte-identical.
|
||||
|
||||
## Data flow
|
||||
|
||||
1. `acaua analyze <dir>` validates the directory, reads supported logs and
|
||||
normalizes events. In this skeleton it validates and returns a stub report.
|
||||
2. Normalized events are written to the local store (when the `duckdb` feature
|
||||
is enabled) with a seven-day TTL.
|
||||
3. Each pillar runs over a deterministic window and returns candidate scores
|
||||
with evidence.
|
||||
4. Fusion combines candidates, applies thresholds and writes alerts.
|
||||
5. `serve` exposes the API and the embedded UI; the Tauri shell can open the same
|
||||
UI against a local or remote daemon.
|
||||
|
||||
## API
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| GET | `/api/health` | Liveness and version |
|
||||
| GET | `/api/status` | Uptime, data directory, pillar state |
|
||||
| GET | `/api/alerts` | Paginated alerts with evidence |
|
||||
| POST | `/api/analyze` | Analyze a dataset path |
|
||||
| POST | `/api/update` | Check for a CLI update |
|
||||
| GET | `/logo.png` | Embedded brand asset |
|
||||
| GET | `/*` | Embedded UI fallback |
|
||||
|
||||
`serve` binds to `127.0.0.1:8787` by default. There is no authentication layer in
|
||||
the skeleton; exposing it on a network interface requires an authenticating
|
||||
reverse proxy.
|
||||
|
||||
## Storage
|
||||
|
||||
DuckDB is an **optional** dependency (`features = ["duckdb"]`, `bundled`). The
|
||||
default skeleton does not compile the C++ backend. When enabled, the schema is
|
||||
append-only normalized events plus an alerts table, with Parquet export and a
|
||||
seven-day retention job. The database file lives under the configured data
|
||||
directory and never outside it.
|
||||
|
||||
## Updates
|
||||
|
||||
`update.rs` queries the Gitea Releases API for the `acaua` repository, selects
|
||||
the asset for the current platform, downloads over HTTPS with `curl`, verifies
|
||||
SHA-256 and replaces the CLI binary. It refuses to update a running GUI
|
||||
automatically; the desktop only reports that a new version exists. This mirrors
|
||||
the Sabiá updater and avoids a second update mechanism.
|
||||
|
||||
The Tauri updater plugin, its `latest.json` manifest, `updater.pubkey` and
|
||||
`createUpdaterArtifacts` are intentionally not used: they would add a second
|
||||
signing and distribution path, and the desktop must not self-update. The single
|
||||
CLI path is easier to audit and keeps release assets to tarballs plus SHA-256.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
An earlier blueprint proposed a Python service with FastAPI and ClickHouse.
|
||||
Both are rejected. A Python service would add a second runtime, packaging burden
|
||||
and a network boundary inside a local-first tool; ClickHouse would add an
|
||||
external server and operational cost for datasets that fit an embedded columnar
|
||||
store. The product is 100% Rust, with Python confined to `research/`.
|
||||
|
||||
## Deployment
|
||||
|
||||
- **Native:** `cargo build --release -p acaua-cli`, then `acaua serve`.
|
||||
- **Desktop:** Tauri bundles for Linux and Windows, built in CI.
|
||||
- **Docker:** a slim runtime image for lab use; see [docker.md](docker.md).
|
||||
|
||||
## Failure behavior
|
||||
|
||||
Malformed input is skipped with a counted, bounded diagnostic. A missing log is
|
||||
not fatal. A corrupt store is reported by `doctor` and never silently recreated
|
||||
over existing data. A failed update leaves the current binary in place.
|
||||
|
||||
## Versioning and compatibility
|
||||
|
||||
SemVer 2.0.0. Evidence JSON carries a schema version. Any change to a score or
|
||||
to the evidence shape is a breaking change for `0.x` minor versions and must be
|
||||
recorded in the changelog.
|
||||
Reference in new issue
Block a user