273 lines
13 KiB
Markdown
273 lines
13 KiB
Markdown
# RedFlag
|
|
|
|
**Self-hosted update management for operators who own their stack.**
|
|
|
|
`v0.2.9.3` — July 2026 · AGPL-3.0
|
|
|
|
> **You're early — over 1,000 of you cloned this before it was announced.**
|
|
> A stable release is coming soon, bringing Windows support back fully gated.
|
|
> I'll be pinning a release version this week to mark the start of stabilization —
|
|
> focused on hardening what's here rather than shipping new features.
|
|
> RedFlag is free and stays free — [here's who builds it, and why](AUTHOR.md).
|
|
|
|
---
|
|
|
|
<!-- Showcase video goes here: terminal → install → multiple agents → updates. -->
|
|
|
|
One dashboard for updates across Linux, Windows, and the Docker containers running on those hosts. Agents check in, scan their package managers, and queue what they find. Nothing installs until a human approves it.
|
|
|
|
What makes RedFlag different: the software that patches your fleet runs as root on every box, which makes it part of your attack surface — XZ Utils came through a build pipeline, SolarWinds came through an update. So every command here is Ed25519-signed and agents reject anything forged or replayed. On APT and DNF, direct package mutation must cross a privileged Rust helper: a short-lived capability binds the host, operation, and artifact entries whose hashes resolved, and the helper validates that authority before executing a fixed argv plan with a cleared environment. Docker, Winget, and Windows Update still use the default-strict signed-command path. The full trust model is in [SECURITY.md](SECURITY.md).
|
|
|
|
ConnectWise charges $50/agent/month. RedFlag doesn't.
|
|
|
|
---
|
|
|
|
|  |  |  |
|
|
|---|---|---|
|
|
|
|
<details>
|
|
<summary>More screenshots</summary>
|
|
|
|
|  |  |  |
|
|
|---|---|---|
|
|
|
|
|  |  |  |
|
|
|---|---|---|
|
|
|
|
|  |  | |
|
|
|---|---|---|
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Server
|
|
|
|
```bash
|
|
git clone https://codeberg.org/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:
|
|
|
|
```bash
|
|
docker-compose down && docker-compose up -d
|
|
```
|
|
|
|
### Agent
|
|
|
|
Get a registration token from **Settings → Token Management**, then:
|
|
|
|
**Linux / macOS:**
|
|
```bash
|
|
curl -sfL -H "X-Registration-Token: your-token" "https://your-server.com/api/v1/install/linux" | sudo bash
|
|
```
|
|
|
|
**Windows:**
|
|
```powershell
|
|
iwr -Headers @{"X-Registration-Token"="your-token"} "https://your-server.com/api/v1/install/windows" | iex
|
|
```
|
|
|
|
---
|
|
|
|
## What It Manages
|
|
|
|
| Platform | Package Managers / Scanners |
|
|
|---|---|
|
|
| Linux | APT, DNF, Docker (socket) |
|
|
| Windows | Winget, Windows Update (COM), Docker (socket) |
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
The update manager *is* attack surface, so it gets treated like one: Ed25519-signed commands with replay protection, hardware-bound agent identity, rotating refresh tokens that burn loudly when stolen, and a separate privileged executor for APT/DNF mutation. The helper checks token version and time, host binding, signature, and replay state, then executes fixed package-manager argv without a shell or inherited environment.
|
|
|
|
The APT/DNF dry-run must resolve the top-level artifact hash before a capability can be minted. Successfully resolved dependency hashes are included, but unresolved dependency hashes can currently be omitted. The helper rehashes artifacts supplied by local path and refuses a missing or mismatched mirror artifact; normal registry entries without local paths are not rehashed helper-side. Its current `systemd-run` unit is short-lived but **not network-isolated**. Complete transitive closure pinning, local custody of every byte, and network isolation remain design work rather than implied guarantees.
|
|
|
|
The full trust model lives in [SECURITY.md](SECURITY.md), including how to report a vulnerability. The architecture and its honest gaps are documented in the RedFlag Architecture Framework (RAF).
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────┐
|
|
│ Server (Go) │ PostgreSQL · Ed25519 Signing Service
|
|
│ Embedded React dashboard │ Dashboard: 31336 · Agent API: 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, Forgejo/Gitea/Codeberg, 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 supply-chain gate has completed an end-to-end run (2026-06-05: `hyprutils` through capability-token minting, helper verification, and install on a live Fedora agent). 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
|
|
- Failed state recovery: reopen, resolve, and transition out of failed
|
|
- Lifecycle history with status badges, version transitions, and failure reasons
|
|
- Scan-set closure reconciler (close-by-absence) — fixes out-of-band false positives
|
|
- Dry-run dependency checking with a mandatory top-level hash and best-effort transitive hash resolution
|
|
- Supply chain gate: OSV batch checks across reported resolved entries, vuln-is-a-full-stop enforcement for the checked set, audited override path
|
|
- Version soak-gating and package age gate as configurable policies
|
|
- Capability-token minting for dnf/apt with Ed25519-signed token verification
|
|
- Ed25519 key rotation and replay protection
|
|
- Maintenance windows
|
|
- Upstream version tracking (GitHub, Forgejo/Gitea/Codeberg, GitLab, Bitbucket, Repology, endoflife.date)
|
|
- Metadata pipeline: CVE details, upstream intelligence, package provenance
|
|
- Auto-discovery bridge (Repology, container registry, exact match)
|
|
- Agent self-update via privileged helper (zero agent sudo)
|
|
- Binary self-update (agent, helper, desktop) through the same signed, hash-pinned capability-token gate as package installs
|
|
- Process explorer: on-demand /proc scanning (sockets, capabilities, namespaces) with inode correlation
|
|
- Setup accepts an operator-supplied signing keypair — bring-your-own-key deployments
|
|
- Reversible token encryption with one-liner restore
|
|
- Real-time heartbeat and rapid polling
|
|
|
|
**Not yet done:**
|
|
- No AUR, Snap, Flatpak, or Homebrew support
|
|
- macOS agent binaries not signed
|
|
- Mobile dashboard usable, not optimized
|
|
- Cert pinning and enforced TLS verification
|
|
- Complete transitive closure hashing for APT/DNF; unresolved dependency hashes can currently be omitted
|
|
- Helper-side rehashing of normal registry artifacts before mutation
|
|
- Network isolation for the privileged helper invocation
|
|
- Capability-helper execution for Docker, Winget, and Windows Update
|
|
|
|
---
|
|
|
|
## Updating
|
|
|
|
```bash
|
|
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.
|
|
|
|
<details>
|
|
<summary>Nuclear option (full reset)</summary>
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
This wipes all data including the database. Re-register agents afterward with new tokens.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Upgrading from pre-v0.1.20</summary>
|
|
|
|
Old installations used different paths. Clean reinstall is the supported migration path.
|
|
|
|
Remove old artifacts if present:
|
|
```bash
|
|
sudo rm -rf /etc/aggregator/ /usr/local/bin/aggregator-agent /var/lib/aggregator/
|
|
```
|
|
|
|
Then install fresh with the standard one-liner.
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Free, Forever
|
|
|
|
RedFlag will never be monetized. No pro tier, no cloud edition, no per-agent pricing — those are the things it exists to replace. This is my resume piece, built in the open and given away, because the update manager is part of everyone's attack surface — not just the orgs with an RMM budget.
|
|
|
|
The architecture documentation — the **RedFlag Architecture Framework (RAF)** — is being published alongside the code: how the system is built, why the design landed where it did, and the pitfalls we think are still out there. Not a guide to attacking it; the reasoning behind the madness, so you can judge the security model yourself instead of trusting a README. I haven't thought of everything — that's part of why it's published.
|
|
|
|
If community adoption takes off, ownership and contribution policies will be made transparent and stay open. This project does not get quietly captured.
|
|
|
|
If RedFlag holds your fleet and you want to give back: [sponsor the work](https://github.com/sponsors/Fimeg), or better — [hire the person who built it](AUTHOR.md).
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
See [CHANGELOG.md](CHANGELOG.md) for the full history. Recent highlights:
|
|
|
|
**v0.2.8.0** — Process explorer, self-update capability tokens, BYO signing keypair at setup, cross-compile CI matrix (linux-arm64, windows-amd64, darwin-arm64).
|
|
|
|
**v0.2.7.1** — CI/CD pipeline on Gitea Actions with release gate and guided release script. Screenshot capability survives self-upgrade.
|
|
|
|
**v0.2.6.8** — Dark/light tray app theme, desktop tray spine, prototype Tauri desktop app.
|
|
|
|
**v0.2.6.5** — Windows agent service logs now write to `C:\ProgramData\RedFlag\logs\agent.log`.
|
|
|
|
**v0.2.6.4** — Windows installer fixes: CRLF, reachable host, port preservation, Ed25519 cold-start tolerance.
|
|
|
|
**v0.2.6.2** — OSV scans moved to detection. Soak gate promoted to real policy. Dead scaffolding retired.
|
|
|
|
**v0.2.6.0** — Metadata pipeline, auto-discovery bridge, Docker enrichment, filter/search primitives.
|
|
|
|
**v0.2.5.1** — Failed state recovery, lifecycle history, reopen/resolve endpoints.
|
|
|
|
**v0.2.5.2** — Reversible token encryption. Idempotent heartbeat auto-queue.
|
|
|
|
**v0.2.3.5** — Unified agent+helper upgrade. Path traversal fixes. Self-update on fresh hosts.
|
|
|
|
**v0.2.3.1** — Supply chain gate hardened: vuln is a full stop. Ack tracking fixed.
|
|
|
|
**v0.2.2.0** — Package state machine enforced. Lifecycle orchestrator foundation.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
AGPL-3.0 — see [LICENSE](LICENSE).
|
|
|
|
**Third-party:** Windows Update integration based on [windowsupdate](https://github.com/ceshihao/windowsupdate) (Apache 2.0).
|