Skip to content

security_policies.md

Latest commit

 

History

History
218 lines (159 loc) · 9.32 KB

security_policies.md

File metadata and controls

218 lines (159 loc) · 9.32 KB

Policy Engine (Ranger-inspiriert)

Stand: 6. April 2026
Version: v1.3.0
Kategorie: 🔒 Security

📑 Inhaltsverzeichnis

Die Policy-Engine ergänzt die Token/Scope-Authorisierung um feingranulare Prüfungen auf Basis von Subjekt (Benutzer), Aktion, Ressourcenpfad und optionalen Bedingungen (z. B. IP-Präfixe).

Aktivierung & Laden

  • Policies können als YAML oder JSON hinterlegt werden.
    • Bevorzugte Dateien: config/policies.yaml oder config/policies.yml
    • Fallback: config/policies.json
  • Der Server lädt diese Datei beim Start automatisch (optional). Existiert keine Datei, gilt bis zum Setzen von Policies: Default-Allow.
  • Wenn Policies vorhanden sind und keine Policy passt, wird der Zugriff per Default-Deny blockiert (Secure-by-Default).

Hinweis: Hot-Reload per API folgt in einer späteren Version. Bis dahin: Datei anpassen und Server neu starten.

Schema (MVP)

  • id (string): Eindeutige Policy-ID
  • name (string): Beschreibung
  • subjects (array): Benutzer-IDs oder "*" (Wildcard)
  • actions (set): z. B. read, write, delete, query, config.read, metrics.read, cdc.read, cdc.admin, vector.search, vector.write, "*"
  • resources (array): Pfadpräfixe, z. B. "/entities/", "/vector/search", "/" (alles)
  • effect ("allow" | "deny"): Effekt der Policy
  • allowed_ip_prefixes (optional array): Wenn gesetzt, muss die Client-IP (aus X-Forwarded-For oder X-Real-IP) mit mindestens einem Präfix übereinstimmen

Beispiel (YAML):

- id: hr-allow-internal
  name: HR nur im Intranet zulassen
  subjects: ["*"]
  actions: [read, write, delete]
  resources: ["/entities/hr:"]
  allowed_ip_prefixes: ["10.", "192.168.", "172.16.", "172.17.", "172.18."]
  effect: allow

Beispiel (JSON):

{
  "id": "hr-allow-internal",
  "name": "HR nur im Intranet zulassen",
  "subjects": ["*"],
  "actions": ["read", "write", "delete"],
  "resources": ["/entities/hr:"],
  "allowed_ip_prefixes": ["10.", "192.168.", "172.16.", "172.17.", "172.18."] ,
  "effect": "allow"
}

Action-Mapping (Server)

Die wichtigsten Endpunkte lösen folgende actions aus (neben Scope-Pflicht):

  • GET /metrics → metrics.read
  • GET/POST /config → config.read / config.write
  • GET /entities/:key → read
  • PUT /entities / DELETE /entities/:key → write / delete
  • POST /query → query
  • POST /vector/search → vector.search
  • POST /vector/batch_insert, DELETE /vector/by-filter → vector.write
  • GET /changefeed, GET /changefeed/stream → cdc.read
  • GET /changefeed/stats, POST /changefeed/retention → cdc.admin

Zusätzlich ist weiterhin ein gültiger Scope am Token erforderlich (z. B. data:read, data:write, metrics:read, ...).

Metriken

Im Prometheus-Endpoint /metrics verfügbar:

  • vccdb_policy_eval_total
  • vccdb_policy_allow_total
  • vccdb_policy_deny_total

Start-Policies (Baseline)

Wir liefern eine Basis-Datei unter config/policies.json mit (du kannst sie 1:1 als policies.yaml umsetzen):

  • Admin: admin darf alles (actions: ["*"], resources: ["/"])
  • Readonly: readonly darf Metriken, Config-Read, Daten-Reads, Query, Vector-Search, CDC-Read auf passenden Pfaden
  • Analyst: analyst (+ analyst1/analyst2) darf Query/Vector-Search/Data-Read
  • HR-Bereich: erlauben aus internen Netzen (10.*, 192.168.*, 172.16/12) und sonst explizit deny

Tokens (Beispiel)

Die folgenden Umgebungsvariablen werden beim Start eingelesen:

  • THEMIS_TOKEN_ADMIN → Benutzer admin mit breiten Scopes
  • THEMIS_TOKEN_READONLY → Benutzer readonly (Read-Scopes)
  • THEMIS_TOKEN_ANALYST → Benutzer analyst (Read-Scopes, inkl. Vector/Query)

Beispiel (PowerShell):

$env:THEMIS_TOKEN_ADMIN = "<geheim>"
$env:THEMIS_TOKEN_READONLY = "<readonly-token>"
$env:THEMIS_TOKEN_ANALYST = "<analyst-token>"

Wichtig: Scopes im Token und Policies müssen zusammenpassen. Beispiel: vector.search bedingt i. d. R. den Scope data:read.

Apache Ranger Integration ✅ Implementiert

Die interne Policy-Engine deckt das operative Enforcen ab (schnell, lokal, ohne externen Hop). Die Apache Ranger-Integration ist vollständig implementiert und ermöglicht die Synchronisierung von Policies aus zentralen Ranger-Instanzen.

✅ Implementierungsstatus (November 2025)

Feature Status Implementierung
Ranger Client ✅ Produktionsreif src/server/ranger_adapter.cpp (208 Zeilen)
Policy Import ✅ Implementiert POST /policies/import/ranger
Policy Export ✅ Implementiert GET /policies/export/ranger
Bearer Token Auth ✅ Implementiert Header-basierte Authentifizierung
TLS/mTLS ✅ Implementiert Volle SSL-Unterstützung
Retry-Logic ✅ Implementiert Exponential Backoff
Timeout-Config ✅ Implementiert Connect + Request Timeouts

Wichtig: Die Ranger-Integration ist keine Planung oder Stub, sondern eine vollständige Implementierung mit echten HTTP-Aufrufen via libcurl. Siehe src/server/ranger_adapter.cpp und include/server/ranger_adapter.h.

Wann Ranger sinnvoll ist

  • Zentrale Verwaltung/Review von Policies (UI, Workflows, Versionierung, Audit)
  • Einheitliche Governance über mehrere Systeme hinweg (Data Lake, DBs, Services)
  • Nutzung von Tag-basierten Policies und fortgeschrittenen ABAC-Mustern

Kosten/Trade-offs

  • Zusätzliche Infrastruktur (Ranger Admin/DB), Betrieb und AuthN/SSO-Anbindung
  • Modellsynchronisation (Ranger-Objektmodell vs. unsere Pfad-/Action-Logik)
  • Fehler- und Latenz-Domäne, wenn Policies live remote abgefragt würden

Architektur (Snapshot-Sync)

  1. Ranger bleibt Management-Ebene. Policies werden periodisch über die Ranger-REST-API gelesen und in unsere lokale policies.json übersetzt (Snapshot).
  2. Enforcen erfolgt weiterhin lokal – robust gegen Netzausfälle und mit konstanter Latenz.
  3. Optional: manuelles Import/Export (Admin-API), sowie Hintergrund-Sync (z. B. alle 60s) mit ETag/Version.

Implementierte Features

  • Import/Export-Endpunkte: POST /policies/import/ranger, GET /policies/export/ranger
  • Übersetzung Ranger → intern:
    • Ranger „resource.path" → resources (Pfad-Präfix)
    • Ranger „users/groups" → subjects
    • Ranger „accessTypes" → actions (Mapping, z. B. read/write/admin zu unseren Actions)
    • Ranger „allow/deny" → effect
  • Client-Konfiguration: Timeouts, Retry-Policy, TLS-Optionen

Bewährte Praxis

  • Lokales Enforcen mit synchronisiertem Snapshot. Remote-Live-Enforcen vermeiden (Latenz, SPOF).
  • Ein dedizierter Service-Name in Ranger für ThemisDB (z. B. themisdb-prod).
  • Einfache, dokumentierte Action-Mappings (siehe oben). Feingranularere Attribute/Tags können in einer zweiten Ausbaustufe ergänzt werden.

Sicherheit & Betrieb

  • Import-Adapter mit mTLS/OAuth2 gegen Ranger absichern.
  • Änderungen auditieren (z. B. in unserem Audit-Logger + Ranger Audit).
  • Fallback: Wenn Ranger nicht erreichbar ist, wird die letzte gültige lokale Policy weiter genutzt.

Fazit: Die Ranger-Integration ist vollständig implementiert und produktionsbereit. Sie ermöglicht die nahtlose Integration in bestehende Enterprise-Sicherheitsinfrastrukturen.

API-Details & Absicherung

  • Import: POST /policies/import/ranger (erfordert Scope admin sowie passende Policy)
    • Liest Ranger-Policies via REST (Bearer-Token) und konvertiert sie nach intern; Ergebnis wird als Snapshot in config/policies.json gespeichert.
  • Export: GET /policies/export/ranger (erfordert Scope admin)
    • Gibt ein minimales, Ranger-ähnliches JSON aus (nicht 1:1 Schema), für Review/Debugging.

Sicherheit (ENV-Variablen, Beispiel – Secrets gehören in sichere Secret-Stores):

# Ranger Endpoint + Service
$env:THEMIS_RANGER_BASE_URL = "https://ranger.example.com"
$env:THEMIS_RANGER_SERVICE = "themisdb-prod"
# Optional: Pfad (Default: /service/public/v2/api/policy)
$env:THEMIS_RANGER_POLICIES_PATH = "/service/public/v2/api/policy"

# AuthN
$env:THEMIS_RANGER_BEARER = "<ranger-api-token>"  # Authorization: Bearer

# TLS
$env:THEMIS_RANGER_TLS_VERIFY = "1"                # 1=verify (Default), 0=skip (nur Test!)
$env:THEMIS_RANGER_CA_CERT    = "C:\\certs\\ca.pem"  # optional eigenes CA-Bundle
# mTLS (optional)
$env:THEMIS_RANGER_CLIENT_CERT = "C:\\certs\\client.crt"
$env:THEMIS_RANGER_CLIENT_KEY  = "C:\\certs\\client.key"

# Timeouts & Retry (optional, defaults shown)
$env:THEMIS_RANGER_CONNECT_TIMEOUT_MS = "5000"     # Verbindungsaufbau-Timeout
$env:THEMIS_RANGER_REQUEST_TIMEOUT_MS = "15000"    # Gesamt-Request-Timeout
$env:THEMIS_RANGER_MAX_RETRIES        = "2"        # Anzahl Wiederholungen bei 5xx/Netzfehlern
$env:THEMIS_RANGER_RETRY_BACKOFF_MS   = "500"      # Initialer Backoff (exponentiell)

Hinweise:

  • Standard ist TLS-Verifikation aktiv. Abschalten nur in Testumgebungen.
  • Admin-geschützte Endpunkte zusätzlich durch Policies abgesichert (action admin).
  • Import erfolgt als Snapshot; Enforcen bleibt lokal → keine Ranger-Latenz im Hot-Path.