mar0ls/bladedr repository overview

⁠bladedr

Agentless threat detection and response for Linux, with an optional eBPF tier.

The control plane scans Linux hosts over SSH: it uploads a static probe, the probe reads a /proc snapshot and evaluates rules on the host, and the findings come back as JSON. Nothing stays resident on the target. Rules are YAML + CEL, so detections are data, not code.

Source, issues and full documentation: https://github.com/mar0ls/bladedr⁠

⁠Run it

# Once: mint the key that seals SSH credentials, and keep it.
docker run --rm mar0ls/bladedr:0.9.0 -keygen
# -> BLADEDR_NODE_KEY=vfnC5oTH…   # private (node) — keep secret

docker run -p 127.0.0.1:8080:8080 \
  -e BLADEDR_DATABASE_URL=postgres://bladedr:pass@db:5432/bladedr \
  -e BLADEDR_NODE_KEY=vfnC5oTH… \
  mar0ls/bladedr:0.9.0

A complete stack with the database is in docs/compose.example.yml⁠.

Pin the version. latest moves on the next release, and this is the component holding SSH access to your fleet.

On first start with no BLADEDR_ADMIN_PASSWORD, the server generates an admin password and prints it once to the log. That password must be changed at first sign-in — until it is, every route returns 403 except the change itself.

⁠What is in the image

• bladedr-server — the control plane and web console
• bladectl — script-friendly API client
• the agentless probe and the eBPF sensor, both prebuilt for linux/amd64 and linux/arm64, so the server can push either without a toolchain
• ~85 builtin detection rules, compiled in

Multi-arch (linux/amd64, linux/arm64), ~46 MB, runs as uid 10001, with a healthcheck on /readyz that also verifies the database is reachable. Images carry build provenance and an SBOM.

⁠What you supply

A database. Use ParadeDB, not stock PostgreSQL — free-text search over observations relies on its BM25 index. Without BLADEDR_DATABASE_URL the server keeps everything in memory and loses it on restart, which is fine for a look around and not for anything else.

A node key. BLADEDR_NODE_KEY decrypts sealed SSH credentials. Generate it once with -keygen and back it up separately from the database: lose it and every stored credential is unrecoverable, by design — the database alone cannot decrypt them.

eBPF policies, if you want the sensor tier. /etc/bladedr/policies is deliberately empty. bladedr does not publish a Tetragon policy bundle yet, so mount your own; a written and kernel-tested set is planned for a later release. Agentless scanning is unaffected.

⁠Configuration

The full table is in the README⁠.

⁠Before you expose it

As configured above the server speaks plaintext HTTP and is published on loopback only. Put a reverse proxy in front of it or give it a certificate. Behind a proxy, also set BLADEDR_TRUSTED_PROXY_CIDRS — without it X-Forwarded-For is ignored, which is the safe default but means the login lockout and the audit log will attribute everything to the proxy.

GET /healthz, /readyz and /metrics are unauthenticated by design, for probes and scrapers. Keep them on an internal interface.

⁠Stability

0.9.x is pre-1.0. Agentless scanning, the rule engine, storage, auth and the REST API are the settled parts. The eBPF sensor and response actions are Beta — response actions in particular run root commands on monitored hosts and have not been proven on a real fleet yet. Risk scoring is experimental and only ever reorders the queue; it never suppresses a finding.

Details, including the /api/v1 compatibility rules: docs/stability.md⁠.

⁠Upgrading

Migrations apply automatically at startup, so an upgrade is: pull the new tag, restart. Downgrades are not supported — snapshot the database before a major bump.

Upgrading to 0.9.0 logs everyone out once. Sessions used to be stored as the bearer token itself and are digests now, and a plaintext token cannot be turned into its own hash. Nothing else is dropped. Read the upgrade notes in CHANGELOG.md⁠ first.

⁠Security

Report vulnerabilities privately through GitHub Security Advisories, not public issues: SECURITY.md⁠.