Fimeg/Redflag
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.27 release: Complete implementation

Browse Source 
Features:
- Error logging system with ETHOS #1 compliance
- Command factory pattern with UUID generation
- Hardware binding with machine fingerprint validation
- Ed25519 cryptographic signing for updates
- Deduplication and idempotency for commands
- Circuit breakers and retry logic
- Frontend error logging integration

Bug Fixes:
- Version display using compile-time injection
- Migration 017 CONCURRENTLY issue resolved
- Docker build context fixes
- Rate limiting implementation verified

Documentation:
- README updated to reflect actual implementation
- v0.1.27 inventory analysis added
This commit is contained in:
Fimeg
2025-12-20 13:47:36 -05:00
parent 54c554ac7c
commit 62697df112
19 changed files with 1405 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

446
README.md Normal file
View File

@@ -0,0 +1,446 @@
# 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](#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.1.27 - Alpha Release (Dec 2025)
```
**Latest:** Implemented proper storage metrics subsystem with dedicated table and models. AgentHealth scanner improvements with OS-aware badges and extended defaults. Agent migration system for version management. Error transparency system and hardware binding security. Ed25519 cryptographic signing. Removed 2,369 lines of dead code. Curiously the program stopped working after that... (just kidding). [Update instructions below](#updating).
---
---
## 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 |
|-----------|---------------|-------------------|
| ![Dashboard](Screenshots/RedFlag%20Default%20Dashboard.png) | ![Linux Agent](Screenshots/RedFlag%20Linux%20Agent%20Details.png) | ![Updates](Screenshots/RedFlag%20Updates%20Dashboard.png) |
| Live Operations | History Tracking | Docker Integration |
|-----------------|------------------|-------------------|
| ![Live Ops](Screenshots/RedFlag%20Live%20Operations%20-%20Failed%20Dashboard.png) | ![History](Screenshots/RedFlag%20History%20Dashboard.png) | ![Docker](Screenshots/RedFlag%20Docker%20Dashboard.png) |
<details>
<summary><b>More Screenshots</b> (click to expand)</summary>
| Heartbeat System | Registration Tokens | Settings Page |
|------------------|---------------------|---------------|
| ![Heartbeat](Screenshots/RedFlag%20Heartbeat%20System.png) | ![Tokens](Screenshots/RedFlag%20Registration%20Tokens.jpg) | ![Settings](Screenshots/RedFlag%20Settings%20Page.jpg) |
| Linux Update History | Windows Agent Details | Agent List |
|---------------------|----------------------|------------|
| ![Linux History](Screenshots/RedFlag%20Linux%20Agent%20History%20Extended.png) | ![Windows Agent](Screenshots/RedFlag%20Windows%20Agent%20Details.png) | ![Agent List](Screenshots/RedFlag%20Agent%20List.png) |
| Windows Update History |
|------------------------|
| ![Windows History](Screenshots/RedFlag%20Windows%20Agent%20History%20Extended.png) |
</details>
---
## 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, then copy generated .env content
# Restart with new configuration
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
```
---
<details>
<summary><b>Full Reinstall (Nuclear Option)</b></summary>
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 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
</details>
---
<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
✓ **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: 3000 │
└────────┬────────┘
│ HTTPS + JWT Auth + Machine Binding
┌────────▼────────┐
│ Server (Go) │ PostgreSQL
│ Port: 8080 │ 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
---
## 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
---
## 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 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)
---
## 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)
**What RedFlag does** (architectural advantages):
- ✅ Hardware fingerprint binding (machine_id + public_key)
- ✅ Self-hosted by design (runs entirely on your infrastructure)
- ✅ Ed25519 signing throughout (verifiable supply chain)
- ✅ 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. It it highly recommended to just uninstall the old version (instructions are below... and yet, for some idiotic reason I have tried to implement this early stage migration - but it's not going to work... don't try that unless you like pain, just uninstall, you can't have more than like... 100 agents already yeah? if so... call me) see below:
**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
iwr https://your-server.com/install.ps1 | iex
```
### Full Fresh Install (If Things Are Messy)
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.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