Redflag/docs/4_LOG/November_2025/research/quick_reference.md

RedFlag Agent - Quick Reference Guide

Key Files and Line Numbers

Main Agent Entry Point

• File: /home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go
• Main loop: Lines 410-549
• Command switch: Lines 502-543
• Agent initialization: Lines 387-549

MONOLITHIC Scan Handler (Key Target for Refactoring)

• Function: handleScanUpdates()
• File: /home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go
• Lines: 551-709 (159 lines - the monolith)

Detailed scanner calls within handleScanUpdates:

• APT Scanner: lines 559-574
• DNF Scanner: lines 576-592
• Docker Scanner: lines 594-610
• Windows Update Scanner: lines 612-628
• Winget Scanner: lines 630-646
• Error aggregation & reporting: lines 648-709

Scanner Implementations

Scanner	File	Lines	Key Methods
APT	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/apt.go	1-91	IsAvailable (23-26), Scan (29-42)
DNF	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/dnf.go	1-157	IsAvailable (23-26), Scan (29-43), determineSeverity (121-157)
Docker	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/docker.go	1-163	IsAvailable (34-47), Scan (50-123), checkForUpdate (137-154)
Registry Client	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/registry.go	1-260	GetRemoteDigest (62-88), fetchManifestDigest (166-216)
Windows Update	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/windows_wua.go	1-553	IsAvailable (27-30), Scan (33-67), convertWUAUpdate (91-211)
Winget	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/winget.go	1-662	IsAvailable (34-43), Scan (46-84), attemptWingetRecovery (533-576)

System Information

Component	File	Lines	Purpose
System Info Structure	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go	13-28	SystemInfo struct
DiskInfo Structure	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go	45-57	Multi-disk support
GetSystemInfo	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go	60-100+	Detailed system collection
Report System Info	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go	1357-1407	Report to server (hourly)
System Metrics (lightweight)	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go	429-444	Every check-in

Command Handlers

Command	Function	File	Lines
scan_updates	handleScanUpdates	main.go	551-709
collect_specs	Not implemented	main.go	~509
dry_run_update	handleDryRunUpdate	main.go	992-1105
install_updates	handleInstallUpdates	main.go	873-989
confirm_dependencies	handleConfirmDependencies	main.go	1108-1216
enable_heartbeat	handleEnableHeartbeat	main.go	1219-1291
disable_heartbeat	handleDisableHeartbeat	main.go	1294-1355
reboot	handleReboot	main.go	1410-1495

Supporting Subsystems

Subsystem	File	Purpose
Local Cache	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/cache/local.go	Cache scan results locally
API Client	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/client/client.go	Server communication
Config Manager	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/config/config.go	Configuration handling
Installers	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/installer/	Package installation (apt, dnf, docker, windows, winget)
Display	/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/display/terminal.go	Terminal output formatting

---

Architecture Issues Found

Problem 1: Monolithic Orchestration

Location: handleScanUpdates() lines 551-709

Issue: All scanner execution tightly coupled in single function

• No abstraction for scanner lifecycle
• Repeated code pattern 5 times (once per scanner)
• Sequential execution (no parallelization)
• Mixed concerns (availability check + scan + error handling)

Example:

// This pattern repeats 5 times
if aptScanner.IsAvailable() {
    updates, err := aptScanner.Scan()
    if err != nil {
        scanErrors = append(scanErrors, fmt.Sprintf("APT scan failed: %v", err))
    } else {
        allUpdates = append(allUpdates, updates...)
    }
}

Problem 2: No Subsystem Health Tracking

Current State: Scanners report errors as plain strings

Missing:

• Per-scanner status tracking
• Subsystem readiness indicators
• Individual scanner metrics
• Enable/disable individual scanners without code changes

Problem 3: Storage and System Info Not Subsystemized

Current State:

• System metrics collected at main loop level (lines 429-444)
• Full system info reported hourly (lines 417-425)
• No formal "system info subsystem"

Needed:

• Separate system info subsystem with its own lifecycle
• DiskInfo is modular (supports multiple disks) but not leveraged
• Storage subsystem could be independent

Problem 4: Error Aggregation Model

Current: Strings accumulated and reported together (lines 648-677)

Better Would Be:

• Per-subsystem error types
• Error codes instead of string concatenation
• Proper error handling chains

---

Subsystems Currently Included

The scan_updates command integrates 5 distinct subsystems:

1. APT Package Scanner (Linux Debian/Ubuntu)

   • Checks: apt list --upgradable
   • Severity: Based on repository name

2. DNF Package Scanner (Linux Fedora/RHEL)

   • Checks: dnf check-update
   • Severity: Complex logic based on package name & repo

3. Docker Image Scanner (Container images)

   • Lists running containers
   • Queries Docker Registry API v2
   • Compares local vs remote digests

4. Windows Update Scanner (Windows OS updates)

   • Uses Windows Update Agent (WUA) COM API
   • Extracts rich metadata (KB articles, CVEs, MSRC severity)

5. Winget Scanner (Windows applications)

   • Multiple fallback methods
   • Includes recovery/repair logic
   • Categorizes packages

Not Part of scan_updates:

• System info collection (separate hourly process)
• Local caching (separate subsystem)
• Installation/update operations (separate handlers)
• Installer implementations (separate files)

---

Refactoring Opportunities

Quick Wins:

1. Extract scanner loop into ScannerOrchestrator interface
2. Use factory pattern to get available scanners
3. Implement per-scanner timeout handling
4. Add metrics/timing per scanner

Major Refactors:

1. Create formal "ScanningSubsystem" with lifecycle management
2. Separate system info into its own subsystem with scheduled updates
3. Implement per-subsystem configuration and enable/disable toggles
4. Add subsystem health check endpoints

---

Modularity Assessment

Modular Components (Can be changed independently):

• Individual scanner files (apt.go, dnf.go, docker.go, etc.)
• Registry client (separate from Docker scanner)
• System info gathering (platform-specific splits)
• Installer implementations
• Local cache

Monolithic Components (Tightly coupled):

• handleScanUpdates orchestration
• Command processing switch statement
• Main loop timer logic
• Error aggregation logic
• Reporting logic

Verdict:

Modules are modular, but orchestration is monolithic.

The individual scanner implementations follow good modular patterns (separate files, common interface), but how they're orchestrated (the handleScanUpdates function) violates single responsibility principle and couples scanner management logic with business logic.