Redflag/docs/4_LOG/November_2025/planning/WINDOWS_AGENT_PLAN.md

Windows Agent Implementation Plan

Overview

RedFlag uses a universal agent strategy - a single agent binary that supports all platforms (Linux, Windows, macOS) with platform-specific scanners and installers.

Architecture Decision: Universal Agent

✅ RECOMMENDED: Single universal agent with Windows-specific modules ❌ NOT RECOMMENDED: Separate Windows agent binary

Benefits of Universal Agent Approach:

• Unified codebase maintenance
• Consistent REST API interface
• Shared features (Docker, dependency workflow, authentication)
• Easier deployment and versioning
• Cross-platform feature parity

Windows Implementation Options

Option 1: Native PowerShell Commands

Windows Update Scanner: PowerShell Get-WUList or Get-WindowsUpdateLog Winget Scanner: winget list --outdated with JSON parsing Pros: No external dependencies, built into Windows Cons: Limited functionality, complex output parsing

Option 2: Windows Update API Library ⭐ RECOMMENDED

Library: github.com/ceshihao/windowsupdate Dependencies: github.com/go-ole/go-ole, github.com/scjalliance/comshim

Implementation Example:

package main

import (
    "encoding/json"
    "fmt"
    "github.com/ceshihao/windowsupdate"
    "github.com/go-ole/go-ole"
    "github.com/scjalliance/comshim"
)

func main() {
    comshim.Add(1)
    defer comshim.Done()

    ole.CoInitializeEx(0, ole.COINIT_APARTMENTTHREADED|ole.COINIT_SPEED_OVER_MEMORY)
    defer ole.CoUninitialize()

    // Create Windows Update session
    session, err := windowsupdate.NewUpdateSession()
    if err != nil {
        panic(err)
    }

    // Search for updates
    searcher, err := session.CreateUpdateSearcher()
    if err != nil {
        panic(err)
    }

    // Find available updates
    result, err := searcher.Search("IsInstalled=0")
    if err != nil {
        panic(err)
    }

    // Process updates
    for _, update := range result.Updates {
        fmt.Printf("Update: %s\n", update.Title)
        fmt.Printf("KB: %s\n", update.KBArticleIDs)
        fmt.Printf("Severity: %s\n", update.MsrcSeverity)
    }

    // Download and install updates
    downloader, err := session.CreateUpdateDownloader()
    installer, err := session.CreateUpdateInstaller()

    downloadResult, err := downloader.Download(result.Updates)
    installationResult, err := installer.Install(result.Updates)
}

Pros:

• Full Windows Update API access
• Rich metadata (KB numbers, severity, categories)
• Programmatic download and installation
• Handles restart requirements
• Professional-grade update management

Cons:

• External Go dependencies
• COM initialization required
• Windows-specific (not cross-platform)

Implementation Plan

Phase 1: Scanner Implementation

1. Windows Update Scanner (internal/scanner/windows.go)

   • Use github.com/ceshihao/windowsupdate library
   • Query for pending updates with metadata
   • Extract KB numbers, severity, categories
   • Handle different update types (security, feature, driver)

2. Winget Scanner (internal/scanner/winget.go)

   • Use winget list --outdated command
   • Parse JSON output for package information
   • Handle multiple package sources

Phase 2: Installer Implementation

1. Windows Update Installer (internal/installer/windows.go)

   • Use same windowsupdate library for installation
   • Handle download and installation phases
   • Manage restart requirements
   • Support dry-run functionality

2. Winget Installer (internal/installer/winget.go)

   • Use winget install --upgrade commands
   • Handle elevation requirements
   • Support interactive and silent modes

Phase 3: Integration

1. Agent Integration (cmd/agent/main.go)

   • Add Windows scanners to scanner initialization
   • Add Windows installers to factory pattern
   • Handle Windows-specific configuration paths

2. Configuration (internal/config/config.go)

   • Windows config path: C:\ProgramData\RedFlag\config.json
   • Handle Windows service installation
   • Windows-specific metadata collection

3. Build System

   • Cross-compilation for Windows target
   • Windows service integration
   • Installer creation (NSIS or WiX)

File Structure

aggregator-agent/
├── internal/
│   ├── scanner/
│   │   ├── apt.go           # Existing
│   │   ├── dnf.go           # Existing
│   │   ├── docker.go        # Existing
│   │   ├── windows.go       # NEW - Windows Update scanner
│   │   └── winget.go        # NEW - Winget scanner
│   ├── installer/
│   │   ├── apt.go           # Existing
│   │   ├── dnf.go           # Existing
│   │   ├── docker.go        # Existing
│   │   ├── windows.go       # NEW - Windows Update installer
│   │   └── winget.go        # NEW - Winget installer
│   └── config/
│       └── config.go        # Modified - Windows paths
├── cmd/
│   └── agent/
│       └── main.go          # Modified - Windows scanner init
└── go.mod                   # Modified - Add Windows dependencies

Dependencies to Add

// go.mod additions
require (
    github.com/ceshihao/windowsupdate v1.0.0
    github.com/go-ole/go-ole v1.2.6
    github.com/scjalliance/comshim v0.0.0-20210919201923-b3615b7356a3
)

Windows-Specific Considerations

Elevation Requirements

• Windows Update installation requires administrator privileges
• Winget system-wide installations require elevation
• Consider user vs. machine scope installations

Service Integration

• Install as Windows service with proper event logging
• Configure Windows Firewall rules for agent communication
• Handle Windows service lifecycle (start/stop/restart)

Update Behavior

• Windows updates may require system restart
• Handle restart scheduling and user notifications
• Support for deferment policies where applicable

Security Context

• COM initialization for Windows Update API
• Proper handling of Windows security contexts
• Integration with Windows security center

Development Workflow

1. Development Environment: Windows VM or Windows machine
2. Testing: Test with various Windows update scenarios
3. Build: Cross-compile from Linux or build natively on Windows
4. Deployment: Windows service installer with configuration management

Next Steps

1. ✅ Document implementation approach
2. ⏳ Create Windows Update scanner using windowsupdate library
3. ⏳ Create Winget scanner
4. ⏳ Implement Windows installers
5. ⏳ Update agent main loop for Windows support
6. ⏳ Test end-to-end functionality
7. ⏳ Create Windows service integration
8. ⏳ Build and package Windows agent

Conclusion

The discovery of the github.com/ceshihao/windowsupdate library significantly simplifies Windows agent development. This library provides direct access to the Windows Update API with professional-grade functionality for update detection, download, and installation.

Combined with the universal agent strategy, this approach provides:

• Rich Windows Update integration with full metadata
• Consistent cross-platform architecture
• Minimal code duplication
• Professional update management capabilities

This makes RedFlag one of the few open-source update management platforms with truly comprehensive Windows support.