Add VitePress documentation site with complete user guides

Covers getting started, repositories, scanning, findings, configuration, SBOM, code graph, impact analysis, DAST, AI chat, issue tracker integration, Docker deployment, environment variables, Keycloak auth, and OpenTelemetry. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 01:18:58 +01:00
parent 65abc55915
commit 94552d1626
21 changed files with 4019 additions and 0 deletions
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -0,0 +1,125 @@
+# Docker Compose Deployment
+
+The recommended way to deploy Compliance Scanner is with Docker Compose.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- At least 4 GB of available RAM
+- Git repository access (tokens configured in `.env`)
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone <repo-url> compliance-scanner
+cd compliance-scanner
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your MongoDB credentials, tokens, etc.
+
+# Start all services
+docker-compose up -d
+```
+
+## Services
+
+The `docker-compose.yml` includes these services:
+
+| Service | Port | Description |
+|---------|------|-------------|
+| `mongo` | 27017 | MongoDB database |
+| `agent` | 3001, 3002 | Compliance agent (REST API + webhooks) |
+| `dashboard` | 8080 | Web dashboard |
+| `chromium` | 3003 | Headless browser for DAST crawling |
+| `otel-collector` | 4317, 4318 | OpenTelemetry collector (optional) |
+
+## Volumes
+
+| Volume | Purpose |
+|--------|---------|
+| `mongo_data` | Persistent MongoDB data |
+| `repos_data` | Cloned repository files |
+
+## Checking Status
+
+```bash
+# View running services
+docker-compose ps
+
+# View logs
+docker-compose logs -f agent
+docker-compose logs -f dashboard
+
+# Restart a service
+docker-compose restart agent
+```
+
+## Accessing the Dashboard
+
+Once running, open [http://localhost:8080](http://localhost:8080) in your browser.
+
+If Keycloak authentication is configured, you'll be redirected to sign in. Otherwise, the dashboard is accessible directly.
+
+## Updating
+
+```bash
+# Pull latest changes
+git pull
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+## Production Considerations
+
+### MongoDB
+
+For production, use a managed MongoDB instance or configure replication:
+
+```bash
+MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/compliance_scanner
+```
+
+### Reverse Proxy
+
+Place the dashboard behind a reverse proxy (nginx, Caddy, Traefik) with TLS:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name compliance.example.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### Resource Limits
+
+Add resource limits to Docker Compose for production:
+
+```yaml
+services:
+  agent:
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+          cpus: '2.0'
+  dashboard:
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1.0'
+```
--- a/docs/deployment/environment.md
+++ b/docs/deployment/environment.md
@@ -0,0 +1,84 @@
+# Environment Variables
+
+Complete reference for all environment variables. See [Configuration](/guide/configuration) for detailed descriptions of each variable.
+
+## Required
+
+```bash
+# MongoDB connection
+MONGODB_URI=mongodb://root:example@localhost:27017/compliance_scanner?authSource=admin
+```
+
+## Agent
+
+```bash
+AGENT_PORT=3001
+SCAN_SCHEDULE=0 0 */6 * * *
+CVE_MONITOR_SCHEDULE=0 0 0 * * *
+GIT_CLONE_BASE_PATH=/tmp/compliance-scanner/repos
+MONGODB_DATABASE=compliance_scanner
+```
+
+## Dashboard
+
+```bash
+DASHBOARD_PORT=8080
+AGENT_API_URL=http://localhost:3001
+```
+
+## LLM / AI
+
+```bash
+LITELLM_URL=http://localhost:4000
+LITELLM_API_KEY=
+LITELLM_MODEL=gpt-4o
+LITELLM_EMBED_MODEL=text-embedding-3-small
+```
+
+## Git Providers
+
+```bash
+# GitHub
+GITHUB_TOKEN=
+GITHUB_WEBHOOK_SECRET=
+
+# GitLab
+GITLAB_URL=https://gitlab.com
+GITLAB_TOKEN=
+GITLAB_WEBHOOK_SECRET=
+```
+
+## Issue Trackers
+
+```bash
+# Jira
+JIRA_URL=
+JIRA_EMAIL=
+JIRA_API_TOKEN=
+JIRA_PROJECT_KEY=
+```
+
+## External Services
+
+```bash
+SEARXNG_URL=http://localhost:8888
+NVD_API_KEY=
+```
+
+## Authentication
+
+```bash
+KEYCLOAK_URL=http://localhost:8080
+KEYCLOAK_REALM=compliance
+KEYCLOAK_CLIENT_ID=compliance-dashboard
+REDIRECT_URI=http://localhost:8080/auth/callback
+APP_URL=http://localhost:8080
+```
+
+## Observability
+
+```bash
+# Set to enable OpenTelemetry export (omit to disable)
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=compliance-agent
+```
--- a/docs/deployment/keycloak.md
+++ b/docs/deployment/keycloak.md
@@ -0,0 +1,104 @@
+# Keycloak Authentication
+
+Compliance Scanner supports Keycloak for SSO authentication. When configured, all dashboard access requires signing in through Keycloak, and all API endpoints are protected.
+
+## How It Works
+
+### Dashboard (OAuth2/OIDC)
+
+The dashboard implements a standard OAuth2 Authorization Code flow with PKCE:
+
+1. User visits the dashboard
+2. If not authenticated, a login page shows with a "Sign in with Keycloak" button
+3. User is redirected to Keycloak's login page
+4. After authentication, Keycloak redirects back with an authorization code
+5. The dashboard exchanges the code for tokens and creates a session
+6. All subsequent `/api/` server function calls require a valid session
+
+### Agent API (JWT)
+
+The agent API validates JWT Bearer tokens from Keycloak:
+
+1. Dashboard (or other clients) include the access token in requests: `Authorization: Bearer <token>`
+2. The agent fetches Keycloak's JWKS (JSON Web Key Set) to validate the token signature
+3. Token expiry and claims are verified
+4. The health endpoint (`/api/v1/health`) is always public
+
+If `KEYCLOAK_URL` and `KEYCLOAK_REALM` are not set on the agent, JWT validation is disabled and all endpoints are open.
+
+## Keycloak Setup
+
+### 1. Create a Realm
+
+In the Keycloak admin console:
+
+1. Create a new realm (e.g. `compliance`)
+2. Note the realm name — you'll need it for `KEYCLOAK_REALM`
+
+### 2. Create a Client
+
+1. Go to **Clients** > **Create client**
+2. Set:
+   - **Client ID**: `compliance-dashboard`
+   - **Client type**: OpenID Connect
+   - **Client authentication**: Off (public client)
+3. Under **Settings**:
+   - **Valid redirect URIs**: `http://localhost:8080/auth/callback` (adjust for your domain)
+   - **Valid post logout redirect URIs**: `http://localhost:8080`
+   - **Web origins**: `http://localhost:8080`
+
+### 3. Create Users
+
+1. Go to **Users** > **Create user**
+2. Set username, email, first name, last name
+3. Under **Credentials**, set a password
+
+## Environment Variables
+
+```bash
+# Keycloak server URL (no trailing slash)
+KEYCLOAK_URL=http://localhost:8080
+
+# Realm name
+KEYCLOAK_REALM=compliance
+
+# Client ID (must match the client created above)
+KEYCLOAK_CLIENT_ID=compliance-dashboard
+
+# OAuth callback URL (must match valid redirect URI in Keycloak)
+REDIRECT_URI=http://localhost:8080/auth/callback
+
+# Application root URL (used for post-logout redirect)
+APP_URL=http://localhost:8080
+```
+
+## Dashboard Features
+
+When authenticated, the dashboard shows:
+
+- **User avatar** in the sidebar (from Keycloak profile picture, or initials)
+- **User name** from Keycloak profile
+- **Logout** link that clears the session and redirects through Keycloak's logout flow
+
+## Session Configuration
+
+Sessions use signed cookies with these defaults:
+
+- **Expiry**: 24 hours of inactivity
+- **SameSite**: Lax (required for Keycloak redirect flow)
+- **Secure**: Disabled by default (enable behind HTTPS)
+- **Storage**: In-memory (resets on server restart)
+
+::: tip
+For production, consider persisting sessions to Redis or a database so they survive server restarts.
+:::
+
+## Running Without Keycloak
+
+If no Keycloak variables are set:
+
+- The **dashboard** serves without authentication (all pages accessible)
+- The **agent API** accepts all requests without token validation
+- A warning is logged: `Keycloak not configured - API endpoints are unprotected`
+
+This is suitable for local development and testing.
--- a/docs/deployment/opentelemetry.md
+++ b/docs/deployment/opentelemetry.md
@@ -0,0 +1,139 @@
+# OpenTelemetry Observability
+
+Compliance Scanner exports traces and logs via OpenTelemetry Protocol (OTLP) for integration with observability platforms like SigNoz, Grafana (Tempo + Loki), Jaeger, and others.
+
+## Enabling
+
+Set the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to enable OTLP export:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+```
+
+When this variable is not set, telemetry export is disabled and only console logging is active.
+
+## What Is Exported
+
+### Traces
+
+Distributed traces for:
+
+- HTTP request handling (via `tower-http` `TraceLayer`)
+- Database operations
+- Scan pipeline phases
+- External API calls (LiteLLM, Keycloak, Git providers)
+
+### Logs
+
+All `tracing::info!`, `tracing::warn!`, `tracing::error!` log events are exported as OTel log records, including structured fields.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector gRPC endpoint | *(disabled)* |
+| `OTEL_SERVICE_NAME` | Service name in traces | `compliance-agent` or `compliance-dashboard` |
+| `RUST_LOG` | Log level filter | `info` |
+
+## Docker Compose Setup
+
+The included `docker-compose.yml` provides an OTel Collector service:
+
+```yaml
+otel-collector:
+  image: otel/opentelemetry-collector-contrib:latest
+  ports:
+    - "4317:4317"   # gRPC
+    - "4318:4318"   # HTTP
+  volumes:
+    - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
+```
+
+The agent and dashboard are pre-configured to send telemetry to the collector:
+
+```yaml
+agent:
+  environment:
+    OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
+    OTEL_SERVICE_NAME: compliance-agent
+
+dashboard:
+  environment:
+    OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
+    OTEL_SERVICE_NAME: compliance-dashboard
+```
+
+## Collector Configuration
+
+Edit `otel-collector-config.yaml` to configure your backend. The default exports to debug (stdout) only.
+
+### SigNoz
+
+```yaml
+exporters:
+  otlp/signoz:
+    endpoint: "signoz-otel-collector:4317"
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/signoz]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/signoz]
+```
+
+### Grafana Tempo (Traces) + Loki (Logs)
+
+```yaml
+exporters:
+  otlp/tempo:
+    endpoint: "tempo:4317"
+    tls:
+      insecure: true
+  loki:
+    endpoint: "http://loki:3100/loki/api/v1/push"
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/tempo]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [loki]
+```
+
+### Jaeger
+
+```yaml
+exporters:
+  otlp/jaeger:
+    endpoint: "jaeger:4317"
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger]
+```
+
+## Verifying
+
+After starting with telemetry enabled, look for this log on startup:
+
+```
+OpenTelemetry OTLP export enabled endpoint=http://otel-collector:4317 service=compliance-agent
+```
+
+If the endpoint is unreachable, the application still starts normally — telemetry export fails silently without affecting functionality.