Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Harpia
Continuous attack surface and vulnerability auditing.
Lightweight Rust scanner · local-first · authorized use.
Terminal · Interface · Architecture · Configuration · Docker · Support · Roadmap · Changelog
English · Português
Status: stable, v2.0.1. The full pipeline (raw-socket SYN scanning, TCP-connect fallback, service fingerprinting, CVE/KEV correlation, scoped diffs, the dashboard, the executive report, CSV export, webhook alerts, Prometheus metrics and CI/release) is implemented and has been validated against a real vulnerable target (DVWA) through the actual hardened Docker Compose stack, not just the host binary. The project was renamed from Xexéu to Harpia in 2.0.0. See CHANGELOG.md for exactly what shipped and when.
Harpia is a lightweight continuous attack surface and vulnerability audit daemon for authorized networks. Instead of one-off scans and unorganized XML dumps, Harpia runs continuously via Docker Compose, tracking what is exposed, what changed between sweeps, and what vulnerabilities exist.
- Continuous, not point-in-time: the primary output is the live deduplicated state of your network surface plus an append-only event log of differences (new hosts, closed ports, altered services, remediated CVEs).
- Tiered scan cadences: critical segments (core servers, DMZs) can be scanned frequently (e.g. every 5 minutes), while secondary segments are audited on broader schedules (e.g. daily cron at 03:00), editable live from the dashboard's Groups view, no file editing required.
- Lightweight & local-first: a single Rust binary, embedded SQLite + Parquet storage. No external database, no Python runtime, and no telemetry.
- Deterministic & explainable: every vulnerability finding carries verifiable JSON evidence (raw banner, candidate CPE, matched feed rule, confidence level); timeouts and network congestion are the only documented source of run-to-run variation, unlike traditional
nmap's intermittent flakiness. - Least privilege: containerized with strict privilege separation. Only the packet emitter container receives
NET_RAW(noNET_ADMIN); the API, ingestion, diffing engine and web dashboard run completely unprivileged without capabilities. Falls back to an unprivilegednativo-sem-rawTCP-connect engine automatically whenCAP_NET_RAWisn't usable. - Authorized use by design: explicit authorized scope declaration is mandatory in configuration; out-of-scope targets are strictly rejected.
- Stays fresh on its own: the local CVE/KEV database can sync itself periodically, independently of image or binary updates, the same principle Trivy uses for its own vulnerability database.
What exists today
| Area | State |
|---|---|
Rust workspace and CLI (harpia) |
✅ serve, scanner, scan, config check, feeds, changes, export, doctor |
| Native scan engine | ✅ raw-socket SYN (nativo, CAP_NET_RAW) with automatic fallback to TCP connect (nativo-sem-raw) |
| Service fingerprinting | ✅ HTTP, SSH, TLS certificate, passive banner grab |
| CPE/CVE/KEV correlation | ✅ NVD CVE JSON 2.0 + CISA KEV, offline import or live sync (one-shot or periodic background) |
| Scoped diff & event history | ✅ deterministic, debounced, partial sweeps never produce false disappearances |
| Storage | ✅ SQLite (state) + Parquet (immutable sweep batches) |
| Dashboard & executive report | ✅ embedded vanilla UI (severity palette, SVG charts, group CRUD), A4 Paged.js report at /relatorio |
| CSV / JSON export | ✅ /api/export/*.csv, harpia export, CSV-injection-safe |
| Webhook alerts and Prometheus metrics | ✅ HMAC-signed webhooks (JSON, Slack, Discord) and /metrics |
| Docker Compose topology & hardening | ✅ validated end-to-end against a real target, including the permission boundary between the two containers' users |
| CI/CD (Gitea) | ✅ ci.yml, release.yml, scripts/check.sh, pre-push hook |
| Bilingual documentation | ✅ EN/PT-BR pairs, with real dashboard screenshots |
nmap adapter / harpia-scanner-nmap variant |
🚧 not yet implemented |
| Published releases | ✅ CLI for linux-x86_64 and linux-aarch64 and the container image, on the releases page |
Core principles
Harpia executes an ongoing loop: schedule → scan → identify → historize → expose.
- Tiered scheduling: group-based cron expressions with jitter and a shared rate-limiting budget prevent network saturation.
- Dual-engine flexibility: the native Rust SYN engine by default, an unprivileged TCP-connect fallback always available, and an optional external
nmapadapter planned for deep service discovery. - Safe vulnerability correlation: matches banner-derived CPEs against local NVD CVE JSON 2.0 and CISA KEV feeds, coupled with non-intrusive configuration checks (expired/soon-to-expire TLS certificates, unencrypted administrative ports). No exploits or intrusive payloads are ever sent.
- Change event log: state changes are debounced via a configurable absence threshold (
ausencias_para_sumir) to prevent flapping on packet loss.
Authorized use
Harpia is defensive software designed strictly for networks you own or are explicitly authorized to audit. Scanning third-party infrastructure without permission is illegal. Operators are responsible for scope, compliance, and data retention policies.
The configuration requires an explicit [escopo] block. Any target resolving outside the authorized CIDR ranges is rejected. The API daemon binds to 127.0.0.1 by default; reads are open, and the routes that change the configuration need an admin token (HARPIA_ADMIN_TOKEN, or the one-off link printed at startup). Put it behind an authenticating reverse proxy before exposing it beyond localhost. See SECURITY.md.
Install
Run via Docker Compose (recommended for operators):
cp .env.example .env
mkdir -p config && cp examples/harpia.toml config/harpia.toml
docker compose pull && docker compose up -d
docker compose logs harpia | grep token # one-off admin link, unless HARPIA_ADMIN_TOKEN is set
The image is public: docker pull git.lucasrguerra.dev.br/ciberfauna/harpia:latest.
Or build and run locally with Docker:
docker compose up -d --build
To compile from source natively (just Rust 1.88+, no external library to fetch, SQLite is bundled):
cargo build --release -p harpia-cli
./target/release/harpia --help
Or download the standalone CLI from the releases page (linux-x86_64 and linux-aarch64) and check it against its .sha256:
sha256sum -c harpia-v2.0.1-linux-x86_64.tar.gz.sha256
tar xzf harpia-v2.0.1-linux-x86_64.tar.gz
Supported platform matrix for container images: linux/amd64 and linux/arm64.
Getting started
# Validate your configuration and view effective schedules
harpia config check --config config/harpia.toml
# Start the server daemon and web dashboard
harpia serve --bind 127.0.0.1:8788 --config config/harpia.toml
# Run an ad-hoc diagnostic scan for a specific group
harpia scan --group dmz --once
# Inspect recent surface changes
harpia changes --since 24h
# Diagnose the environment (capabilities, feeds, storage)
harpia doctor
See docs/cli.md for the full command reference.
Development
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
scripts/check.sh
See CONTRIBUTING.md and docs/architecture.md.
Known limits
- No
nmapadapter yet (profiles withmotor = "nmap"fail validation); thenativoraw-SYN engine and thenativo-sem-rawTCP-connect fallback are the only working engines today. - Authenticated scans (SSH/WinRM) and active exploit validation are non-goals.
- The
nativo-sem-rawdegraded mode is restricted to TCP connect and lacks ICMP/ARP discovery. - IPv6 target expansion is limited to prefixes up to
/112or explicit host lists; the raw SYN engine itself only scans IPv4 targets (IPv6 ones fall back tonativo-sem-rawautomatically).
Where it's going
Summary of the ROADMAP:
| Done (2.0.1) | Workspace crates, native SYN/connect scan engines, fingerprinting, CVE/KEV correlation, scoped diffs, SQLite+Parquet storage, dashboard, executive report, CSV export, config CRUD with scanner hot-reload behind an admin token, CI/CD with published image and CLI, property tests and weekly fuzzing, webhook alerts, Prometheus metrics |
| Next | Distribution backport mapping, email alerts |
| Later | nmap adapter and the harpia-scanner-nmap variant, OSV correlation, multi-scanner aggregation |
| Not planned | Exploitation payloads, NASL engine, mandatory cloud services, desktop Tauri wrapper |
License
MIT or Apache-2.0, your choice.

