# RedFlag
> **π¨ BREAKING CHANGES IN v0.1.23 - READ THIS FIRST**
>
> **β οΈ ALPHA SOFTWARE - NOT READY FOR PRODUCTION**
>
> This is experimental software in active development. Features may be broken, bugs are expected, and breaking changes happen frequently. Use at your own risk, preferably on test systems only. Seriously, don't put this in production yet.
**Self-hosted update management for homelabs**
Cross-platform agents β’ Web dashboard β’ Single binary deployment β’ No enterprise BS
No MacOS yet - need real hardware, not hackintosh hopes and prayers
```
v0.1.23 - BREAKING CHANGES RELEASE
```
**Latest:** Complete rearchitecture with security hardening, multi-subsystem support, and real metrics. **This is NOT a simple update** - see [Breaking Changes](#breaking-changes) below.
---
## What It Does
RedFlag lets you manage software updates across all your servers from one dashboard. Track pending updates, approve installs, and monitor system health without SSHing into every machine.
**Supported Platforms:**
- Linux (APT, DNF, Docker)
- Windows (Windows Update, Winget)
- Future: Proxmox integration planned
**Built With:**
- Go backend + PostgreSQL
- React dashboard
- Pull-based agents (firewall-friendly)
- JWT auth with refresh tokens
---
## 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 Details | Linux Health Details | Agent List |
|---------------------|----------------------|------------|
|  |  |  |
| Linux Update History | Windows Agent Details | Windows Update History |
|---------------------|----------------------|------------------------|
|  |  |  |
---
## π¨ Breaking Changes & Automatic Migration (v0.1.23)
**THIS IS NOT A SIMPLE UPDATE** - This version introduces a complete rearchitecture from a monolithic to a multi-subsystem security architecture. However, we've built a comprehensive migration system to handle the upgrade for you.
### **What Changed**
- **Security**: Machine binding enforcement (v0.1.22+ minimum), Ed25519 signing required.
- **Architecture**: Single scan β Multi-subsystem (storage, system, docker, packages).
- **Paths**: The agent now uses `/etc/redflag/` and `/var/lib/redflag/`. The migration system will move your old files from `/etc/aggregator/` and `/var/lib/aggregator/`.
- **Database**: The server now uses separate tables for metrics, docker images, and storage metrics.
- **UI**: New approval/reject workflow, real security metrics, and a frosted glass design.
### **Automatic Migration**
The agent now includes an automatic migration system that will run on the first start after the upgrade. Here's how it works:
1. **Detection**: The agent will detect your old installation (`/etc/aggregator`, old config version).
2. **Backup**: It will create a timestamped backup of your old configuration and state in `/etc/redflag.backup.{timestamp}/`.
3. **Migration**: It will move your files to the new paths (`/etc/redflag/`, `/var/lib/redflag/`), update your configuration file to the latest version, and enable the new security features.
4. **Validation**: The agent will validate the migration and then start normally.
**What you need to do:**
- **Run the agent with elevated privileges (sudo) for the first run after the upgrade.** The migration process needs root access to move files and create backups in `/etc/`.
- That's it. The agent will handle the rest.
### **Manual Intervention (Only if something goes wrong)**
If the automatic migration fails, you can find a backup of your old configuration in `/etc/redflag.backup.{timestamp}/`. You can then manually restore your old setup and report the issue.
**Need Migration Help?**
If you run into any issues with the automatic migration, join our Discord server and ask for help.
---
## Quick Start
### Server Deployment (Docker)
```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:3000
# Follow setup wizard to:
# - Generate Ed25519 signing keys (CRITICAL for agent updates)
# - Configure database and admin settings
# - Copy generated .env content to config/.env
# Restart server to use new configuration and signing keys
docker-compose down
docker-compose up -d
```
---
### Agent Installation
**Linux (one-liner):**
```bash
curl -sfL https://your-server.com/install | sudo bash -s -- your-registration-token
```
**Windows (PowerShell):**
```powershell
iwr https://your-server.com/install.ps1 | iex
```
**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
To update to the latest version:
```bash
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:
```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
```
**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 ALL agent config:
- `sudo rm /etc/aggregator/config.json` (old path)
- `sudo rm -rf /etc/redflag/` (new path)
- `sudo rm -rf /var/lib/aggregator/` (old state)
- `sudo rm -rf /var/lib/redflag/` (new state)
- `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:**
```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 ALL agent configuration (old and new paths)
sudo rm /etc/aggregator/config.json
sudo rm -rf /etc/redflag/
sudo rm -rf /var/lib/aggregator/
sudo rm -rf /var/lib/redflag/
# 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"
```
---
## Key Features
β **Secure by Default** - Registration tokens, JWT auth, rate limiting
β **Idempotent Installs** - Re-running installers won't create duplicate agents
β **Real-time Heartbeat** - Interactive operations with rapid polling
β **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
β **Ed25519 Signing** - Cryptographic signatures for agent updates (v0.1.22+)
β **Machine Binding** - Hardware fingerprint enforcement prevents agent spoofing
β **Real Security Metrics** - Actual database-driven security monitoring
---
## Architecture
```
βββββββββββββββββββ
β Web Dashboard β React + TypeScript
β Port: 3000 β
ββββββββββ¬βββββββββ
β HTTPS + JWT Auth
ββββββββββΌβββββββββ
β Server (Go) β PostgreSQL
β Port: 8080 β
ββββββββββ¬βββββββββ
β Pull-based (agents check in every 5 min)
ββββββ΄βββββ¬βββββββββ
β β β
βββββΌβββ ββββΌβββ ββββΌββββ
βLinux β βWindowsβ βLinux β
βAgent β βAgent β βAgent β
ββββββββ βββββββββ ββββββββ
```
---
## Documentation
- **[API Reference](docs/API.md)** - Complete API documentation
- **[Configuration](docs/CONFIGURATION.md)** - CLI flags, env vars, config files
- **[Architecture](docs/ARCHITECTURE.md)** - System design and database schema
- **[Development](docs/DEVELOPMENT.md)** - Build from source, testing, contributing
---
## Security Notes
RedFlag uses:
- **Registration tokens** - One-time use tokens for secure agent enrollment
- **Refresh tokens** - 90-day sliding window, auto-renewal for active agents
- **SHA-256 hashing** - All tokens hashed at rest
- **Rate limiting** - Configurable API protection
- **Minimal privileges** - Agents run with least required permissions
- **Ed25519 Signing** - All agent updates signed with server keys (v0.1.22+)
- **Machine Binding** - Agents bound to hardware fingerprint (v0.1.22+)
**File Flow & Update Security:**
- All agent update packages are cryptographically signed
- Setup wizard generates Ed25519 keypair during initial configuration
- Agents validate signatures before installing any updates
- File integrity verified with checksums and signatures
- Controlled file flow prevents unauthorized updates
For production deployments:
1. Complete setup wizard to generate signing keys
2. Use HTTPS/TLS
3. Configure firewall rules
4. Enable rate limiting
5. Monitor security metrics dashboard
---
## Current Status
**What Works:**
- β
Cross-platform agent registration and updates
- β
Update scanning for all supported package managers
- β
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
- β
Docker integration for container image updates
**Known Issues:**
- Windows Winget detection needs debugging
- Some Windows Updates may reappear after installation (known Windows Update quirk)
**Planned Features:**
- Proxmox VM/container integration
- Agent auto-update system
- Mobile-responsive dashboard improvements
---
## Development
```bash
# Start local development environment
make db-up
make server # Terminal 1
make agent # Terminal 2
make web # Terminal 3
```
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed build instructions.
---
## Alpha Release Notice
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!
---
## 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)
---
## Project Goals
RedFlag aims to be:
- **Simple** - Deploy in 5 minutes, understand in 10
- **Honest** - No enterprise marketing speak, 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. If you want to manage updates across your homelab without SSH-ing into every server, welcome aboard.
---
**Made with β for homelabbers, by homelabbers**