revelio-agent

Go scanner agent for Revelio — runs on a customer's Linux server, executes security posture checks, and POSTs findings to revelio-api.

Status: Paused 2026-04-12. Code-complete through Phase 4. Deployment blocked on Revelio launch decision.

What it does

Runs a batch of checks against the local system and produces a scan report:

• SSH config — password auth, root login, X11 forwarding, etc. (parses sshd -T)
• Firewall — UFW status and rule enforcement
• Listening ports / services — unexpected services bound publicly
• Permissions — SUID binaries, world-writable files, sensitive file modes
• Users — login shells, authorized keys, sudoers
• Packages — pending security upgrades

Each check returns Finding records (severity, description, remediation, evidence). The runner assembles them into a JSON scan report and either prints it or POSTs it to the API.

Run modes

revelio scan                  # one-shot, prints results to stdout
revelio scan --report         # one-shot, submits to API
revelio init                  # interactive wizard: writes /etc/revelio/revelio.yaml (0600)
revelio install-timer         # enables systemd timer (hourly with randomized delay)

Stack

• Go (stdlib for almost everything; gopkg.in/yaml.v3 for config)
• GoReleaser for linux/amd64 + linux/arm64 releases with SHA256 checksums
• init() registration pattern — each check file self-registers into the runner

Security model

Running a scanner on customer systems means the agent is itself a high-value target. Hardening:

• Runs as unprivileged user — no root required (reads configs, runs safe commands like sshd -T, ufw status, ss -tlnp)
• All exec.Command calls use explicit argument arrays, never shell interpolation
• Every command execution has a timeout (no hangs on unresponsive systems)
• HTTPS-only API communication — refuses HTTP endpoints (hardcoded, not configurable)
• TLS 1.2+ minimum, explicit MinVersion: tls.VersionTLS12
• Retry with exponential backoff + jitter (3 attempts: 2s/4s/8s)
• Config file at /etc/revelio/revelio.yaml is forced to 0600; warns on startup if group/world-readable
• API key masked in all debug output (rvl_agt_...a3f2), never logged plaintext
• Evidence fields truncated to 4KB to bound memory and API request size
• GoReleaser produces signed SHA256 checksums for install-time verification

Config (revelio.yaml)

api:
  endpoint: "https://api.revelio.watch"
  key: "rvl_agt_..."

checks:
  disabled: ["web_headers"]
  ssl:
    domains: ["example.com"]

scan:
  interval: "1h"
  timeout: "5m"

Related

• revelio-api — Cloudflare Workers API backend
• revelio-web — Astro dashboard