git.stella-ops.org/docs/modules/zastava/operations/windows.md

Windows Container Deployment Guide

This guide covers deploying and operating the Zastava Agent for Windows container monitoring.

Overview

The Zastava Agent supports Windows container runtime monitoring via:

1. Docker Desktop for Windows - Docker API over named pipe
2. Docker Engine on Windows Server - Native Windows containers
3. Windows Server Core containers - Server-class workloads

System Requirements

Minimum Requirements

Component	Requirement
Operating System	Windows Server 2019 or later
Container Runtime	Docker Engine 20.10+ or Docker Desktop 4.x
.NET Runtime	.NET 10.0 or later
Memory	512 MB minimum, 1 GB recommended
Disk Space	100 MB for agent + event buffer space

Supported Windows Versions

Windows Version	Container Types	Status
Windows Server 2022	Windows Server Core, Nano Server	Full Support
Windows Server 2019	Windows Server Core, Nano Server	Full Support
Windows 11	Windows/Linux containers (via WSL2)	Supported
Windows 10	Windows/Linux containers (via WSL2)	Supported

Installation

Option 1: PowerShell Installation Script

# Download and run installer
Invoke-WebRequest -Uri "https://releases.stellaops.org/zastava-agent/latest/Install-ZastavaAgent.ps1" -OutFile "$env:TEMP\Install-ZastavaAgent.ps1"

# Install with required parameters
& "$env:TEMP\Install-ZastavaAgent.ps1" `
    -Tenant "your-tenant" `
    -ScannerBackendUrl "https://scanner.internal" `
    -InstallPath "C:\Program Files\StellaOps\Zastava"

Option 2: Manual Installation

1. Download the agent:

   $version = "latest"
   $arch = if ([System.Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" }
   $url = "https://releases.stellaops.org/zastava-agent/$version/zastava-agent-win-$arch.zip"
   
   Invoke-WebRequest -Uri $url -OutFile "C:\temp\zastava-agent.zip"
   

2. Extract and install:

   $installPath = "C:\Program Files\StellaOps\Zastava"
   New-Item -ItemType Directory -Path $installPath -Force
   Expand-Archive -Path "C:\temp\zastava-agent.zip" -DestinationPath $installPath
   

3. Create configuration file:

   @"
   # Zastava Agent Configuration
   ZASTAVA_TENANT=your-tenant
   ZASTAVA_AGENT__Backend__BaseAddress=https://scanner.internal
   ZASTAVA_AGENT__DockerEndpoint=npipe:////./pipe/docker_engine
   ZASTAVA_AGENT__EventBufferPath=C:\ProgramData\StellaOps\Zastava\runtime-events
   ZASTAVA_AGENT__HealthCheck__Port=8080
   "@ | Out-File -FilePath "$installPath\zastava-agent.env" -Encoding UTF8
   

4. Install as Windows Service:

   # Using NSSM (Non-Sucking Service Manager)
   nssm install ZastavaAgent "$installPath\StellaOps.Zastava.Agent.exe"
   nssm set ZastavaAgent AppDirectory "$installPath"
   nssm set ZastavaAgent AppEnvironmentExtra "+DOTNET_ENVIRONMENT=Production"
   nssm set ZastavaAgent DisplayName "StellaOps Zastava Agent"
   nssm set ZastavaAgent Description "Container Runtime Monitor for StellaOps"
   nssm set ZastavaAgent Start SERVICE_AUTO_START
   

   Alternatively, use the native sc.exe:

   sc.exe create ZastavaAgent binPath= "$installPath\StellaOps.Zastava.Agent.exe" start= auto
   

5. Start the service:

   Start-Service ZastavaAgent
   

Configuration

Docker Named Pipe Access

The Windows agent connects to Docker via named pipe:

npipe:////./pipe/docker_engine

Environment Variables

Variable	Default	Description
ZASTAVA_TENANT	(required)	Tenant identifier
ZASTAVA_AGENT__Backend__BaseAddress	(required)	Scanner backend URL
ZASTAVA_AGENT__DockerEndpoint	npipe:////./pipe/docker_engine	Docker API endpoint
ZASTAVA_AGENT__EventBufferPath	%ProgramData%\StellaOps\Zastava\runtime-events	Event buffer directory
ZASTAVA_AGENT__HealthCheck__Port	8080	Health check HTTP port

Configuration File Location

C:\Program Files\StellaOps\Zastava\zastava-agent.env

Docker Desktop Configuration

Enable TCP/Named Pipe Access

1. Open Docker Desktop Settings
2. Go to Settings → General
3. Enable Expose daemon on tcp://localhost:2375 without TLS (for development only)
4. Or use the named pipe (default): npipe:////./pipe/docker_engine

Windows Containers Mode

Ensure Docker is in Windows containers mode:

# Check current mode
docker info --format '{{.OSType}}'

# Should output: windows

To switch to Windows containers:

• Right-click Docker Desktop tray icon
• Select "Switch to Windows containers..."

Security Considerations

Named Pipe Permissions

The Docker named pipe requires membership in:

• docker-users group (Docker Desktop)
• Administrators group (Docker Engine)

# Add service account to docker-users group
Add-LocalGroupMember -Group "docker-users" -Member "NT SERVICE\ZastavaAgent"

Windows Firewall

If health checks are accessed remotely:

New-NetFirewallRule `
    -DisplayName "Zastava Agent Health Check" `
    -Direction Inbound `
    -Protocol TCP `
    -LocalPort 8080 `
    -Action Allow

PE Library Hashing

The agent collects SHA-256 hashes of loaded DLLs from Windows containers:

• Portable Executable (PE) format parsing
• Version information extraction
• Digital signature verification (if signed)

Health Monitoring

Health Endpoints

Endpoint	URL	Description
Liveness	http://localhost:8080/healthz	Agent is running
Readiness	http://localhost:8080/readyz	Agent can process events

PowerShell Health Check

# Check agent health
Invoke-RestMethod -Uri "http://localhost:8080/healthz"

# Check readiness
Invoke-RestMethod -Uri "http://localhost:8080/readyz"

Windows Service Status

# Check service status
Get-Service ZastavaAgent

# View service events
Get-EventLog -LogName Application -Source ZastavaAgent -Newest 20

Logging

Event Log

Agent logs are written to Windows Event Log:

• Log: Application
• Source: ZastavaAgent

# View recent events
Get-EventLog -LogName Application -Source ZastavaAgent -Newest 50

# Filter by level
Get-EventLog -LogName Application -Source ZastavaAgent -EntryType Error,Warning

File Logging (Optional)

Enable file logging via configuration:

Serilog__WriteTo__0__Name=File
Serilog__WriteTo__0__Args__path=C:\ProgramData\StellaOps\Zastava\logs\agent-.log
Serilog__WriteTo__0__Args__rollingInterval=Day

Troubleshooting

Agent Won't Start

1. Check Docker is running:

   docker info
   

2. Verify named pipe exists:

   Test-Path "\\.\pipe\docker_engine"
   

3. Check service account permissions:

   whoami /groups
   

4. Review Event Log:

   Get-EventLog -LogName Application -Source ZastavaAgent -Newest 10
   

Cannot Connect to Docker

1. Test Docker API:

   Invoke-RestMethod -Uri "http://localhost:2375/info" -Method Get
   # or for named pipe
   docker version
   

2. Verify Docker mode:

   docker info --format '{{.OSType}}'
   # Should be "windows" for Windows containers
   

3. Check pipe permissions:

   # List pipe ACL
   Get-Acl "\\.\pipe\docker_engine" | Format-List
   

Events Not Being Sent

1. Check event buffer:

   Get-ChildItem "C:\ProgramData\StellaOps\Zastava\runtime-events"
   

2. Verify backend connectivity:

   Test-NetConnection -ComputerName scanner.internal -Port 443
   

3. Check readiness:

   Invoke-RestMethod -Uri "http://localhost:8080/readyz"
   

Upgrade Procedure

1. Stop the service:

   Stop-Service ZastavaAgent
   

2. Backup configuration:

   Copy-Item "C:\Program Files\StellaOps\Zastava\zastava-agent.env" "C:\temp\zastava-agent.env.bak"
   

3. Download and extract new version:

   $version = "1.2.0"
   $url = "https://releases.stellaops.org/zastava-agent/$version/zastava-agent-win-x64.zip"
   Invoke-WebRequest -Uri $url -OutFile "C:\temp\zastava-agent.zip"
   Expand-Archive -Path "C:\temp\zastava-agent.zip" -DestinationPath "C:\Program Files\StellaOps\Zastava" -Force
   

4. Restore configuration:

   Copy-Item "C:\temp\zastava-agent.env.bak" "C:\Program Files\StellaOps\Zastava\zastava-agent.env"
   

5. Start the service:

   Start-Service ZastavaAgent
   

6. Verify health:

   Invoke-RestMethod -Uri "http://localhost:8080/healthz"
   

Uninstallation

# Stop and remove service
Stop-Service ZastavaAgent
sc.exe delete ZastavaAgent

# Remove installation directory
Remove-Item -Path "C:\Program Files\StellaOps\Zastava" -Recurse -Force

# Remove data directory
Remove-Item -Path "C:\ProgramData\StellaOps\Zastava" -Recurse -Force

Known Limitations

1. Hyper-V isolation only - Process isolation containers have limited observability
2. Windows container logs - Container stdout/stderr capture not yet implemented
3. WSL2 containers - Linux containers on Windows require WSL2 mode, not directly supported

References

• Docker Desktop for Windows
• Windows Server Containers
• Docker Engine on Windows Server