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

```powershell
# 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:**

   ```powershell
   $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:**

   ```powershell
   $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:**

   ```powershell
   @"
   # 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:**

   ```powershell
   # 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`:

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

5. **Start the service:**

   ```powershell
   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:

```powershell
# 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)

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

### Windows Firewall

If health checks are accessed remotely:

```powershell
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

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

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

### Windows Service Status

```powershell
# 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

```powershell
# 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:**
   ```powershell
   docker info
   ```

2. **Verify named pipe exists:**
   ```powershell
   Test-Path "\\.\pipe\docker_engine"
   ```

3. **Check service account permissions:**
   ```powershell
   whoami /groups
   ```

4. **Review Event Log:**
   ```powershell
   Get-EventLog -LogName Application -Source ZastavaAgent -Newest 10
   ```

### Cannot Connect to Docker

1. **Test Docker API:**
   ```powershell
   Invoke-RestMethod -Uri "http://localhost:2375/info" -Method Get
   # or for named pipe
   docker version
   ```

2. **Verify Docker mode:**
   ```powershell
   docker info --format '{{.OSType}}'
   # Should be "windows" for Windows containers
   ```

3. **Check pipe permissions:**
   ```powershell
   # List pipe ACL
   Get-Acl "\\.\pipe\docker_engine" | Format-List
   ```

### Events Not Being Sent

1. **Check event buffer:**
   ```powershell
   Get-ChildItem "C:\ProgramData\StellaOps\Zastava\runtime-events"
   ```

2. **Verify backend connectivity:**
   ```powershell
   Test-NetConnection -ComputerName scanner.internal -Port 443
   ```

3. **Check readiness:**
   ```powershell
   Invoke-RestMethod -Uri "http://localhost:8080/readyz"
   ```

## Upgrade Procedure

1. **Stop the service:**
   ```powershell
   Stop-Service ZastavaAgent
   ```

2. **Backup configuration:**
   ```powershell
   Copy-Item "C:\Program Files\StellaOps\Zastava\zastava-agent.env" "C:\temp\zastava-agent.env.bak"
   ```

3. **Download and extract new version:**
   ```powershell
   $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:**
   ```powershell
   Copy-Item "C:\temp\zastava-agent.env.bak" "C:\Program Files\StellaOps\Zastava\zastava-agent.env"
   ```

5. **Start the service:**
   ```powershell
   Start-Service ZastavaAgent
   ```

6. **Verify health:**
   ```powershell
   Invoke-RestMethod -Uri "http://localhost:8080/healthz"
   ```

## Uninstallation

```powershell
# 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](https://docs.docker.com/desktop/windows/)
- [Windows Server Containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/)
- [Docker Engine on Windows Server](https://docs.docker.com/engine/install/windows/)