Redflag/docs/4_LOG/October_2025/Architecture-Documentation/UPDATE_INFRASTRUCTURE_DESIGN.md

RedFlag Agent Update Infrastructure Design

Overview

This document outlines the design and architecture for implementing automatic agent update capabilities in the RedFlag update management platform. The current implementation provides version tracking and notification, with infrastructure ready for future automated update delivery.

Current Implementation Status

✅ Completed Features

1. Version Tracking System

   • Agents report version during check-in (current_version field)
   • Server compares against latest_version configuration
   • Update availability status (update_available boolean)
   • Version check timestamps (last_version_check)

2. Version Comparison Logic

   • Semantic version comparison utility (internal/utils/version.go)
   • Server-side version detection during agent check-ins
   • Automatic update availability calculation

3. Database Schema

   • Version tracking columns in agents table
   • Migration: 009_add_agent_version_tracking.sql
   • Model support in Agent and AgentWithLastScan structs

4. Web UI Integration

   • Version status indicators in agent list and detail views
   • Visual update availability badges
   • Version check timestamps

Proposed Auto-Update Architecture

Phase 1: Update Delivery Infrastructure

1.1 Update Package Management

-- Update packages table
CREATE TABLE agent_update_packages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    version VARCHAR(50) NOT NULL,
    os_type VARCHAR(50) NOT NULL,
    architecture VARCHAR(50) NOT NULL,
    package_url TEXT NOT NULL,
    checksum_sha256 VARCHAR(64) NOT NULL,
    size_bytes BIGINT NOT NULL,
    release_notes TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Update deployment history
CREATE TABLE agent_update_deployments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    agent_id UUID NOT NULL REFERENCES agents(id),
    package_id UUID NOT NULL REFERENCES agent_update_packages(id),
    status VARCHAR(50) NOT NULL, -- 'pending', 'downloading', 'installing', 'completed', 'failed'
    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP,
    error_message TEXT,
    rollback_available BOOLEAN DEFAULT FALSE,
    FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE
);

1.2 Update Distribution Service

// UpdatePackageService
type UpdatePackageService struct {
    packageQueries   *queries.UpdatePackageQueries
    deploymentQueries *queries.DeploymentQueries
    storageProvider   StorageProvider
    config           *config.Config
}

// StorageProvider interface for different storage backends
type StorageProvider interface {
    UploadPackage(ctx context.Context, package *UpdatePackage) (string, error)
    GetDownloadURL(ctx context.Context, packageID string) (string, error)
    ValidateChecksum(ctx context.Context, packageID string, expectedChecksum string) error
}

// S3StorageProvider implementation
type S3StorageProvider struct {
    client *s3.Client
    bucket string
}

1.3 Secure Update Delivery

• Signed URLs: Time-limited, authenticated download URLs
• Checksum Validation: SHA-256 verification before installation
• Package Signing: Cryptographic signature verification
• Rollback Support: Previous version retention and rollback capability

Phase 2: Agent Update Engine

2.1 Update Command System

// New command types for updates
const (
    CommandTypeDownloadUpdate   = "download_update"
    CommandTypeInstallUpdate    = "install_update"
    CommandTypeRollbackUpdate   = "rollback_update"
    CommandTypeVerifyUpdate     = "verify_update"
)

// Update command parameters
type UpdateCommandParams struct {
    PackageID      string `json:"package_id"`
    DownloadURL    string `json:"download_url"`
    ChecksumSHA256 string `json:"checksum_sha256"`
    ForceUpdate    bool   `json:"force_update,omitempty"`
    Rollback       bool   `json:"rollback,omitempty"`
}

2.2 Agent Update Handler

// Agent update handler
type UpdateHandler struct {
    downloadDir    string
    backupDir      string
    maxRetries     int
    timeout        time.Duration
    signatureVerifier SignatureVerifier
}

// Update execution flow
func (h *UpdateHandler) ExecuteUpdate(cmd UpdateCommand) error {
    // 1. Download package with validation
    packagePath, err := h.downloadPackage(cmd.DownloadURL, cmd.ChecksumSHA256)
    if err != nil {
        return err
    }

    // 2. Create backup of current version
    backupPath, err := h.createBackup()
    if err != nil {
        return err
    }

    // 3. Verify package signature
    if err := h.verifySignature(packagePath); err != nil {
        return err
    }

    // 4. Install update
    if err := h.installPackage(packagePath); err != nil {
        // Attempt rollback
        h.rollback(backupPath)
        return err
    }

    // 5. Verify installation
    if err := h.verifyInstallation(); err != nil {
        h.rollback(backupPath)
        return err
    }

    return nil
}

Phase 3: Update Management UI

3.1 Update Dashboard

• Update Status Overview: Global view of update deployment progress
• Agent Update Status: Per-agent update state and history
• Rollback Management: View and manage rollback capabilities
• Update Scheduling: Configure maintenance windows and auto-approval rules

3.2 Update Controls

// Update management interface
interface UpdateManagement {
    // Manual update triggers
    triggerUpdate(agentId: string, options: UpdateOptions): Promise<void>

    // Bulk update operations
    bulkUpdate(agentIds: string[], options: BulkUpdateOptions): Promise<void>

    // Rollback operations
    rollbackUpdate(agentId: string, targetVersion?: string): Promise<void>

    // Update scheduling
    scheduleUpdate(agentId: string, schedule: UpdateSchedule): Promise<void>

    // Update monitoring
    getUpdateStatus(agentId: string): Promise<UpdateStatus>
    getDeploymentHistory(agentId: string): Promise<UpdateDeployment[]>
}

Security Considerations

1. Package Security

• Code Signing: All update packages must be cryptographically signed
• Checksum Verification: SHA-256 validation before installation
• Integrity Checks: Package tampering detection
• Secure Storage: Encrypted storage of update packages

2. Delivery Security

• Authenticated Downloads: Signed URLs with expiration
• Transport Security: HTTPS/TLS for all update communications
• Access Control: Role-based access to update management
• Audit Logging: Complete audit trail of update operations

3. Installation Security

• Permission Validation: Verify update installation permissions
• Rollback Safety: Safe rollback mechanisms
• Isolation: Updates run in isolated context
• Validation: Post-installation verification

Implementation Roadmap

Phase 1: Foundation (Next Sprint)

• Create update packages database schema
• Implement storage provider interface
• Add update package management API
• Create update command types and handlers

Phase 2: Delivery (Following Sprint)

• Implement secure package delivery
• Add agent download and verification
• Create backup and rollback mechanisms
• Add update progress reporting

Phase 3: Automation (Final Sprint)

• Implement auto-update scheduling
• Add bulk update operations
• Create update management UI
• Add monitoring and alerting

Configuration

Server Configuration

# Update settings
UPDATE_STORAGE_TYPE=s3
UPDATE_STORAGE_BUCKET=redflag-updates
UPDATE_BASE_URL=https://updates.redflag.local
UPDATE_MAX_PACKAGE_SIZE=100MB
UPDATE_SIGNATURE_REQUIRED=true

# S3 settings (if using S3)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1

# Update scheduling
UPDATE_AUTO_APPROVE=false
UPDATE_MAINTENANCE_WINDOW_START=02:00
UPDATE_MAINTENANCE_WINDOW_END=04:00
UPDATE_MAX_CONCURRENT_UPDATES=10

Agent Configuration

# Update settings
UPDATE_ENABLED=true
UPDATE_AUTO_INSTALL=false
UPDATE_DOWNLOAD_TIMEOUT=300s
UPDATE_INSTALL_TIMEOUT=600s
UPDATE_MAX_RETRIES=3
UPDATE_BACKUP_RETENTION=3

Monitoring and Observability

1. Metrics

• Update success/failure rates
• Update deployment duration
• Package download times
• Rollback frequency
• Update availability status

2. Logging

• Detailed update execution logs
• Error and failure tracking
• Performance metrics
• Security events

3. Alerting

• Update failure notifications
• Security violation alerts
• Performance degradation warnings
• Rollback required alerts

Testing Strategy

1. Unit Testing

• Version comparison logic
• Package validation functions
• Update command handling
• Rollback mechanisms

2. Integration Testing

• End-to-end update flow
• Package delivery and verification
• Multi-platform compatibility
• Security validation

3. Performance Testing

• Large-scale update deployments
• Concurrent update handling
• Network failure scenarios
• Storage performance

Conclusion

This design provides a comprehensive foundation for implementing secure, reliable automatic updates for RedFlag agents. The phased approach allows for incremental implementation while maintaining system security and reliability.

The current version tracking system serves as the foundation for this infrastructure, with all necessary components in place to begin implementing automated update delivery.