Windows Container Deployment Guide

Historical / retired. This guide describes the legacy standalone Zastava Agent for Windows. The StellaOps.Zastava.* source tree was archived on 2026-05-12 and the standalone agent no longer ships; Windows runtime evidence is now collected through the RuntimeInstrumentation host-agent / deployment-agent model. See the Zastava retirement record and the Windows host agent. The procedures below are retained as a reference for Windows container monitoring concepts.

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

Supported Windows Versions

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

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

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 is not yet implemented.
3. Linux containers via WSL2 - The agent monitors Windows containers; Linux containers running under WSL2 are not directly observed by this agent.

References

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