Self-hosted update management for operators who own their stack.

v0.2.3.1 — June 2026 · MIT License

You're early — nearly 600 of you cloned this before it was announced. A stable release is coming soon, bringing Windows support back fully gated. If you want it to keep existing, sponsor the work.

The software that patches your fleet runs as root on every box. XZ Utils came through a build pipeline. SolarWinds came through an update. The update manager is part of your attack surface — most homelab tooling ignores that. RedFlag treats it as the attack surface it is.

Every command the server issues is Ed25519-signed. Agents verify the signature, check the nonce, validate the timestamp, and reject anything they've seen before. The signing key never leaves your server. Hardware binding means a stolen agent config doesn't work on a different machine. You can read the security model in the code, not in marketing copy.

The supply-chain gate goes deeper: when an update is approved, the server resolves the full dependency closure, checks every transitive artifact against OSV.dev, and mints a signed capability token binding the exact artifact hashes. A network-less privileged executor verifies the signature and every hash before anything installs — it can't reach out and can't be redirected. A known vulnerability anywhere in the closure is a full stop: the operator must override with a documented reason, or the token is never minted. The signing and hash verification have no skip path.

It also just manages your updates — across Linux and Windows, including Docker containers running on those hosts — from a single dashboard, with a human approval step before anything gets installed.

ConnectWise charges $50/agent/month. RedFlag doesn't.

More screenshots

Quick Start

Server

git clone https://github.com/Fimeg/RedFlag.git
cd RedFlag
cp config/.env.bootstrap.example config/.env
docker-compose build && docker-compose up -d

Open http://localhost:31336, complete the setup wizard, then restart:

docker-compose down && docker-compose up -d

Agent

Get a registration token from Settings → Token Management, then:

Linux / macOS:

curl -sfL https://your-server.com/install | sudo bash -s -- your-registration-token

Windows:

iwr https://your-server.com/install.ps1 | iex your-registration-token

What It Manages

Agents run at the OS level and query the Docker socket directly — there's no separate container agent. Agents are pull-based: they check in every 5 minutes and execute what the server has approved. The server never initiates a connection.

Trust Model

Agents register with a one-time token plus a hardware fingerprint. The server stores the fingerprint; future check-ins that don't match the registered machine are rejected. This prevents config copying between hosts.

On first connect, the agent fetches and caches the server's Ed25519 public key (TOFU). Every subsequent command is verified against it. The signing_keys table supports multiple concurrent active keys for zero-downtime rotation: a new key is promoted to primary while the previous key remains active (still verifies commands) until the operator deprecates it through the dashboard. Agents cache keys by key_id fingerprint and re-fetch when they see an unknown signer — no coordinated agent restart required. The signing key roster and deprecation controls live at Settings → Security → Key Management.

Every command includes a signed nonce with a 10-minute validity window. The agent tracks executed nonces and rejects replays, including from an attacker who intercepted a valid command.

Agent-server communication runs over HTTPS. The Ed25519 signing model is a defense-in-depth layer on top of that — commands can't be forged or replayed even if traffic is somehow intercepted or TLS is terminated at a proxy. The signing model doesn't assume the transport is trustworthy. Cert pinning and enforced TLS verification are on the roadmap.

Before a package is installed: the agent fetches the expected SHA-256 from the server, downloads the artifact, verifies the hash. Mismatch blocks the install. OSV.dev is queried for known vulnerabilities at discovery time (async, deduped) for npm, PyPI, apt, and dnf packages — results are visible in the dashboard before approval. The resolved dependency closure is checked too: every transitive artifact the capability token would authorize is queried before the token is minted, not just the package you named.

Refresh-token rotation (90-day TTL). Each renewal mints a new refresh token (90-day expiry) and marks the old one consumed. Replaying a consumed token whose successor was also consumed means theft — the server revokes the entire token family and logs a security event. Agent crash-before-save is covered by accept-previous-once grace: a consumed token whose successor is still unconsumed gets a fresh one, not a revocation.

Machine-bound renewal. The renewal endpoint now checks X-Machine-ID against the registered host, exactly as command endpoints do. A stolen config.json cannot mint access tokens from an unregistered machine — a mismatch returns 403 with a logged machine_id_mismatch security event. The agent surfaces this as a critical event, not a quiet backoff.

Security Health is surfaced as a dashboard panel on each agent — signing status, nonce protection, machine binding violations, command validation — so the posture is visible without digging through logs.

Architecture

┌─────────────────┐
│  Web Dashboard  │  React + TypeScript
│  Port: 31336    │
└────────┬────────┘
         │ HTTPS + JWT + Machine Binding
┌────────▼────────┐
│  Server (Go)    │  PostgreSQL · Ed25519 Signing Service
│  Port: 31337    │
└────────┬────────┘
         │ Pull-based (agents check in, not the reverse)
         ├──────────────────┐
┌────────▼────────┐  ┌──────▼──────────┐
│   Linux Agent   │  │  Windows Agent  │
│                 │  │                 │
│  APT / DNF      │  │  Winget / WUA   │
│  Docker socket  │  │  Docker socket  │
└─────────────────┘  └─────────────────┘

Features

• Approval workflow — updates queue for human review before anything runs
• Maintenance windows — day/time gates on when installs can proceed
• Upstream tracking — polls GitHub, Gitea, GitLab, Bitbucket for new releases; flags EOL drift
• Drift detection — knows what should be installed vs. what is, bridges the gap into update packages
• Agent self-update — SHA-256 → signature → atomic binary swap → service restart, reconciled server-side
• Dependency dry-run — checks before installing, not after
• Idempotent installer — re-running won't create duplicate agents
• Proxy support — HTTP/HTTPS/SOCKS5 for restricted networks
• Native services — systemd on Linux, Windows Services on Windows
• Full audit trail — all operations logged with context, sanitized against log injection

Status

Compiles, runs on the maintainer's stack, not yet battle-tested. No live deployment outside the dev environment. The gate (supply-chain verification) has not completed a full end-to-end run against real infrastructure. Treat everything below as "implemented and locally exercised, not production-proven."

Implemented:

• Linux and Windows agent registration and update management
• APT, DNF, Winget, Windows Update, Docker image scanning
• Package state machine with enforced transitions and lifecycle orchestrator
• Dry-run dependency checking with full closure resolution
• Supply chain gate: OSV batch checks across transitive closures, vuln-is-a-full-stop enforcement, audited override path
• Ed25519 key rotation and replay protection
• Maintenance windows
• Upstream version tracking (GitHub, Gitea, GitLab, Bitbucket, Repology, endoflife.date)
• Agent self-update via privileged helper (zero agent sudo)
• Real-time heartbeat and rapid polling

Not yet done:

• Live end-to-end gate test (GATE-002)
• Windows installer stubs report fake success (CRITICAL-004)
• No AUR, Snap, Flatpak, or Homebrew support
• macOS agent binaries not signed
• Mobile dashboard usable, not optimized

Updating

git pull && docker-compose down && docker-compose build --no-cache && docker-compose up -d

Agent self-update runs from the dashboard. Requires a real service manager (systemd on Linux, SCM on Windows). Container-only agent deployments can't self-update through this path — redeploy with the new image instead.

If a self-update times out, the previous binary is preserved at <binary>.bak on the agent host. Restore manually and restart the service.

docker-compose down -v --remove-orphans && \
  rm config/.env && \
  docker-compose build --no-cache && \
  cp config/.env.bootstrap.example config/.env && \
  docker-compose up -d

sudo rm -rf /etc/aggregator/ /usr/local/bin/aggregator-agent /var/lib/aggregator/

Philosophy

RedFlag follows ETHOS:

• Honest — what you see is what you get
• Transparent — errors logged with full context, sanitized against injection
• Secure — hardware binding, cryptographic verification, local-only logging
• Open standards — no vendor lock-in, no cloud dependency, no telemetry

The maintainer runs this on their own infrastructure. Releases are versioned, migrations are idempotent. If something breaks, the error shows up in full — not swallowed into a generic failure message. Log output is sanitized against injection (ANSI stripping, control character replacement, field truncation) but the content is preserved.

Built for operators who'd rather own the problem than outsource it.

Sponsorship & Consulting

I build systems that organizations actually own: cryptographically secured, self-hosted, and auditable. I weave this infrastructure in the open so you can own your stack, free from the extortion of vendor lock-in.

The code is yours, but keeping the forge lit requires fuel. If this system defends your fleet and saves your treasury — like eliminating $600K/year in RMM fees — consider sponsoring the work.

Hire the Architect

I am a Systems Architect with 25 years on the frontier. I build sovereign agent runtimes in Rust and resurrect dead datacenters from the ashes of ransomware strikes. I am available for anyone whose genuine purpose is the betterment of humanity:

• Full-Time Campaigns: Joining a team to build sovereign AI, high-trust infrastructure, or federated networks.
• Consulting Expeditions ($175/hr): Hands-on architecture, network engineering, and system hardening.
• Incident Response ($250/hr): Ransomware restoration, AD/DNS rebuilds, and pulling your servers back from the void.

Contact: casey@samaritansolutions.net | LinkedIn | GitHub Sponsors | Discord

Changelog

See CHANGELOG.md for the full history. Recent highlights:

v0.2.3.1 — Supply chain gate hardened: vuln in the dependency closure is a full stop at approval. Audited operator override path. Ack tracking fixed (no more 34-deep recycling).

v0.2.3.0 — OSV batch checks across full dependency closures. DNF dry-run detection fix. Auto-confirm frisks the whole closure.

v0.2.2.0 — Package state machine enforced. Lifecycle orchestrator foundation. Vulnerability dashboard.

v0.2.1.1 — Zero-sudo agent. Helper self-upgrade. OSV expansion to apt/dnf. Staging page.

v0.2.1.0 — Token-is-the-command. Helper privilege split. DiscoveryRunner. Installer interface shrunk to 4 methods.

v0.2.0.7 — Refresh-token rotation. Machine-bound renewal. No unsigned binaries.

License

MIT — see LICENSE.

Third-party: Windows Update integration based on windowsupdate (Apache 2.0).