up

2025-12-14 18:33:02 +02:00
parent d233fa3529
commit 2e70c9fdb6
51 changed files with 5958 additions and 75 deletions
--- a/docs/modules/zastava/operations/docker-socket-permissions.md
+++ b/docs/modules/zastava/operations/docker-socket-permissions.md
@@ -0,0 +1,318 @@
+# Docker Socket Permissions and Security
+
+This document covers the security considerations and configuration options for Docker socket access in Zastava Agent deployments.
+
+## Overview
+
+The Zastava Agent requires read access to the Docker socket (`/var/run/docker.sock`) to:
+
+1. **Monitor container lifecycle events** - Start, stop, pause, die, etc.
+2. **Inspect running containers** - Image digest, labels, environment variables
+3. **Collect runtime evidence** - Loaded libraries, process information
+
+## Default Configuration
+
+By default, the agent runs as:
+- **User:** `zastava-agent` (system user)
+- **Group:** `docker` (grants socket access)
+- **Socket:** `/var/run/docker.sock`
+
+```yaml
+# systemd service configuration
+User=zastava-agent
+Group=docker
+ReadWritePaths=/var/run/docker.sock
+```
+
+## Security Considerations
+
+### Docker Socket Exposure Risks
+
+The Docker socket provides significant privileges:
+
+| Capability | Risk Level | Mitigation |
+|------------|-----------|------------|
+| List containers | Low | Required for operation |
+| Inspect containers | Low | Required for operation |
+| Read container logs | Medium | Agent does not use this |
+| Create containers | High | Agent does not use this |
+| Execute in containers | Critical | Agent does not use this |
+| Pull images | High | Agent does not use this |
+| Remove containers | High | Agent does not use this |
+
+### Agent Behavior
+
+The Zastava Agent performs **read-only operations**:
+
+```go
+// Operations used by agent
+docker.ContainerList(...)     // List running containers
+docker.ContainerInspect(...)  // Get container details
+docker.Events(...)            // Subscribe to lifecycle events
+```
+
+The agent **does not** perform write operations such as creating, starting, stopping, or removing containers.
+
+## Alternative Configurations
+
+### Option 1: Docker API Proxy (Recommended for High-Security)
+
+Deploy a Docker API proxy that restricts available operations:
+
+```yaml
+# docker-proxy configuration example
+allowed_endpoints:
+  - "GET /containers/json"        # List containers
+  - "GET /containers/*/json"      # Inspect container
+  - "GET /events"                 # Subscribe to events
+  - "GET /_ping"                  # Health check
+```
+
+Example proxy: [Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)
+
+```bash
+# Deploy proxy
+docker run -d \
+  --name docker-proxy \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -e CONTAINERS=1 \
+  -e EVENTS=1 \
+  -p 2375:2375 \
+  tecnativa/docker-socket-proxy
+```
+
+Configure agent to use proxy:
+```env
+ZASTAVA_AGENT__DockerEndpoint=tcp://localhost:2375
+```
+
+### Option 2: Unix Socket with ACLs
+
+Use filesystem ACLs for fine-grained access:
+
+```bash
+# Install ACL support
+sudo apt-get install acl
+
+# Set ACL for zastava-agent user
+sudo setfacl -m u:zastava-agent:rw /var/run/docker.sock
+
+# Verify ACL
+getfacl /var/run/docker.sock
+```
+
+This allows removing the user from the `docker` group while maintaining socket access.
+
+### Option 3: SELinux/AppArmor Policies
+
+#### SELinux Policy
+
+```te
+# zastava-agent.te
+module zastava_agent 1.0;
+
+require {
+    type docker_var_run_t;
+    type zastava_agent_t;
+    class sock_file { read write };
+}
+
+# Allow read/write to Docker socket
+allow zastava_agent_t docker_var_run_t:sock_file { read write getattr };
+```
+
+#### AppArmor Profile
+
+```apparmor
+# /etc/apparmor.d/zastava-agent
+profile zastava-agent /opt/stellaops/zastava-agent/StellaOps.Zastava.Agent {
+  # Docker socket access
+  /var/run/docker.sock rw,
+
+  # Deny network access except to scanner backend
+  network inet stream,
+  network inet6 stream,
+
+  # Read-only system access
+  /etc/stellaops/* r,
+  /opt/stellaops/zastava-agent/** mr,
+
+  # Data directory
+  /var/lib/zastava-agent/** rw,
+}
+```
+
+### Option 4: Rootless Docker
+
+For maximum isolation, use rootless Docker:
+
+```bash
+# Install rootless Docker
+dockerd-rootless-setuptool.sh install
+
+# Configure agent to use rootless socket
+export ZASTAVA_AGENT__DockerEndpoint=unix:///run/user/1000/docker.sock
+```
+
+Note: Rootless Docker has some limitations with networking and storage drivers.
+
+## Log Paths
+
+### Agent Logs
+
+| Component | Log Location |
+|-----------|--------------|
+| Agent stdout/stderr | `journalctl -u zastava-agent` |
+| Runtime events | `/var/lib/zastava-agent/runtime-events/*.ndjson` |
+| Health check | Agent stdout (structured JSON) |
+
+### Log Configuration
+
+```env
+# Set log level
+Serilog__MinimumLevel__Default=Information
+
+# Available levels: Verbose, Debug, Information, Warning, Error, Fatal
+```
+
+### Log Rotation
+
+Event buffer files are automatically rotated:
+
+```yaml
+# Default settings
+event_buffer:
+  max_file_size_mb: 10
+  max_total_size_mb: 100
+  retention_hours: 24
+```
+
+## Health Check Configuration
+
+The agent exposes HTTP health endpoints:
+
+| Endpoint | Port | Description |
+|----------|------|-------------|
+| `/healthz` | 8080 | Liveness probe |
+| `/readyz` | 8080 | Readiness probe |
+| `/livez` | 8080 | Alias for liveness |
+
+### Health Check Port
+
+Configure via environment variable:
+
+```env
+ZASTAVA_AGENT__HealthCheck__Port=8080
+```
+
+### Health Check Behavior
+
+**Liveness (`/healthz`):**
+- Returns 200 if agent process is running
+- Returns 503 if critical subsystems failed
+
+**Readiness (`/readyz`):**
+- Returns 200 if agent can process events
+- Returns 503 if:
+  - Docker socket is unreachable
+  - Event buffer is not writable
+  - Backend connection failed
+
+### Prometheus Metrics
+
+Health metrics are exposed at `/metrics`:
+
+```
+# HELP zastava_agent_docker_connected Docker connectivity status
+# TYPE zastava_agent_docker_connected gauge
+zastava_agent_docker_connected 1
+
+# HELP zastava_agent_buffer_writable Event buffer writability
+# TYPE zastava_agent_buffer_writable gauge
+zastava_agent_buffer_writable 1
+
+# HELP zastava_agent_events_buffered Number of events in buffer
+# TYPE zastava_agent_events_buffered gauge
+zastava_agent_events_buffered 42
+```
+
+## Monitoring Recommendations
+
+### Alerting Rules
+
+```yaml
+groups:
+  - name: zastava-agent
+    rules:
+      - alert: ZastavaAgentDown
+        expr: up{job="zastava-agent"} == 0
+        for: 5m
+        annotations:
+          summary: "Zastava Agent is down on {{ $labels.instance }}"
+
+      - alert: ZastavaDockerDisconnected
+        expr: zastava_agent_docker_connected == 0
+        for: 1m
+        annotations:
+          summary: "Zastava Agent lost Docker connectivity"
+
+      - alert: ZastavaBufferNotWritable
+        expr: zastava_agent_buffer_writable == 0
+        for: 1m
+        severity: critical
+        annotations:
+          summary: "Zastava event buffer is not writable"
+```
+
+### Grafana Dashboard
+
+Import the Zastava monitoring dashboard from:
+`docs/modules/zastava/operations/dashboards/zastava-observability.json`
+
+## Troubleshooting
+
+### Cannot Access Docker Socket
+
+```bash
+# Check socket exists
+ls -la /var/run/docker.sock
+
+# Check agent user groups
+id zastava-agent
+
+# Check Docker daemon is running
+systemctl status docker
+
+# Test socket access manually
+sudo -u zastava-agent docker ps
+```
+
+### Permission Denied Errors
+
+```bash
+# Add user to docker group (if not using ACLs)
+sudo usermod -aG docker zastava-agent
+
+# Restart agent
+sudo systemctl restart zastava-agent
+```
+
+### Events Not Being Received
+
+```bash
+# Check Docker events stream
+docker events --since 1m
+
+# Verify agent can see events
+journalctl -u zastava-agent | grep -i "event"
+
+# Check event buffer
+ls -la /var/lib/zastava-agent/runtime-events/
+```
+
+## References
+
+- [Docker Engine Security](https://docs.docker.com/engine/security/)
+- [Docker Socket Security](https://docs.docker.com/engine/security/protect-access/)
+- [Rootless Docker](https://docs.docker.com/engine/security/rootless/)
+- [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)
--- a/docs/modules/zastava/operations/windows.md
+++ b/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/)