audit_api_implementation

ThemisDB Audit API – Implementierung & Hardening ✅

Stand: 5. Dezember 2025
Version: 1.0.0
Kategorie: Development

---

Datum: 7. November 2025
Status: REST-API implementiert, Hardening (URL-Decoding, erweiterter ISO8601 Parser, Rate-Limiting) aktiv, Tests grün

---

Implementierte Komponenten

1. C++ Backend (themis_server)

AuditApiHandler (include/server/audit_api_handler.h, src/server/audit_api_handler.cpp)

Funktionalität:

• Liest und dekodiert verschlüsselte Audit-Logs aus JSONL-Datei (data/logs/audit.jsonl)
• Entschlüsselt encrypt-then-sign Payloads mit FieldEncryption
• Filtert Logs nach mehreren Kriterien
• Paginierung (1-1000 Einträge pro Seite)
• CSV-Export

Strukturen:

struct AuditLogEntry {
    int64_t id, timestamp_ms;
    std::string user, action, entity_type, entity_id;
    std::string old_value, new_value;
    bool success;
    std::string ip_address, session_id, error_message;
};

struct AuditQueryFilter {
    int64_t start_ts_ms, end_ts_ms;
    std::string user, action, entity_type, entity_id;
    bool success_only;
    int page, page_size;
};

Methoden:

• queryAuditLogs(filter) → JSON mit entries[], totalCount, page, pageSize, hasMore
• exportAuditLogsCsv(filter) → CSV-String mit escaped Feldern

HTTP-Endpunkte (http_server.cpp)

GET /api/audit

• Query-Parameter: start, end, user, action, entity_type, entity_id, success, page, page_size
• Antwort: application/json

{
  "entries": [...],
  "totalCount": 1234,
  "page": 1,
  "pageSize": 100,
  "hasMore": true
}

GET /api/audit/export/csv

• Gleiche Query-Parameter
• Antwort: text/csv mit Datei-Download

Features (aktuell):

• ISO 8601 Datum-Parsing: Unterstützung für YYYY-MM-DDTHH:MM:SS, optionale Millisekunden (.fff), sowie Zeitzonen Z oder Offset ±HH:MM (Normalisierung nach UTC)
• Epoch-Millis als Alternative (numerischer Parameterwert)
• Vollständiges URL-Decoding (Percent-Encoding inkl. + → Leerzeichen)
• Case-insensitive Filterung der Erfolg-Parameter (success=true|1|yes)
• Automatische Sortierung (neueste zuerst)
• CSV-Export mit konfigurierbarer Page-Size (bis 10.000)
• Rate-Limiting pro Minute pro (Route + Authorization-Token oder anonym) mit Retry-After
• Integration mit Audit-Logger (encrypt-then-sign) Infrastruktur

---

2. .NET Frontend (Themis.AuditLogViewer)

ThemisApiClient.cs

• REST-Client für themis_server
• GetAuditLogsAsync(filter) → ApiResponse
• ExportAuditLogsToCsvAsync(filter) → ApiResponse<byte[]>
• Query-String-Builder mit URL-Encoding
• Konfigurierbar via appsettings.json

MockThemisApiClient.cs

• Generiert 1234 simulierte Audit-Einträge
• Für Tests ohne laufenden Server
• Gleiche Schnittstelle wie echter Client

WPF-Anwendung

• MVVM mit DataGrid (11 Spalten)
• Filter: Datum, User, Action, Entity, Success-Only
• Paginierung mit Vor/Zurück-Buttons
• CSV-Export mit SaveFileDialog
• Loading-Indikator, Statusleiste
• Dependency Injection (Microsoft.Extensions.DI)

---

Build-Status (Kurz)

• C++ Server: Endpunkte in HttpServer integriert, Unit- und HTTP-Tests vorhanden (siehe tests/test_http_audit.cpp).
• .NET Tools: WPF Viewer vorhanden unter tools/Themis.AuditLogViewer (optionale Nutzung).

---

Dateistruktur

c:\VCC\themis\
├── include\server\
│   ├── audit_api_handler.h          ✅ NEU
│   └── http_server.h                ✅ ERWEITERT
├── src\server\
│   ├── audit_api_handler.cpp        ✅ NEU (188 Zeilen)
│   └── http_server.cpp              ✅ ERWEITERT (+170 Zeilen)
├── tools\
│   ├── Themis.sln
│   ├── README.md
│   ├── STATUS.md
│   ├── MOCK_MODE.md
│   ├── Themis.AdminTools.Shared\
│   │   ├── ApiClient\
│   │   │   ├── ThemisApiClient.cs          ✅ REST-Client
│   │   │   └── MockThemisApiClient.cs       ✅ Mock
│   │   └── Models\
│   │       ├── AuditLogModels.cs           ✅ DTOs
│   │       └── Common.cs                   ✅ Shared
│   └── Themis.AuditLogViewer\
│       ├── App.xaml + .cs                  ✅ DI-Setup
│       ├── appsettings.json                ✅ Config
│       ├── ViewModels\
│       │   └── MainWindowViewModel.cs      ✅ MVVM
│       └── Views\
│           └── MainWindow.xaml + .cs       ✅ UI
└── CMakeLists.txt                          ✅ ERWEITERT

---

Integration in themis_server

Initialisierung (http_server.cpp – Konstruktor)

// Audit Logger (neu)
themis::utils::AuditLoggerConfig audit_cfg;
audit_cfg.log_path = "data/logs/audit.jsonl";
audit_logger_ = std::make_shared<themis::utils::AuditLogger>(
    field_enc, pki_client, audit_cfg);

// Audit API Handler (neu)
audit_api_ = std::make_unique<themis::server::AuditApiHandler>(
    field_enc, pki_client, audit_cfg.log_path);

Routing (http_server.cpp)

if (path_only == "/api/audit" && method == http::verb::get)
    return Route::AuditQueryGet;
if (path_only == "/api/audit/export/csv" && method == http::verb::get)
    return Route::AuditExportCsvGet;

Handler-Dispatch (http_server.cpp)

case Route::AuditQueryGet:
    response = handleAuditQuery(req);
    break;
case Route::AuditExportCsvGet:
    response = handleAuditExportCsv(req);
    break;

---

Funktionsweise

Workflow: Audit-Log-Eintrag → UI

1. Anwendung → AuditLogger::logEvent(event)
2. AuditLogger → Verschlüsselt Payload (FieldEncryption)
3. AuditLogger → Signiert Hash mit PKI
4. AuditLogger → Schreibt JSONL-Zeile in data/logs/audit.jsonl
   {
     "ts": 1730476800000,
     "category": "AUDIT",
     "payload": { "ciphertext_b64": "...", "iv_b64": "...", "tag_b64": "..." },
     "signature": { "sig_b64": "...", "cert_serial": "..." }
   }

5. WPF-App → GET /api/audit?start=...&user=admin&page=1
6. HttpServer::handleAuditQuery() → AuditApiHandler::queryAuditLogs()
7. AuditApiHandler → Liest JSONL-Datei Zeile für Zeile
8. AuditApiHandler → Entschlüsselt payload mit FieldEncryption
9. AuditApiHandler → Parsed JSON-Event aus entschlüsseltem Payload
10. AuditApiHandler → Filtert nach Query-Parametern
11. AuditApiHandler → Sortiert nach Timestamp (neueste zuerst)
12. AuditApiHandler → Paginiert (z.B. Zeilen 1-100)
13. HttpServer → Gibt JSON zurück
14. WPF-App → Zeigt Einträge im DataGrid

---

Beispiel-Requests

Alle Logs der letzten 7 Tage

GET /api/audit?start=2025-10-25T00:00:00&end=2025-11-01T23:59:59&page=1&page_size=100

Nur fehlerhafte Aktionen von User "admin"

GET /api/audit?user=admin&success=false&page=1

CSV-Export aller CREATE-Aktionen

GET /api/audit/export/csv?action=CREATE&page_size=10000

---

Nächste Schritte

Sofort testbar (Mock-Modus)

cd c:\VCC\themis\tools\Themis.AuditLogViewer
# Folge Anleitung in MOCK_MODE.md
dotnet run

Integration-Test mit echtem Server

1. Server starten:

   cd c:\VCC\themis\build
   .\Release\themis_server.exe

2. Audit-Logs generieren:

   • Führe beliebige CRUD-Operationen aus (PUT /entities, POST /query, etc.)
   • Logs werden automatisch in data/logs/audit.jsonl geschrieben

3. WPF-App konfigurieren:

   // tools\Themis.AuditLogViewer\appsettings.json
   {
     "ThemisServer": {
       "BaseUrl": "http://localhost:8080"
     }
   }

4. App starten:

   cd c:\VCC\themis\tools\Themis.AuditLogViewer
   dotnet run

5. Testen:

   • Filter anwenden (Datum, User, Action)
   • Paginierung durchklicken
   • CSV exportieren

---

Bekannte Limitierungen

C++ API

• Authentifizierung/Autorisierung: Wenn Tokens via Env gesetzt sind, verlangen die Endpunkte den Scope audit:read. Der ADMIN‑Token erhält diesen Scope automatisch. (Readonly-Token kann optional erweitert werden.)
• Rate-Limiting ist aktuell statisch pro Minute (fester 60s Zeitschlitz, keine gleitenden Fenster)
• Page-Size für JSON Query auf 1000 begrenzt; CSV auf 10.000 – kein Streaming-Paging für große Exporte
• ISO 8601 Parser deckt kein Wochen-/Ordinaldatum und keine rein Minuten/UTC-Abkürzungen ab (nur Basis-Format + Offset)
• URL-Decoder deckt kein Unicode-Normalisierungs-Handling ab (Byte-orientiert)

.NET App

• Keine Unit-Tests
• Keine Internationalisierung (nur Deutsch)
• Export auf 10k Einträge limitiert
• Keine Fehler-Wiederholung bei Netzwerkfehlern

---

Verbesserungsideen

Kurzfristig

• Rollen/Scopes feinjustieren (z. B. readonly optional mit audit:read)
• Dynamisches Rate-Limiting (gleitende Fenster / Token-Leaky-Bucket)
• Erweiterter ISO 8601 Parser (Edge Cases, Validierung, Reject invalid)
• Einheitliches Error-Handling mit strukturiertem Fehlerobjekt (Fehlercode, Tracking-ID)

Auth & Scopes (Beispiel)

• ADMIN‑Token per Umgebung setzen (erhält audit:read):
  • Windows PowerShell:
    • $env:THEMIS_TOKEN_ADMIN = "<geheimer-token>"
  • Linux/macOS:
    • export THEMIS_TOKEN_ADMIN=<geheimer-token>
• Request mit Bearer Header:
  • Authorization: Bearer <geheimer-token>

Mittelfristig

• WebSocket/SSE für Echtzeit-Updates
• Elasticsearch / Columnar Secondary Store für schnelle Filterung
• Grafische Auswertungen (Charts, Heatmaps)
• Excel-Export zusätzlich zu CSV

Langfristig

• KI-basierte Anomalie-Erkennung
• SIEM-Integration (Splunk, ELK-Stack)
• Multi-Tenant-Fähigkeit inkl. Mandanten-Trennung der Audit-Dateien
• Audit-Log-Kompression / Rotation (z. B. zstd + Zeitindex)

---

Rate-Limiting Details

Die Audit-Endpunkte nutzen ein einfaches Fenster-basiertes Limiting:

Merkmal	Wert
Konfiguration	Env THEMIS_AUDIT_RATE_LIMIT (Standard: 100)
Fenster	60 Sekunden (fixe Zeitscheiben)
Schlüssel	route + ':' + Authorization-Header oder anon
Antworten bei Limit	HTTP 429 mit Header Retry-After: 60, X-RateLimit-Limit, X-RateLimit-Remaining

Beispiel:

GET /api/audit?page=1&page_size=10
Authorization: Bearer <token>
→ Nach >N Requests innerhalb einer Minute: 429

Erweiterungsideen:

• Sliding Window / Token Bucket für gleichmäßigere Verteilung
• Metriken (Prometheus) für aktuelle Bucket-Auslastung
• Differenzierte Limits für JSON vs. CSV Export

URL-Decoding

Aktuelle Implementierung ersetzt:

• + → Leerzeichen
• %HH → Byte (hexadezimal)

Nicht unterstützt:

• Mehrfache Kodierung (%252F → %2F → / nur einstufig)
• UTF-8 Validierung – Bytes werden roh übernommen

Zeitstempel-Parsing

Akzeptierte Formen:

1730860000000          # Epoch Millis
2025-11-07T10:15:30Z   # Zulu
2025-11-07T10:15:30.123Z
2025-11-07T11:15:30+01:00
2025-11-07T09:15:30-01:00

Fehlerhafte oder nicht erkannte Eingaben → 0 (Aktuell stillschweigend; zukünftige Änderung: 400 Bad Request)

Sicherheit & Scopes

Benötigter Scope für beide Endpunkte: audit:read. Aktuell vergebene Scopes (Umgebungsvariablen):

Token	Env Variable	Standard-Scopes
Admin	THEMIS_TOKEN_ADMIN	admin, config:read, config:write, cdc:read, cdc:admin, metrics:read, data:read, data:write, audit:read
ReadOnly	THEMIS_TOKEN_READONLY	metrics:read, config:read, data:read, cdc:read, audit:read
Analyst	THEMIS_TOKEN_ANALYST	metrics:read, data:read, cdc:read

Hinweis: Analyst-Token erhält aktuell keinen audit:read Scope – bewusst getrennt.

Header-Beispiel:

Authorization: Bearer <ADMIN_TOKEN>

Fehlerantworten (aktuell)

Status	Grund
400	Ungültige Parameter (z. B. page < 1)
401	Fehlender oder ungültiger Authorization-Header
403	Token ohne erforderlichen Scope
429	Rate Limit erreicht
500	Interner Fehler beim Lesen/Entschlüsseln

Struktur (Beispiel 429):

{"error":true,"message":"Rate limit exceeded","status_code":429}

Geplante Vereinheitlichung: { "error": { "code": "rate_limit", "message": "...", "retry_after": 60 } }

Beispiel für erweiterten Query mit Offset und URL-Encoding

GET /api/audit?user=alice%2Badmin&action=VIEW%2FACCESS&start=1969-12-31T00:00:00Z&end=2100-01-01T00:00:00%2B02:00&page=1&page_size=10

Environment Konfiguration Zusammenfassung

Variable	Bedeutung
THEMIS_AUDIT_RATE_LIMIT	Requests pro Minute (0 = kein Limit)
THEMIS_TOKEN_ADMIN	Admin-Token mit umfassenden Scopes
THEMIS_TOKEN_READONLY	Optionaler ReadOnly-Token

Tests

tests/test_http_audit.cpp enthält u. a.:

• QueryReturnsSingleEntry – Basisfunktion
• CsvExportReturnsHeaderAndRow – CSV-Export
• UrlDecodingAndIso8601RangeAndRateLimit – URL-Decoding, ISO8601 mit Offset, Rate-Limit (429)

Nächste Dokumentationsschritte

• OpenAPI (openapi/openapi.yaml) um 429-Schema erweitern
• Einheitliches Fehlerobjekt spezifizieren
• Beispiel für Audit-spezifische Governance-Header aufnehmen
• Performance-Hinweise (große CSV Exporte vs. JSON Paging)

---

Erstellt & gepflegt: VS Code Copilot – Aktualisiert nach Hardening

---

Erstellt: VS Code Copilot
Zusammenfassung: themis_server REST API vollständig implementiert und getestet (Build ✅)