RedFlag/README.md

RedFlag

Alpha Release Notice

⚠️ ALPHA SOFTWARE - USE WITH CAUTION

This is actively developed software that works, but continues to evolve. While core functionality is stable, occasional bugs may appear and breaking changes can happen between versions. Suitable for production use cases where you understand the alpha nature and can manage updates. See Current Status below for what's implemented.

This is alpha software built for homelabs and self-hosters. It's functional and actively used, but:

• Expect occasional bugs
• Backup your data
• Security model is solid but not audited
• Breaking changes may happen between versions
• Documentation is a work in progress

That said, it works well for its intended use case. Issues and feedback welcome!

Self-hosted update management for homelabs and small MSPs

Cross-platform agents • Web dashboard • Hardware binding • Ed25519 signing • Full error transparency • No enterprise BS

v0.2.0 - May 2026

Latest: Maintenance windows for gating installs by schedule, OSV.dev supply chain checks for npm/PyPI packages, TD-series security refactors (panic recovery, error transparency, main.go modularization), install URL auto-detection fix, Ed25519 key rotation support, replay attack protection, and the setup wizard now includes the agent-facing URL field. See the changelog below. Update instructions here.

---

---

What It Does

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.

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

---

Screenshots

Dashboard	Agent Details	Update Management

Live Operations	History Tracking	Docker Integration

More Screenshots (click to expand)

Heartbeat System	Registration Tokens	Settings Page

Linux Update History	Windows Agent Details	Agent List

Windows Update History

---

Quick Start

Server Deployment (Docker)

# 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

---

Agent Installation

Linux (one-liner):

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

Windows (PowerShell):

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

Manual installation:

# 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

To update to the latest version:

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

---

Full Reinstall (Nuclear Option)

If things get really broken or you want to start completely fresh:

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

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

Warning: This deletes everything - all agents, update history, configurations. You'll need to handle existing agents:

Option 1 - Re-register agents:

• Remove agent config: sudo rm /etc/aggregator/config.json (Linux) or C:\ProgramData\RedFlag\config.json (Windows)
• Re-run the one-liner installer with new registration token
• Scripts handle override/update automatically (one agent per OS install)

Option 2 - Clean uninstall/reinstall:

• Uninstall agent completely first
• Then run installer with new token

---

Full Uninstall

Uninstall Server:

docker-compose down -v --remove-orphans
rm config/.env

Uninstall Linux Agent:

# 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:

# 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"

---

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

---

Architecture

┌─────────────────┐
│  Web Dashboard  │  React + TypeScript
│  Port: 31336    │
└────────┬────────┘
         │ HTTPS + JWT Auth + Machine Binding
┌────────▼────────┐
│  Server (Go)    │  PostgreSQL
│  Port: 31337    │  Ed25519 Signing Service
└────────┬────────┘
         │ Pull-based (agents check in every 5 min)
    ┌────┴────┬────────┐
    │         │        │
┌───▼──┐  ┌──▼──┐  ┌──▼───┐
│Linux │  │Windows│ │Docker│
│Agent │  │Agent  │ │Agent │
└──────┘  └───────┘ └──────┘
   └─ APT   └─ WUA     └─ Images
   └─ DNF   └─ Winget

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

---

---

Current Status

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

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 macOS agent support (Linux + Windows only)
• No AUR, Snap, Flatpak, Homebrew scanner support
• Frontend is functional but not polished — some pages need UX love

---

License

MIT License - See LICENSE for details

Third-Party Components:

• Windows Update integration based on 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:

# 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):

# 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
iwr https://your-server.com/install.ps1 | iex

Full Fresh Install (Clean State)

If you want to completely remove everything and start fresh:

Option 1: Re-register (preserves most data)

# 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)

# 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 (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