Lucas RayanandClaude Opus 5.5 2697d15a3e
Release / Plan (reuse the published image?) (push) Successful in 5s
CI / Docker image (build and smoke test) (push) Skipped
CI / Format and clippy (push) Successful in 8m5s
CI / Dependency audit (push) Successful in 13s
CI / Tests (Linux) (push) Successful in 14m3s
Release / ci (push) Successful in 22m8s
Release / Build image (arm64) (push) Successful in 6m37s
Release / Build image (amd64) (push) Successful in 8m56s
Release / Publish tags (push) Successful in 16s
Release / Gitea release (push) Successful in 6s
Release / CLI (linux-x86_64) (push) Successful in 2m34s
Release / CLI (linux-aarch64) (push) Successful in 5m18s
chore(release): 2.1.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 21:26:50 -03:00
2026-11-03 21:26:50 -03:00
2026-11-03 21:26:50 -03:00
2026-11-03 21:26:50 -03:00
2026-11-03 21:26:50 -03:00

Harpia

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

The Harpia dashboard overview: KPI cards, a severity-distribution chart, a top-exposed-hosts chart and a prioritized findings list


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 (no NET_ADMIN); the API, ingestion, diffing engine and web dashboard run completely unprivileged without capabilities. Falls back to an unprivileged nativo-sem-raw TCP-connect engine automatically when CAP_NET_RAW isn'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.

  1. Tiered scheduling: group-based cron expressions with jitter and a shared rate-limiting budget prevent network saturation.
  2. Dual-engine flexibility: the native Rust SYN engine by default, an unprivileged TCP-connect fallback always available, and an optional external nmap adapter planned for deep service discovery.
  3. 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.
  4. 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 nmap adapter yet (profiles with motor = "nmap" fail validation); the nativo raw-SYN engine and the nativo-sem-raw TCP-connect fallback are the only working engines today.
  • Authenticated scans (SSH/WinRM) and active exploit validation are non-goals.
  • The nativo-sem-raw degraded mode is restricted to TCP connect and lacks ICMP/ARP discovery.
  • IPv6 target expansion is limited to prefixes up to /112 or explicit host lists; the raw SYN engine itself only scans IPv4 targets (IPv6 ones fall back to nativo-sem-raw automatically).

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.

S
Description
Continuous attack surface and vulnerability auditing
Readme
13 MiB
0 Stars 1 Watchers 0 Forks
Harpia 2.1.0
Latest
2026-11-04 12:07:52 +00:00
Languages
Rust 79.5%
JavaScript 11.3%
CSS 4.1%
HTML 2.5%
Shell 2.3%
Other 0.3%