up

docs/modules/zastava/operations/windows.md

@@ -0,0 +1,367 @@
+# 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/)