Redflag/docs/4_LOG/_originals_archive.backup/pathtoalpha.md

Path to Alpha Release

Current Reality Check

You're absolutely right - I was suggesting unrealistic manual CLI workflows. Let's think like actual RMM developers and users.

What Actually Exists vs What's Needed

✅ Current Authentication State

• Server uses hardcoded JWT secret: "test-secret-for-development-only"
• Agents register with ANY binary (no verification)
• Development token approach only
• No production security model

❌ Missing Production Deployment Model

• No environment configuration system
• No secure agent onboarding
• No installer automation
• No production-grade security

Realistic RMM Deployment Patterns

Industry Standard Approaches:

1. Ansible/Chef/Puppet Pattern (Enterprise)

# Server setup creates inventory file
ansible-playbook setup-redflag-server.yml
# Generates /etc/redflag/agent-config.json on each target
# Agents auto-connect with pre-distributed config

2. Kubernetes Operator Pattern (Cloud Native)

# CRD for agent registration
apiVersion: redflag.io/v1
kind: AgentRegistration
metadata:
  name: agent-prod-01
spec:
  token: auto-generated
  config: |-
    {"server": "redflag.internal:8080", "token": "rf-tok-xyz..."}

3. Simple Installer Pattern (Homelab/SMB)

# One-liner that downloads and configures
curl -sSL https://get.redflag.dev | bash -s -- --server 192.168.1.100 --token abc123

# Or Windows:
Invoke-WebRequest -Uri "https://get.redflag.dev" | Invoke-Expression

4. Configuration File Distribution (Most Realistic for Us)

# Server generates config files during setup
mkdir -p /opt/redflag/agents
./redflag-server --setup --output-dir /opt/redflag/agents

# Creates:
# /opt/redflag/agents/agent-linux-01.json
# /opt/redflag/agents/agent-windows-01.json
# /opt/redflag/agents/agent-docker-01.json

# User copies configs to targets (SCP, USB, etc.)
# Agent install reads config file and auto-registers

Recommended Approach: Configuration File Distribution

Why This Fits Our Target Audience:

• Self-hosters: Can SCP files to their machines
• Homelab users: Familiar with config file management
• Small businesses: Simple copy/paste deployment
• No complex dependencies: Just file copy and run
• Air-gapped support: Works without internet during install

Implementation Plan:

Phase 1: Server Setup & Config Generation

# Interactive server setup
./redflag-server --setup
? Server bind address [0.0.0.0]:
? Server port [8080]:
? Database host [localhost:5432]:
? Generate agent registration configs? [Y/n]: y
? Output directory [/opt/redflag/agents]:
? Number of agent configs to generate [5]:

✅ Server configuration written to /etc/redflag/server.yml
✅ Agent configs generated:
   /opt/redflag/agents/agent-001.json
   /opt/redflag/agents/agent-002.json
   /opt/redflag/agents/agent-003.json
   /opt/redflag/agents/agent-004.json
   /opt/redflag/agents/agent-005.json

📋 Next steps:
   1. Copy agent config files to your target machines
   2. Run: curl -sSL https://get.redflag.dev | bash
   3. Agent will auto-register using provided config

Phase 2: Agent Configuration File

{
  "server_url": "https://redflag.internal:8080",
  "registration_token": "rf-tok-550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "hostname": "fileserver-01",
  "verify_tls": true,
  "proxy_url": "",
  "log_level": "info"
}

Phase 3: One-Line Agent Install

# Linux/macOS
curl -sSL https://get.redflag.dev | bash

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://get.redflag.dev" | Invoke-Expression

# Or manual install
sudo ./aggregator-agent --config /path/to/agent-config.json

Security Model:

1. Registration tokens are single-use
2. Tokens expire after 24 hours
3. Agent config files contain sensitive data (restrict permissions)
4. TLS verification by default (with option to disable for air-gapped)
5. Server whitelists agent IDs from pre-generated configs

Critical Path to Alpha

Week 1: Core Infrastructure

1. Server Configuration System

   • Environment-based config
   • Interactive setup script
   • Config file generation for agents

2. Secure Registration

   • One-time registration tokens
   • Pre-generated agent configs
   • Token validation and expiration

Week 2: Deployment Automation

3. Installer Scripts

   • One-line Linux/macOS installer
   • PowerShell installer for Windows
   • Docker Compose deployment

4. Production Security

   • Rate limiting on all endpoints
   • TLS configuration
   • Secure defaults

Week 3: Polish & Documentation

5. Deployment Documentation

   • Step-by-step install guides
   • Configuration reference
   • Troubleshooting guide

6. Alpha Testing

   • End-to-end deployment testing
   • Security validation
   • Performance testing

Updated Implementation Plan (UI-First Approach)

Priority 1: Server Configuration System with User Secrets

// Enhanced config.go with user-provided secrets:
type Config struct {
    Server struct {
        Host string `env:"REDFLAG_SERVER_HOST" default:"0.0.0.0"`
        Port int    `env:"REDFLAG_SERVER_PORT" default:"8080"`
        TLS  struct {
            Enabled   bool   `env:"REDFLAG_TLS_ENABLED" default:"false"`
            CertFile  string `env:"REDFLAG_TLS_CERT_FILE"`
            KeyFile   string `env:"REDFLAG_TLS_KEY_FILE"`
        }
    }
    Database struct {
        Host     string `env:"REDFLAG_DB_HOST" default:"localhost"`
        Port     int    `env:"REDFLAG_DB_PORT" default:"5432"`
        Database string `env:"REDFLAG_DB_NAME" default:"redflag"`
        Username string `env:"REDFLAG_DB_USER" default:"redflag"`
        Password string `env:"REDFLAG_DB_PASSWORD"` // User-provided
    }
    Admin struct {
        Username string `env:"REDFLAG_ADMIN_USER" default:"admin"`
        Password string `env:"REDFLAG_ADMIN_PASSWORD"` // User-provided
        JWTSecret string `env:"REDFLAG_JWT_SECRET"` // Derived from admin password
    }
    AgentRegistration struct {
        TokenExpiry string `env:"REDFLAG_TOKEN_EXPIRY" default:"24h"`
        MaxTokens   int    `env:"REDFLAG_MAX_TOKENS" default:"100"`
        MaxSeats    int    `env:"REDFLAG_MAX_SEATS" default:"50"` // Security limit, not pricing
    }
}

Priority 2: UI-Controlled Registration System

// agents.go needs UI-driven token management:
func (h *AgentHandler) GenerateRegistrationToken(request TokenRequest) (*TokenResponse, error) {
    // Check seat limit (security, not licensing)
    activeAgents, err := h.queries.GetActiveAgentCount()
    if activeAgents >= h.config.MaxSeats {
        return nil, fmt.Errorf("maximum agent seats (%d) reached", h.config.MaxSeats)
    }

    // Generate one-time use token
    token := generateSecureToken()
    expiry := time.Now().Add(parseDuration(request.ExpiresIn))

    // Store with metadata
    err = h.queries.CreateRegistrationToken(token, expiry, request.Labels)
    return &TokenResponse{
        Token: token,
        ExpiresAt: expiry,
        InstallCommand: fmt.Sprintf("curl -sfL https://%s/install | bash -s -- %s", h.config.ServerHost, token),
    }, nil
}

func (h *AgentHandler) ListRegistrationTokens() ([]TokenInfo, error) {
    return h.queries.GetActiveRegistrationTokens()
}

func (h *AgentHandler) RevokeRegistrationToken(token string) error {
    return h.queries.RevokeRegistrationToken(token)
}

Priority 3: UI Components for Token Management

• Admin Dashboard → Agent Management → Registration Tokens
• Generate Token Button → Shows one-liner install command
• Token List → Active, Used, Expired, Revoked status
• Revoke Button → Immediate token invalidation
• Agent Count/Seat Usage → Security monitoring (not licensing)

Current Progress

✅ COMPLETED:

• Created Path to Alpha document
• Enhanced server configuration system with user-provided secrets
• Interactive setup wizard with secure configuration generation
• Production-ready command line interface (--setup, --migrate, --version)
• Removed development JWT secret dependency
• Added backwards compatibility with existing environment variables
• Registration token database schema with security features
• Complete registration token database queries (CRUD operations)

✅ COMPLETED:

• Created Path to Alpha document
• Enhanced server configuration system with user-provided secrets
• Interactive setup wizard with secure configuration generation
• Production-ready command line interface (--setup, --migrate, --version)
• Removed development JWT secret dependency
• Added backwards compatibility with existing environment variables
• Registration token database schema with security features
• Complete registration token database queries (CRUD operations)
• Complete registration token API endpoints (UI-ready)
• User-adjustable rate limiting system with comprehensive API security

✅ COMPLETED:

• Created Path to Alpha document
• Enhanced server configuration system with user-provided secrets
• Interactive setup wizard with secure configuration generation
• Production-ready command line interface (--setup, --migrate, --version)
• Removed development JWT secret dependency
• Added backwards compatibility with existing environment variables
• Registration token database schema with security features
• Complete registration token database queries (CRUD operations)
• Complete registration token API endpoints (UI-ready)
• User-adjustable rate limiting system with comprehensive API security
• Enhanced agent configuration system with proxy support and registration tokens

🔄 IN PROGRESS:

• Agent client proxy support implementation
• Server-side registration token validation for agents

⏭️ NEXT:

• UI components for agent enrollment (token generation, listing, revocation)
• UI components for rate limit settings management
• One-liner installer scripts for clean machine deployment
• Cross-platform binary distribution system
• Production deployment automation (Docker Compose, installers)
• Clean machine deployment testing

✅ REGISTRATION TOKEN API ENDPOINTS IMPLEMENTED:

# Token Generation:
POST /api/v1/admin/registration-tokens
{
  "label": "Server-01",
  "expires_in": "24h",  // Optional, defaults to config
  "metadata": {}
}

# Token Listing:
GET /api/v1/admin/registration-tokens?page=1&limit=50&status=active

# Active Tokens Only:
GET /api/v1/admin/registration-tokens/active

# Revoke Token:
DELETE /api/v1/admin/registration-tokens/{token}

# Token Statistics:
GET /api/v1/admin/registration-tokens/stats

# Cleanup Expired:
POST /api/v1/admin/registration-tokens/cleanup

# Validate Token (debug):
GET /api/v1/admin/registration-tokens/validate?token=xyz

✅ SECURITY FEATURES IMPLEMENTED:

• Agent seat limit enforcement (security, not licensing)
• One-time use tokens with configurable expiration (max 7 days)
• Token revocation with audit trail
• Automatic cleanup of expired tokens
• Comprehensive token usage statistics
• JWT secret derived from user credentials
• User-adjustable rate limiting system for comprehensive API security

✅ RATE LIMITING SYSTEM IMPLEMENTED:

# Rate Limit Management:
GET  /api/v1/admin/rate-limits           # View current settings
PUT  /api/v1/admin/rate-limits           # Update settings
POST /api/v1/admin/rate-limits/reset    # Reset to defaults
GET  /api/v1/admin/rate-limits/stats    # Usage statistics
POST /api/v1/admin/rate-limits/cleanup  # Clean expired entries

# Default Rate Limits (User Adjustable):
- Agent Registration: 5 requests/minute per IP
- Agent Check-ins: 60 requests/minute per agent ID
- Agent Reports: 30 requests/minute per agent ID
- Admin Token Generation: 10 requests/minute per user
- Admin Operations: 100 requests/minute per user
- Public Access: 20 requests/minute per IP

# Features:
- In-memory sliding window rate limiting
- Configurable per-endpoint limits
- Real-time usage statistics
- Automatic memory cleanup
- HTTP rate limit headers (X-RateLimit-*, Retry-After)
- Professional error responses

✅ AGENT DISTRIBUTION AND SERVING SYSTEM IMPLEMENTED:

# Server builds and serves multi-platform agents:
GET /api/v1/downloads/linux-amd64     # Linux agent binary
GET /api/v1/downloads/windows-amd64   # Windows agent binary
GET /api/v1/downloads/darwin-amd64    # macOS agent binary

# One-liner installation scripts:
GET /api/v1/install/linux             # Linux installer
GET /api/v1/install/windows           # Windows installer
GET /api/v1/install/darwin            # macOS installer

# Admin workflow:
1. Generate registration token in admin interface
2. Download agent for target platform
3. Install with: curl http://server/install/linux | bash
4. Agent auto-configures with server URL and token

**✅ ENHANCED AGENT CONFIGURATION SYSTEM IMPLEMENTED:**
```bash
# New CLI Flags (v0.1.16):
./redflag-agent --version                    # Show version
./redflag-agent --server https://redflag.company.com --token reg-token-123
./redflag-agent --proxy-http http://proxy.company.com:8080
./redflag-agent --log-level debug --organization "IT Department"
./redflag-agent --tags "production,webserver" --name "Web Server 01"

# Configuration Priority:
1. CLI flags (highest priority)
2. Environment variables
3. Configuration file
4. Default values

# Environment Variables:
REDFLAG_SERVER_URL="https://redflag.company.com"
REDFLAG_REGISTRATION_TOKEN="reg-token-123"
REDFLAG_HTTP_PROXY="http://proxy.company.com:8080"
REDFLAG_HTTPS_PROXY="https://proxy.company.com:8080"
REDFLAG_NO_PROXY="localhost,127.0.0.1"
REDFLAG_LOG_LEVEL="info"
REDFLAG_ORGANIZATION="IT Department"

# Enhanced Configuration Structure:
{
  "server_url": "https://redflag.company.com",
  "registration_token": "reg-token-123",
  "proxy": {
    "enabled": true,
    "http": "http://proxy.company.com:8080",
    "https": "https://proxy.company.com:8080",
    "no_proxy": "localhost,127.0.0.1"
  },
  "network": {
    "timeout": "30s",
    "retry_count": 3,
    "retry_delay": "5s"
  },
  "tls": {
    "insecure_skip_verify": false
  },
  "logging": {
    "level": "info",
    "max_size": 100,
    "max_backups": 3
  },
  "tags": ["production", "webserver"],
  "organization": "IT Department",
  "display_name": "Web Server 01"
}

✅ DATABASE SCHEMA & QUERIES IMPLEMENTED:

-- Registration tokens table with:
- One-time use tokens with configurable expiration
- Token status tracking (active, used, expired, revoked)
- Audit trail (created_by, used_by_agent_id, timestamps)
- Automatic cleanup functions
- Performance indexes

✅ SERVER CONFIGURATION SYSTEM WORKING:

# Test setup wizard (interactive):
./redflag-server --setup

# Test version info:
./redflag-server --version

# Test configuration validation (fails without config):
rm .env && ./redflag-server
# Output: [WARNING] Missing required configuration
# Output: [INFO] Run: ./redflag-server --setup to configure

# Test migrations:
./redflag-server --migrate

# Test server start with proper config:
./redflag-server

✅ SERVER CONFIGURATION SYSTEM WORKING:

# Test setup wizard (interactive):
./redflag-server --setup

# Test version info:
./redflag-server --version

# Test configuration validation (fails without config):
rm .env && ./redflag-server
# Output: [WARNING] Missing required configuration
# Output: [INFO] Run: ./redflag-server --setup to configure

# Test migrations:
./redflag-server --migrate

# Test server start with proper config:
./redflag-server