readme: v0.2.0.7 with rotation, machine-bound renew, terminal-state alerts
This commit is contained in:
Fimeg
parent
e8afcc7994
commit
216aed7ca9
1 changed files with 149 additions and 404 deletions
607
README.md
607
README.md
|
|
@ -2,69 +2,31 @@
|
|||
|
||||
**Self-hosted update management for operators who own their stack.**
|
||||
|
||||
Cross-platform agents • Web dashboard • Hardware binding • Ed25519 signing • Supply-chain gates • Full error transparency
|
||||
|
||||
```
|
||||
v0.2.0.5 — May 2026 (pre-release)
|
||||
```
|
||||
|
||||
> **NOT YET OFFICIALLY RELEASED** — Tags do not imply stability. We're in flux.
|
||||
> Mass enrollment announcement coming soon. Use at your own risk.
|
||||
|
||||
RedFlag runs in production homelabs and small operator environments today. It is not a beta with disclaimers; it is a working system that the maintainer also runs as their primary update-management plane. Releases are versioned, migrations are idempotent, and the security model is documented in the code, not in marketing copy.
|
||||
|
||||
**What's new in v0.2.0.2:** upstream version-sync subsystem (Repology + endoflife.date adapters, periodic syncer, "Stack Drift" dashboard panel, full CRUD page); aggregated Attention panel surfacing offline agents, failed updates, EOL drift, and recent upstream movement; rate-limiting UI rewritten to the real backend; agent-management token selector that doesn't conflate registration tokens with the install command; idempotent installer that detects existing credentials and skips re-registration; two-axis revocation model locked in; supply-chain package-age gate (Shai-Hulud-class defense). [Full changelog](#-tldr-changelog-dont-trust-the-transport-layer) · [Update instructions](#updating).
|
||||
`v0.2.0.7` — May 2026 · MIT License
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
The update manager is part of your attack surface. Most homelab tooling ignores this. RedFlag doesn't.
|
||||
|
||||
## What It Does
|
||||
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.
|
||||
|
||||
RedFlag lets you manage software updates across all your servers from one dashboard. Track pending updates, approve installs, and monitor some basic system health without SSHing into every machine.
|
||||
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.
|
||||
|
||||
RedFlag implements:
|
||||
- **Hardware binding** - Machine fingerprint prevents token sharing between machines
|
||||
- **Registration tokens** - One-time use tokens for secure agent enrollment
|
||||
- **Refresh tokens** - 90-day sliding window, auto-renewal for active agents
|
||||
- **Ed25519 signing** - All commands and updates cryptographically signed
|
||||
- **SHA-256 hashing** - All tokens hashed at rest
|
||||
- **Rate limiting** - 60 req/min per agent (configurable policies)
|
||||
- **Minimal privileges** - Agents run with least required permissions
|
||||
- **Error transparency** - All errors logged locally with full context (not sanitized)
|
||||
|
||||
**Trust Model:**
|
||||
- Initial agent registration uses token + TLS
|
||||
- Public key fetched and cached on first run (TOFU model)
|
||||
- Hardware fingerprint binding prevents config copying attacks
|
||||
- All subsequent communications verified via Ed25519 signatures
|
||||
ConnectWise charges $50/agent/month. RedFlag doesn't.
|
||||
|
||||
---
|
||||
|
||||
## Screenshots
|
||||
|
||||
| Dashboard | Agent Details | Update Management |
|
||||
|-----------|---------------|-------------------|
|
||||
|  |  |  |
|
||||
|
||||
| Live Operations | History Tracking | Docker Integration |
|
||||
|-----------------|------------------|-------------------|
|
||||
|  |  |  |
|
||||
|  |  |  |
|
||||
|---|---|---|
|
||||
|
||||
<details>
|
||||
<summary><b>More Screenshots</b> (click to expand)</summary>
|
||||
<summary>More screenshots</summary>
|
||||
|
||||
| Heartbeat System | Registration Tokens | Settings Page |
|
||||
|------------------|---------------------|---------------|
|
||||
|  |  |  |
|
||||
|  |  |  |
|
||||
|---|---|---|
|
||||
|
||||
| Linux Update History | Windows Agent Details | Agent List |
|
||||
|---------------------|----------------------|------------|
|
||||
|  |  |  |
|
||||
|
||||
| Windows Update History |
|
||||
|------------------------|
|
||||
|  |
|
||||
|  |  |  |
|
||||
|---|---|---|
|
||||
|
||||
</details>
|
||||
|
||||
|
|
@ -72,178 +34,65 @@ RedFlag implements:
|
|||
|
||||
## Quick Start
|
||||
|
||||
### Server Deployment (Docker)
|
||||
### Server
|
||||
|
||||
```bash
|
||||
# Clone and configure
|
||||
git clone https://github.com/Fimeg/RedFlag.git
|
||||
cd RedFlag
|
||||
cp config/.env.bootstrap.example config/.env
|
||||
docker-compose build
|
||||
docker-compose up -d
|
||||
|
||||
# Access web UI and run setup
|
||||
open http://localhost:31336
|
||||
# Follow setup wizard, then copy generated .env content
|
||||
|
||||
# Restart with new configuration
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
docker-compose build && docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
Open `http://localhost:31336`, complete the setup wizard, then restart:
|
||||
|
||||
### Agent Installation
|
||||
```bash
|
||||
docker-compose down && docker-compose up -d
|
||||
```
|
||||
|
||||
**Linux (one-liner):**
|
||||
### Agent
|
||||
|
||||
Get a registration token from **Settings → Token Management**, then:
|
||||
|
||||
**Linux / macOS:**
|
||||
```bash
|
||||
curl -sfL https://your-server.com/install | sudo bash -s -- your-registration-token
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
**Windows:**
|
||||
```powershell
|
||||
& ([scriptblock]::Create((iwr -useb https://your-server.com/install.ps1).Content)) -Token your-registration-token
|
||||
iwr https://your-server.com/install.ps1 | iex your-registration-token
|
||||
```
|
||||
The token is required — the installer will not register without it. (`iwr ... | iex` cannot pass arguments; the scriptblock form is how PowerShell hands the token to the fetched script, the equivalent of Linux's `bash -s -- token`.)
|
||||
|
||||
**macOS (curl):**
|
||||
```bash
|
||||
curl -sfL https://your-server.com/install | sudo bash -s -- your-registration-token
|
||||
```
|
||||
|
||||
**Manual installation:**
|
||||
```bash
|
||||
# Download agent binary
|
||||
wget https://your-server.com/download/linux/amd64/redflag-agent
|
||||
|
||||
# Register and install
|
||||
chmod +x redflag-agent
|
||||
sudo ./redflag-agent --server https://your-server.com --token your-token --register
|
||||
```
|
||||
|
||||
Get registration tokens from the web dashboard under **Settings → Token Management**.
|
||||
|
||||
---
|
||||
|
||||
### Updating
|
||||
## What It Manages
|
||||
|
||||
To update the server stack:
|
||||
| Platform | Package Managers / Scanners |
|
||||
|---|---|
|
||||
| Linux | APT, DNF, Docker (socket) |
|
||||
| Windows | Winget, Windows Update (COM), Docker (socket) |
|
||||
|
||||
```bash
|
||||
git pull && docker-compose down && docker-compose build --no-cache && docker-compose up -d
|
||||
```
|
||||
|
||||
#### Agent self-update
|
||||
|
||||
Agents accept an `update_agent` command from the dashboard. The flow:
|
||||
download → SHA-256 → Ed25519 signature → atomic binary swap → service restart.
|
||||
Completion is reconciled server-side once the new binary reports its version.
|
||||
|
||||
**Requires a real service manager on the agent host** — Linux: `systemd` (unit
|
||||
`redflag-agent`); Windows: SCM (service `RedFlagAgent`). Container-only agent
|
||||
deployments (no `systemctl`, no `sc`) cannot self-update through this path: the
|
||||
restart command will fail and the deferred rollback restores the previous
|
||||
binary. For containerized agents, redeploy with the new image instead.
|
||||
|
||||
If a self-update times out without the new version attesting (`agent_update`
|
||||
system event with subtype `timed_out`, severity `error`), the previous binary
|
||||
is preserved at `<binary>.bak` on the agent host
|
||||
(`/usr/local/bin/redflag-agent.bak` on Linux,
|
||||
`C:\Program Files\RedFlag\redflag-agent.exe.bak` on Windows). Restore manually
|
||||
and restart the service.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
<details>
|
||||
<summary><b>Full Reinstall (Nuclear Option)</b></summary>
|
||||
## Trust Model
|
||||
|
||||
If things get really broken or you want to start completely fresh:
|
||||
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.
|
||||
|
||||
```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
|
||||
```
|
||||
On first connect, the agent fetches and caches the server's Ed25519 public key (TOFU). Every subsequent command is verified against it. Keys have TTL-based rotation — agents pre-cache new keys before the old ones expire, so rotation is zero-downtime.
|
||||
|
||||
**What this does:**
|
||||
- `down -v` - Stops containers and **wipes all data** (including the database)
|
||||
- `--remove-orphans` - Cleans up leftover containers
|
||||
- `rm config/.env` - Removes old server config
|
||||
- `build --no-cache` - Rebuilds images from scratch
|
||||
- `cp config/.env.bootstrap.example` - Resets to bootstrap mode for setup wizard
|
||||
- `up -d` - Starts fresh in background
|
||||
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.
|
||||
|
||||
**Warning:** This deletes everything - all agents, update history, configurations. You'll need to handle existing agents:
|
||||
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.
|
||||
|
||||
**Option 1 - Re-register agents:**
|
||||
- Remove agent config: `sudo rm /etc/redflag/agent/config.json` (Linux) or `C:\ProgramData\RedFlag\agent\config.json` (Windows)
|
||||
- Re-run the one-liner installer with new registration token
|
||||
- Scripts handle override/update automatically (one agent per OS install)
|
||||
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. At approval time, OSV.dev is queried for known vulnerabilities in npm and PyPI packages.
|
||||
|
||||
**Option 2 - Clean uninstall/reinstall:**
|
||||
- Uninstall agent completely first
|
||||
- Then run installer with new token
|
||||
**Refresh-token rotation.** Each renewal mints a new refresh token 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.
|
||||
|
||||
</details>
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
<details>
|
||||
<summary><b>Full Uninstall</b></summary>
|
||||
|
||||
**Uninstall Server:**
|
||||
```bash
|
||||
docker-compose down -v --remove-orphans
|
||||
rm config/.env
|
||||
```
|
||||
|
||||
**Uninstall Linux Agent:**
|
||||
```bash
|
||||
# Using uninstall script (recommended)
|
||||
sudo bash aggregator-agent/uninstall.sh
|
||||
|
||||
# Remove agent configuration
|
||||
sudo rm /etc/aggregator/config.json
|
||||
|
||||
# Remove agent user (optional - preserves logs)
|
||||
sudo userdel -r redflag-agent
|
||||
```
|
||||
|
||||
**Uninstall Windows Agent:**
|
||||
```powershell
|
||||
# Stop and remove service
|
||||
Stop-Service RedFlagAgent
|
||||
sc.exe delete RedFlagAgent
|
||||
|
||||
# Remove files
|
||||
Remove-Item "C:\Program Files\RedFlag\redflag-agent.exe"
|
||||
Remove-Item "C:\ProgramData\RedFlag\config.json"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
✓ **Hardware Binding** - Machine fingerprint prevents config copying between agents
|
||||
✓ **Ed25519 Signing** - All updates cryptographically verified before installation
|
||||
✓ **Key Rotation** - TTL-based auto-refresh of signing keys with zero-downtime rotation
|
||||
✓ **Replay Protection** - Signed nonces with 10-minute window prevent command replay
|
||||
✓ **Maintenance Windows** - Schedule when updates can be installed (cron-free day/time config)
|
||||
✓ **Supply Chain Checks** - OSV.dev vulnerability scan at approval time for npm/PyPI packages
|
||||
✓ **Secure by Default** - Registration tokens, JWT auth with refresh, rate limiting
|
||||
✓ **Error Transparency** - All errors logged with full context (no sanitization)
|
||||
✓ **Idempotent Installs** - Re-running installers won't create duplicate agents
|
||||
✓ **Real-time Heartbeat** - Interactive operations with rapid polling mode
|
||||
✓ **Dependency Handling** - Dry-run checks before installing updates
|
||||
✓ **Multi-seat Tokens** - One token can register multiple agents
|
||||
✓ **Audit Trails** - Complete history of all operations
|
||||
✓ **Proxy Support** - HTTP/HTTPS/SOCKS5 for restricted networks
|
||||
✓ **Native Services** - systemd on Linux, Windows Services on Windows
|
||||
✓ **Self-hosted** - No cloud dependencies, runs entirely on your infrastructure
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -254,261 +103,157 @@ Remove-Item "C:\ProgramData\RedFlag\config.json"
|
|||
│ Web Dashboard │ React + TypeScript
|
||||
│ Port: 31336 │
|
||||
└────────┬────────┘
|
||||
│ HTTPS + JWT Auth + Machine Binding
|
||||
│ HTTPS + JWT + Machine Binding
|
||||
┌────────▼────────┐
|
||||
│ Server (Go) │ PostgreSQL
|
||||
│ Port: 31337 │ Ed25519 Signing Service
|
||||
│ Server (Go) │ PostgreSQL · Ed25519 Signing Service
|
||||
│ Port: 31337 │
|
||||
└────────┬────────┘
|
||||
│ Pull-based (agents check in every 5 min)
|
||||
┌────┴────┬────────┐
|
||||
│ │ │
|
||||
┌───▼──┐ ┌──▼──┐ ┌──▼───┐
|
||||
│Linux │ │Windows│ │Docker│
|
||||
│Agent │ │Agent │ │Agent │
|
||||
└──────┘ └───────┘ └──────┘
|
||||
└─ APT └─ WUA └─ Images
|
||||
└─ DNF └─ Winget
|
||||
│ Pull-based (agents check in, not the reverse)
|
||||
├──────────────────┐
|
||||
┌────────▼────────┐ ┌──────▼──────────┐
|
||||
│ Linux Agent │ │ Windows Agent │
|
||||
│ │ │ │
|
||||
│ APT / DNF │ │ Winget / WUA │
|
||||
│ Docker socket │ │ Docker socket │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**Key Security Flow:**
|
||||
1. Agent registers with machine fingerprint + public key
|
||||
2. Server stores hardware binding in database
|
||||
3. Every agent request validated against stored fingerprint
|
||||
4. Commands signed with server Ed25519 private key
|
||||
5. Agent verifies signature + nonce + timestamp before execution
|
||||
6. All updates have checksum verification + rollback on failure
|
||||
---
|
||||
|
||||
### Binary Integrity: Closing the Cold-Start Gap
|
||||
## Features
|
||||
|
||||
The update pipeline runs as root and executes downloaded binaries. That makes the
|
||||
binary itself a trust boundary, not just the transport. RedFlag verifies the agent
|
||||
binary at every stage of its life:
|
||||
|
||||
- **Install time (cold start).** The installer fetches a signed *release manifest* —
|
||||
one Ed25519-signed document listing the expected SHA-256 of every released binary
|
||||
per platform/architecture, signed with the same key the agent trusts. Before it
|
||||
executes anything, the installer verifies the manifest signature and confirms the
|
||||
downloaded binary's hash matches the manifest entry. Any mismatch removes the
|
||||
binary and aborts. This closes the gap where a first install would run an
|
||||
unverified binary.
|
||||
- **Upgrade time.** Self-upgrade verifies SHA-256 + Ed25519 signature before the
|
||||
atomic binary swap, with rollback to the previous binary on failure.
|
||||
- **Runtime.** A small, privileged, network-less Rust executor — separate from the Go
|
||||
agent and outside its trust boundary — re-verifies the agent binary's hash. A
|
||||
mismatch stops command issuance and surfaces in the Security Health panel alongside
|
||||
nonce and machine-binding violations.
|
||||
|
||||
**The two-binary payoff.** To run unsigned code on a managed host, an attacker now has
|
||||
to replace *both* the Go agent and the Rust executor — atomically, while the executor
|
||||
is actively watching the agent, before the next check-in reaches the server. That is a
|
||||
different class of problem than swapping a single binary: it takes local root with
|
||||
precise timing, or a compromise of the build-and-signing infrastructure itself — which
|
||||
the capability-token gate already addresses. The defense is layered on purpose, and the
|
||||
layers are independent.
|
||||
- **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, nothing sanitized
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
**Working in production:**
|
||||
- Linux and Windows agent registration and update management
|
||||
- APT, DNF, Winget, Windows Update, Docker image scanning
|
||||
- Dry-run dependency checking
|
||||
- Real-time heartbeat and rapid polling
|
||||
- Ed25519 key rotation and replay protection
|
||||
- Supply chain hash verification and OSV.dev checks
|
||||
- Maintenance windows
|
||||
- Upstream version tracking (GitHub, Gitea, GitLab, Bitbucket, Repology, endoflife.date)
|
||||
- Agent self-update with rollback
|
||||
|
||||
**Known issues:**
|
||||
- Winget detection occasionally misses packages (Windows API limitation)
|
||||
- Some Windows Updates reappear after installation (Windows Update quirk, not ours)
|
||||
- No AUR, Snap, Flatpak, or Homebrew support yet
|
||||
- macOS agent binaries not yet signed
|
||||
- Mobile dashboard is usable, not optimized
|
||||
|
||||
---
|
||||
|
||||
## Current Status
|
||||
## Updating
|
||||
|
||||
**What Works:**
|
||||
- ✅ Linux and Windows agent registration and updates
|
||||
- ✅ Update scanning for APT, DNF, Winget, Windows Update, Docker
|
||||
- ✅ Dry-run dependency checking before installation
|
||||
- ✅ Real-time heartbeat and rapid polling
|
||||
- ✅ Multi-seat registration tokens
|
||||
- ✅ Native service integration (systemd, Windows Services)
|
||||
- ✅ Web dashboard with full agent management
|
||||
- ✅ Maintenance windows for scheduling installs
|
||||
- ✅ Ed25519 key rotation and replay attack protection
|
||||
- ✅ Supply chain vulnerability check (OSV.dev) for npm/PyPI packages at approval time
|
||||
```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, nothing sanitized
|
||||
- **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 sanitized into a generic failure message.
|
||||
|
||||
Built for operators who'd rather own the problem than outsource it.
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
**v0.2.0.7 (May 2026)**
|
||||
- Refresh-token rotation with accept-previous-once crash-recovery grace
|
||||
- Machine-bound renewal path closes stolen-config.json replay attack
|
||||
- Typed sentinel errors for auth failures in agent polling loop
|
||||
- Loud terminal-state detection: revoked refresh tokens and machine-ID mismatches surface as critical events, not silent retries
|
||||
- No-more-unsigned-binaries: signing-disabled path removed from orchestrator; unsigned fallback removed from download handler
|
||||
|
||||
**v0.2.0.6 (May 2026)**
|
||||
- Agent cold-start trust root: signed release manifest verified before first binary execution
|
||||
- Supply-chain hash registry (Layer 1): expected SHA-256 stored server-side, verified by agents before install
|
||||
- Drift → UpdatePackage bridge: drifted bindings automatically create pending update packages
|
||||
- Upstream tracking UI with release-source adapters (GitHub, Gitea, GitLab, Bitbucket)
|
||||
- Attention panel: surfaces offline agents, failed updates, EOL drift, upstream movement
|
||||
|
||||
**v0.2.0.0 (May 2026)**
|
||||
- Maintenance windows for scheduling/gating installs
|
||||
- OSV.dev supply chain checks at approval time (npm/PyPI)
|
||||
- Ed25519 key rotation with TTL-based auto-refresh
|
||||
- Command signing v3: agent_id binding prevents relay attacks
|
||||
- Replay protection via signed nonces (10-minute window)
|
||||
- Semver-aware version comparison
|
||||
- Binary path traversal protection
|
||||
- Machine ID rebind endpoint for hardware migration
|
||||
- 170+ tests across 18 packages
|
||||
- Command lifecycle v2: `received` state, disk-persisted dedup, authenticated binary download
|
||||
|
||||
**v0.1.27 (December 2025)**
|
||||
- Hardware binding with machine fingerprinting
|
||||
- Ed25519 signing for all commands and updates
|
||||
- Error transparency system (ETHOS #1)
|
||||
- Circuit breakers and retry logic
|
||||
- Agent auto-update fully implemented
|
||||
- Rate limiting (60 req/min, configurable)
|
||||
- Command deduplication and idempotency
|
||||
|
||||
**Known Issues:**
|
||||
- Windows Winget detection occasionally misses packages (Windows API limitation)
|
||||
- Some Windows Updates may reappear after installation (known Windows Update quirk)
|
||||
- Limited mobile dashboard optimization (usable but not ideal)
|
||||
- No AUR, Snap, Flatpak, Homebrew scanner support
|
||||
- Frontend is functional but not polished — some pages need UX love
|
||||
- macOS agent binaries not yet signed (build paths enabled, awaiting binary)
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See [LICENSE](LICENSE) for details
|
||||
|
||||
**Third-Party Components:**
|
||||
- Windows Update integration based on [windowsupdate](https://github.com/ceshihao/windowsupdate) (Apache 2.0)
|
||||
|
||||
---
|
||||
|
||||
## Competitive Position
|
||||
|
||||
**Why This Matters:**
|
||||
|
||||
ConnectWise charges $50/agent/month. For 1000 agents, that's **$600,000 per year**.
|
||||
|
||||
RedFlag costs $0/agent/month + the cost of your VM ($50/month).
|
||||
|
||||
That's not a feature difference - that's a **business model disruption**.
|
||||
|
||||
**What ConnectWise can't do** (architectural limitations):
|
||||
- ❌ Hardware binding (their cloud model prevents it)
|
||||
- ❌ Self-hosted by design (they push "MSP Cloud")
|
||||
- ❌ Code transparency (proprietary, can't audit claims)
|
||||
- ❌ Ed25519 cryptographic verification (opaque signing process)
|
||||
- ❌ Supply chain vulnerability checks at install time
|
||||
|
||||
**What RedFlag does** (architectural advantages):
|
||||
- ✅ Hardware fingerprint binding (machine_id + public_key)
|
||||
- ✅ Self-hosted by design (runs entirely on your infrastructure)
|
||||
- ✅ Ed25519 signing throughout with key rotation (verifiable supply chain)
|
||||
- ✅ Replay attack protection (signed nonces, 10-minute window)
|
||||
- ✅ Maintenance windows for gating installs (all, not just a toggle)
|
||||
- ✅ Supply chain vulnerability checks (OSV.dev, npm/PyPI)
|
||||
- ✅ Error transparency (all logs local with full context)
|
||||
- ✅ $600k/year savings (undeniable math)
|
||||
|
||||
**This isn't about replacing ConnectWise feature-for-feature.**
|
||||
|
||||
It's about: **80% of the functionality for 0% of the cost, plus 3 security advantages they literally cannot match without breaking their business model.**
|
||||
|
||||
**Bottom line**: Built from scratch with hardware binding, Ed25519 signing, and complete error transparency. Works for homelabs and small MSPs who value control, privacy, and cost sanity. Enterprises can keep paying their $600k/year. That's fine. Different tools for different needs.
|
||||
|
||||
---
|
||||
|
||||
## Cleanup Instructions (Important for Upgrades)
|
||||
|
||||
### Removing Old Versions (Pre-v0.1.20)
|
||||
|
||||
If you're upgrading from versions older than v0.1.20, old agent installations used different paths. We recommend uninstalling the old version and reinstalling fresh rather than trying to migrate in place — the early-stage migration path is not reliable and a clean reinstall is the supported route. If you have a large fleet (more than ~100 agents) and an in-place migration would be valuable for you, please reach out and we'll work with you on it.
|
||||
|
||||
**Old Agent Locations (to remove if present):**
|
||||
- `/etc/aggregator/` - Old agent configuration directory
|
||||
- `/etc/redflag/` - Old configuration (moved to `/etc/redflag-agent/`)
|
||||
- `/usr/local/bin/aggregator-agent` - Old binary location
|
||||
- `/var/lib/aggregator/` - Old data directory
|
||||
|
||||
**New Agent Locations (v0.1.20+):**
|
||||
- `/etc/redflag-agent/` - Agent configuration and keys
|
||||
- `/usr/local/bin/redflag-agent` - Agent binary (Linux)
|
||||
- `C:\Program Files\RedFlag\` - Agent install (Windows)
|
||||
- `/var/lib/redflag-agent/` - Agent data and logs (if used)
|
||||
|
||||
**Cleanup Commands:**
|
||||
```bash
|
||||
# Linux cleanup (if upgrading from old versions)
|
||||
sudo rm -rf /etc/aggregator/
|
||||
sudo rm -rf /usr/local/bin/aggregator-agent
|
||||
sudo rm -rf /var/lib/aggregator/
|
||||
|
||||
# Then install new agent normally
|
||||
curl -sfL https://your-server.com/install | sudo bash -s -- your-token
|
||||
```
|
||||
|
||||
**Windows Cleanup (if upgrading):**
|
||||
```powershell
|
||||
# Remove old agent locations
|
||||
Remove-Item "C:\Program Files\Aggregator\*" -Recurse -ErrorAction SilentlyContinue
|
||||
Remove-Item "C:\ProgramData\Aggregator\*" -Recurse -ErrorAction SilentlyContinue
|
||||
|
||||
# Then install new agent
|
||||
& ([scriptblock]::Create((iwr -useb https://your-server.com/install.ps1).Content)) -Token your-registration-token
|
||||
```
|
||||
|
||||
### Full Fresh Install (Clean State)
|
||||
|
||||
If you want to completely remove everything and start fresh:
|
||||
|
||||
**Option 1: Re-register (preserves most data)**
|
||||
```bash
|
||||
# Remove agent config (keeps logs)
|
||||
sudo rm /etc/redflag-agent/config.json
|
||||
# Or on Windows
|
||||
Remove-Item "C:\ProgramData\RedFlag\config.json"
|
||||
|
||||
# Re-run installer (agent will re-register)
|
||||
curl -sfL https://your-server.com/install | sudo bash -s -- your-new-token
|
||||
```
|
||||
|
||||
**Option 2: Complete removal (start completely fresh)**
|
||||
```bash
|
||||
# Use uninstall script (preserves logs for debugging)
|
||||
sudo bash /usr/local/bin/redflag-agent/uninstall.sh
|
||||
|
||||
# Or manual removal
|
||||
sudo systemctl stop redflag-agent
|
||||
sudo userdel -r redflag-agent # Optional: removes agent user and home directory
|
||||
sudo rm /etc/redflag-agent/config.json
|
||||
sudo rm /usr/local/bin/redflag-agent
|
||||
|
||||
# Then reinstall from scratch
|
||||
curl -sfL https://your-server.com/install | sudo bash -s -- your-new-token
|
||||
```
|
||||
|
||||
**Note**: Re-registering is usually sufficient. Complete removal is only needed if the agent state is corrupted or you want to change the agent user.
|
||||
|
||||
---
|
||||
|
||||
## Homelab Philosophy
|
||||
|
||||
This software follows ETHOS principles:
|
||||
- **Honest** - What you see is what you get
|
||||
- **Transparent** - All errors logged with full context (no sanitization)
|
||||
- **Secure** - Hardware binding, cryptographic verification, local logging
|
||||
- **Open Standards** - No vendor lock-in, self-hosted by design
|
||||
|
||||
Made for homelabbers and small MSPs who:
|
||||
- Value control over their infrastructure
|
||||
- Want cost sanity ($0 vs $600k/year)
|
||||
- Prefer transparency over enterprise marketing
|
||||
- Can handle "alpha software" that actually works
|
||||
|
||||
|
||||
## Project Goals
|
||||
|
||||
RedFlag aims to be:
|
||||
- **Simple** - Deploy in 5 minutes, understand in 10
|
||||
- **Honest** - No enterprise marketing speak, no upsell, just useful software
|
||||
- **Homelab-first** - Built for real use cases, not investor pitches
|
||||
- **Self-hosted** - Your data, your infrastructure
|
||||
|
||||
If you're looking for an enterprise-grade solution with SLAs and support contracts, this isn't it. Passing the buck has to stop somewhere. If you own your infra - this will be sovreign to you.
|
||||
|
||||
---
|
||||
|
||||
**Made with ☕ for homelabbers, by homelabbers**
|
||||
|
||||
---
|
||||
|
||||
## 📜 **TLDR Changelog: Don't trust the transport layer**
|
||||
|
||||
**v0.2.0.0 (May 2026)**:
|
||||
- ✅ Maintenance windows for scheduling/gating install operations
|
||||
- ✅ Supply chain vulnerability checks (OSV.dev) for npm/PyPI at approval time
|
||||
- ✅ Ed25519 key rotation with TTL-based auto-refresh
|
||||
- ✅ Command signing v3: agent_id binding prevents relay attacks
|
||||
- ✅ Replay attack protection via signed nonces (10-minute window)
|
||||
- ✅ Configurable operational timeouts (was 6 hardcoded values)
|
||||
- ✅ Semver-aware version comparison (fixes "0.1.9" > "0.1.22" bug)
|
||||
- ✅ Binary path traversal protection on download endpoints
|
||||
- ✅ Machine ID rebind endpoint for hardware migration recovery
|
||||
- ✅ TD-series refactors: main.go God function split, panic recovery, error transparency
|
||||
- ✅ Test suite: 170+ tests across 18 packages
|
||||
- ✅ Install URL auto-detection: backend uses REDFLAG_PUBLIC_URL, frontend :8080 → :31337
|
||||
- ✅ Setup wizard includes agent-facing URL field with auto-detect
|
||||
- ✅ Command lifecycle v2 (Migration 033): `received` state distinguishes "agent has it" from "lost in flight"; stuck-command re-issuance no longer fires blindly
|
||||
- ✅ Disk-persisted command deduplication: a restarted agent cannot re-execute a command issued within the 4h max-age window
|
||||
- ✅ Agent self-upgrade completion loop: TimeoutService reconciles `is_updating` on version attestation (success) or after threshold (timeout, with system_event)
|
||||
- ✅ Authenticated binary download: agent self-upgrade now reuses JWT + X-Machine-ID for the download endpoint (was unauthenticated, would 401 in production)
|
||||
- ✅ Surfaced MarkCommand* failures: silent warnings → ERROR logs + `should_retry` hint on the response (ETHOS #1)
|
||||
|
||||
**v0.1.27 (Dec 2025, Christmas Release) 🎄**:
|
||||
- ✅ Hardware binding with machine fingerprinting (security differentiator)
|
||||
- ✅ Ed25519 cryptographic signing for all updates (supply chain protection)
|
||||
- ✅ Error transparency system with full context logging (ETHOS #1)
|
||||
- ✅ Circuit breakers and retry logic throughout (reliability)
|
||||
- ✅ Agent auto-update system fully implemented (was marked "placeholder")
|
||||
- ✅ Rate limiting active (60 req/min, configurable)
|
||||
- ✅ Command deduplication and idempotency
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
|
||||
**Third-party:** Windows Update integration based on [windowsupdate](https://github.com/ceshihao/windowsupdate) (Apache 2.0).
|
||||
|
|
|
|||
Loading…
Reference in a new issue