Skip to content

CONFIGURATION.md

Latest commit

 

History

History
133 lines (113 loc) · 10.6 KB

CONFIGURATION.md

File metadata and controls

133 lines (113 loc) · 10.6 KB
Raw

ISCY Configuration

ISCY Community wird lokal und auf eigener Infrastruktur betrieben. Production darf nicht mit Demo- oder Entwicklungsannahmen starten.

Betriebsmodi

Variable Zweck Erforderlich Sicherer Standard Gueltige Werte Sicherheitsauswirkung Secret-Datei
ISCY_APP_MODE Betriebsmodus Production: ja development development, demo, production Steuert Preflight, Cookie- und Header-Grenzen nein
DATABASE_URL Datenbankverbindung Production: ja keine sqlite:*, postgres://*, postgresql://* Beispielwerte werden in Production abgewiesen ja, DATABASE_URL_FILE
RUST_BACKEND_BIND Bind-Adresse nein 127.0.0.1:9000 Socket-Adresse 0.0.0.0 verlangt in Production einen bestaetigten Reverse Proxy nein
ISCY_MEDIA_ROOT Evidence-/Upload-Speicher nein media Pfad Muss durch Betreiber gesichert, gesichert und wiederherstellbar sein nein
ISCY_TRUST_PROXY_IDENTITY_HEADERS Akzeptiert x-iscy-* Identity-Header nein Production: 0 0/1, true/false Nur aktivieren, wenn ein vertrauenswuerdiger Proxy eingehende gleichnamige Client-Header entfernt nein
ISCY_TRUSTED_PROXY_CONFIGURED Proxy-Vertrauensgrenze bestaetigt Production bei Public Bind: ja 0 0/1, true/false Erlaubt Production-Bind auf 0.0.0.0 und optionales Header-Vertrauen nein
ISCY_SECURE_COOKIES Setzt Session-Cookie mit Secure Production: ja Production: 1 0/1, true/false Verhindert Session-Cookie ueber unsicheres HTTP nein
ISCY_HTTPS_CONFIRMED HTTPS ist fuer Nutzerzugriff bestaetigt fuer HSTS: ja 0 0/1, true/false Voraussetzung fuer HSTS nein
ISCY_HSTS_ENABLED Aktiviert Strict-Transport-Security nein 0 0/1, true/false Darf nur nach bestaetigtem HTTPS aktiv sein nein
ISCY_ALERTMANAGER_TOKEN Webhook-Secret Production: ja keine starkes Secret, mind. 24 Zeichen Schuetzt Alertmanager-Webhook ja, ISCY_ALERTMANAGER_TOKEN_FILE
ISCY_ALERTMANAGER_TENANT_ID Fester Tenant fuer Alertmanager-Persistenz fuer automatische Persistenz ausserhalb Development: ja leer positive Ganzzahl Bindet das Webhook-Token serverseitig an genau einen Tenant nein
ISCY_ALERTMANAGER_USER_ID Fester technischer User fuer Alertmanager-Persistenz fuer automatische Persistenz ausserhalb Development: ja leer positive Ganzzahl Muss gemeinsam mit ISCY_ALERTMANAGER_TENANT_ID gesetzt sein; Request-Header koennen den Service-Principal nicht ueberschreiben nein
ISCY_ALERTMANAGER_HMAC_SECRET Optionales HMAC-Secret fuer Alertmanager nein leer starkes Secret Signiert timestamp.body und reduziert Spoofing-/Replay-Risiko ja, ISCY_ALERTMANAGER_HMAC_SECRET_FILE
ISCY_ALERTMANAGER_HMAC_PREVIOUS_SECRET Altes HMAC-Secret fuer Rotation nein leer starkes Secret Erlaubt kurze Secret-Rotation ohne Monitoring-Ausfall ja, ISCY_ALERTMANAGER_HMAC_PREVIOUS_SECRET_FILE
ISCY_ALERTMANAGER_HMAC_MAX_AGE_SECONDS Replay-Fenster fuer HMAC-Timestamps nein 300 positive Sekunden Alte oder weit zukuenftige Signaturen werden abgewiesen nein
ISCY_AGENT_NOTIFICATION_INTERVAL_SECONDS Agent-Policy-Notification-Worker nein 300 0 oder mindestens 60 Sekunden 0 deaktiviert; kleinere positive Werte werden auf 60 Sekunden begrenzt nein
ISCY_SHUTDOWN_TIMEOUT_SECONDS Graceful-Shutdown-Grenze nein 30 5 bis 120 Sekunden Begrenzt das Auslaufen laufender HTTP-Requests nach SIGINT/SIGTERM nein
ISCY_NOTIFICATION_ALLOW_HTTP Erlaubt HTTP-Webhookziele ausser Loopback nein 0 0/1, true/false Nur fuer kontrollierte Entwicklungsnetze; Production sollte HTTPS nutzen nein
ISCY_NOTIFICATION_WEBHOOK_ALLOWED_HOSTS Production-Allowlist fuer Notification-Ziele Production bei aktivem Kanal: ja leer kommaseparierte exakte Hostnamen Verhindert freie serverseitige Webhook-Ziele; Redirects bleiben deaktiviert nein
ISCY_AGENT_NOTIFICATION_SECRET Bearer-/HMAC-Secret fuer Agent-Notification-Webhooks bei geschuetztem Kanal: ja leer starkes Secret Einzige erlaubte Secret-Referenz fuer tenant-konfigurierbare Notification-Kanaele nein
ISCY_INITIAL_ADMIN_TENANT_NAME Tenant-Name fuer init-admin fuer init-admin empfohlen ISCY Production Tenant Text Erstzugang ohne Demo-Seed nein
ISCY_INITIAL_ADMIN_TENANT_SLUG Tenant-Slug fuer init-admin fuer init-admin empfohlen iscy-production Kleinbuchstaben, Zahlen, Bindestrich Eindeutige Mandantenkennung nein
ISCY_INITIAL_ADMIN_USERNAME Initialer Admin-Username fuer init-admin empfohlen iscy-admin Text Wird nicht ueberschrieben, wenn aktiver Admin existiert nein
ISCY_INITIAL_ADMIN_EMAIL Initiale Admin-E-Mail fuer init-admin empfohlen iscy-admin@example.local E-Mail/Text Kontaktadresse des Erstadmins nein
ISCY_INITIAL_ADMIN_FIRST_NAME Initialer Admin-Vorname nein ISCY Text Anzeigeprofil des Erstadmins nein
ISCY_INITIAL_ADMIN_LAST_NAME Initialer Admin-Nachname nein Admin Text Anzeigeprofil des Erstadmins nein
ISCY_INITIAL_ADMIN_PASSWORD Initiales Admin-Passwort fuer init-admin ja keine mind. 14 Zeichen, kein Beispielwert Erzeugt ersten Admin ohne Demo-Zugangsdaten ja, ISCY_INITIAL_ADMIN_PASSWORD_FILE
ISCY_POSTGRES_RESTORE_DRILL_SOURCE_URL Disposable PostgreSQL-Quelle fuer Restore-Drill nur fuer Drill leer PostgreSQL-URL Wird durch make rust-postgres-restore-drill mit Demo-Daten initialisiert nein
ISCY_POSTGRES_RESTORE_DRILL_RESTORE_URL Disposable PostgreSQL-Ziel fuer Restore-Drill nur fuer Drill leer PostgreSQL-URL Ziel-Schema wird beim Drill geloescht und aus Dump wiederhergestellt nein
NVD_API_KEY Optionaler NVD API Key nein leer Secret Wird nur als apiKey-Header zur fest verdrahteten offiziellen NVD-API gesendet und nie protokolliert ja, NVD_API_KEY_FILE
ISCY_VULNERABILITY_SYNC_INTERVAL_SECONDS Periodischer Vulnerability-Intelligence-Runner nein 0 0 oder 7200 bis 604800 Sekunden 0 deaktiviert; jeder Feed laeuft isoliert, vorhandene Daten bleiben bei Ausfall erhalten nein

Secret-Dateien

Fuer Container, NixOS und systemd koennen *_FILE-Varianten auf gemountete Secret-Dateien zeigen. Direkter Env-Wert und zugehoerige *_FILE-Quelle sind gegenseitig ausgeschlossen; sind beide gesetzt, bricht ISCY mit der sicheren Fehlerklasse ambiguous_source ab. Dateien muessen absolut, regulaer, symlinkfrei, hoechstens 16 KiB gross und ohne Group-/Other-Rechte sein. Nur abschliessende CR-/LF-Bytes werden entfernt. Der Default-Root ist /run/secrets; weitere absolute Wurzeln muessen explizit ueber ISCY_SECRET_ROOTS beziehungsweise fuer S3-Referenzen ueber ISCY_EVIDENCE_SECRET_ROOTS freigegeben werden.

Unterstuetzt sind DATABASE_URL_FILE, NVD_API_KEY_FILE, ISCY_INITIAL_ADMIN_PASSWORD_FILE, ISCY_ALERTMANAGER_TOKEN_FILE, ISCY_ALERTMANAGER_HMAC_SECRET_FILE, ISCY_ALERTMANAGER_HMAC_PREVIOUS_SECRET_FILE, ISCY_EVIDENCE_OBJECT_STORAGE_ACCESS_KEY_FILE, ISCY_EVIDENCE_OBJECT_STORAGE_SECRET_KEY_FILE und ISCY_EVIDENCE_OBJECT_STORAGE_SESSION_TOKEN_FILE. Das offizielle PostgreSQL-Image verwendet getrennt POSTGRES_PASSWORD_FILE. Secrets duerfen nicht ins Repository, in Logs, Metriken, Nix-Strings oder Supportpakete geschrieben werden.

Production-Minimum

ISCY_APP_MODE=production
ISCY_SECRETS_DIR=./.runtime/secrets
DATABASE_URL_FILE=/run/secrets/database_url
POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password
RUST_BACKEND_BIND=0.0.0.0:9000
ISCY_TRUSTED_PROXY_CONFIGURED=1
ISCY_TRUST_PROXY_IDENTITY_HEADERS=0
ISCY_SECURE_COOKIES=1
ISCY_HTTPS_CONFIRMED=1
ISCY_HSTS_ENABLED=1
ISCY_ALERTMANAGER_TOKEN_FILE=/run/secrets/iscy_alertmanager_token
ISCY_ALERTMANAGER_HMAC_SECRET_FILE=/run/secrets/iscy_alertmanager_hmac_secret
ISCY_AGENT_NOTIFICATION_INTERVAL_SECONDS=300
ISCY_SHUTDOWN_TIMEOUT_SECONDS=30
ISCY_NOTIFICATION_ALLOW_HTTP=0
ISCY_NOTIFICATION_WEBHOOK_ALLOWED_HOSTS=soc-webhook.example.org
ISCY_AGENT_NOTIFICATION_SECRET=<strong-channel-secret>
ISCY_INITIAL_ADMIN_PASSWORD_FILE=/run/secrets/iscy_initial_admin_password
NVD_API_KEY_FILE=/run/secrets/nvd_api_key
ISCY_EVIDENCE_OBJECT_STORAGE_ACCESS_KEY_FILE=/run/secrets/iscy_s3_access_key
ISCY_EVIDENCE_OBJECT_STORAGE_SECRET_KEY_FILE=/run/secrets/iscy_s3_secret_key
ISCY_SECRET_ROOTS=/run/secrets
ISCY_EVIDENCE_SECRET_ROOTS=/run/secrets
ISCY_VULNERABILITY_SYNC_INTERVAL_SECONDS=7200

Ein Agent-Notification-Kanal speichert fuer Bearer oder HMAC nur den Namen ISCY_AGENT_NOTIFICATION_SECRET, nie den Secret-Wert. Andere Environment-Variablen werden beim Speichern und erneut vor jeder Zustellung abgewiesen. Die referenzierte Variable muss im Backend-Prozess gesetzt sein.

Identity-Header duerfen produktiv nur aktiviert werden, wenn der Reverse Proxy eingehende x-iscy-tenant-id, x-iscy-user-id, x-iscy-user-email, x-iscy-roles, x-iscy-is-staff und x-iscy-is-superuser immer entfernt und nur selbst neu setzt.

Die Vulnerability-Intelligence-Quellen sind nicht konfigurierbar: NVD API 2.0, der CISA-KEV-JSON-Katalog und die FIRST-EPSS-API werden ausschliesslich ueber ihre fest definierten offiziellen HTTPS-URLs angesprochen. Freie Feed-URLs, Redirects, private oder lokale Ziele und file:// werden abgewiesen. Ohne Netzverbindung oder NVD-Key startet ISCY weiterhin; lediglich der jeweilige Sync-Lauf meldet einen begrenzten Fehlerstatus.

Initial-Admin ohne Demo-Seed

Produktive Systeme sollten mit Migrationen und einem eigenen Initial-Admin starten:

DATABASE_URL_FILE=/run/secrets/database_url \
ISCY_INITIAL_ADMIN_PASSWORD_FILE=/run/secrets/iscy_initial_admin_password \
nix run .#iscy-backend -- init-admin

init-admin fuehrt Migrationen aus, legt bei Bedarf einen Tenant und einen aktiven Admin an und seedet keine Demo-Daten.

Restore-Drills

Der lokale Standard-Smoke startet eine isolierte Rust-Instanz, legt einen echten Evidence-Upload an und restauriert SQLite-Datenbank plus Media-Verzeichnis. Der Drill prueft anschliessend, ob die restaurierte Evidence-Zeile denselben Dateipfad referenziert und ob die SHA-256-Pruefsumme der Datei unveraendert ist:

nix develop --command make rust-restore-smoke

Fuer PostgreSQL kann ein Drill gegen zwei wegwerfbare Testdatenbanken aktiviert werden. Das Ziel-Schema wird geloescht.

ISCY_POSTGRES_RESTORE_DRILL_SOURCE_URL=postgresql://isms:<password>@localhost:5432/iscy_drill_source \
ISCY_POSTGRES_RESTORE_DRILL_RESTORE_URL=postgresql://isms:<password>@localhost:5432/iscy_drill_restore \
nix develop --command make rust-postgres-restore-drill