Redflag/docs/4_LOG/_originals_archive.backup/technical-debt.md

Technical Debt & Future Improvements

Created: 2025-10-17 Purpose: Track security improvements, feature gaps, and technical debt for alpha release preparation

🔴 HIGH PRIORITY - Alpha Release Blockers

Agent Security Enhancements

• Issue: Current authentication allows any binary to register
• Risk: Unauthorized agents could connect to server
• Solution: Implement agent registration keys and fingerprinting
• Files to modify:
  • aggregator-server/internal/api/handlers/agents.go - Registration endpoint
  • aggregator-server/internal/config/config.go - Add agent registration secret
  • aggregator-agent/cmd/agent/main.go - Add registration key parameter
  • aggregator-agent/internal/config/config.go - Store registration key

Agent Auto-Update Mechanism

• Issue: Manual agent updates required for new features
• Impact: Deployment overhead for multi-machine setups
• Solution: Built-in agent auto-update with version checking
• Design: Agent checks version on each startup, prompts/download/update
• Files to create:
  • aggregator-server/internal/api/handlers/updates.go - Agent binary endpoint
  • aggregator-agent/internal/updater/updater.go - Auto-update logic

🟡 MEDIUM PRIORITY - Alpha Improvements

Docker Scanner Reliability

• Issue: Docker scanner shows "not available" when Docker daemon accessible
• Root Cause: Scanner may not detect Docker in all configurations
• Investigation Needed:
  • Test Docker socket access (/var/run/docker.sock)
  • Test Docker Desktop for Windows integration
  • Test WSL Docker daemon detection
  • Consider Docker-in-Docker scenarios
• Files to review:
  • aggregator-agent/internal/scanner/docker.go - Detection logic

Configuration Documentation

• Issue: .env configuration needs clearer documentation
• Required: Setup guide with all configuration options
• Files to create:
  • docs/configuration.md - Comprehensive configuration guide
  • examples/docker-compose.prod.yml - Production example
  • examples/.env.production - Production environment template

🟢 LOW PRIORITY - Future Enhancements

IP Whitelisting Support

• Feature: Allow only specific IP ranges/subnets for agent connections
• Use Case: Additional security layer for network isolation
• Implementation: Middleware to check agent IP against allowed ranges
• Files to modify:
  • aggregator-server/internal/api/middleware/ip_whitelist.go
  • aggregator-server/internal/config/config.go - Add whitelist configuration

Agent Fingerprinting

• Feature: Create unique system fingerprint per agent
• Purpose: Prevent binary sharing between machines
• Implementation: Hash of hostname + CPU ID + installation time + version
• Files to modify:
  • aggregator-agent/internal/system/fingerprint.go
  • aggregator-server/internal/models/agent.go - Add fingerprint field

Rate Limiting

• Security: Prevent API abuse and brute force attacks
• Implementation: Rate limiting middleware for sensitive endpoints
• Files to create:
  • aggregator-server/internal/api/middleware/ratelimit.go

🐛 Known Issues

Windows Docker Support

• Issue: Unclear Docker support via WSL and Windows Desktop
• Investigation: Test different Docker configurations on Windows
• Status: Needs testing with Docker Desktop, WSL2, and Windows containers

Package Manager Compatibility

• Issue: Some package managers may have edge cases
• Examples:
  • DNF5 vs DNF command differences
  • APT repository availability issues
  • Winget version detection
• Status: Partially addressed, needs more testing

📋 Alpha Release Checklist

Security Must-Haves

• Agent registration keys implemented
• Configuration documentation complete
• Default secure settings documented

Feature Completeness

• Agent auto-update mechanism
• Docker scanner reliability confirmed
• All package managers tested on target platforms

Documentation

• Configuration guide
• Deployment instructions
• Security best practices guide
• Troubleshooting guide

Testing

• Multi-platform deployment tested
• Docker support verified (WSL/Desktop/Linux)
• Security controls tested

🚀 Post-Alpha Roadmap

v0.2.0 Features

• Real-time WebSocket updates
• Advanced scheduling (maintenance windows)
• Proxmox integration
• Advanced reporting and analytics

v0.3.0 Features

• Multi-tenant support
• Agent groups and tagging
• Custom update policies
• Integration with external systems (Prometheus, Grafana)

---

Notes: This document should be updated regularly as items are completed or new requirements are identified. Priorities may shift based on user feedback and security considerations.