Skip to content

SECURITY.md

Latest commit

 

History

History
551 lines (387 loc) · 22.9 KB

SECURITY.md

File metadata and controls

551 lines (387 loc) · 22.9 KB
Raw

🔐 Security Policy

ThemisDB Security Team

Status Baseline Gitleaks Responsible Disclosure

⚠️ IMPORTANT: ThemisDB is in active development. Canonical module and maturity status is tracked in ROADMAP.md and governed by DOCUMENTATION_GOVERNANCE.md.

📋 Supported Versions & Security Status

Caution

ThemisDB security module is currently in HARDENING status (see module table in ROADMAP.md). Do not use in production-critical environments without project-specific hardening review and validated release evidence.

Version / Line Status Security Module Notes
2.4.0 (current GA lane) 🟡 Human sign-off pending ✅ Technical GA gates PASS Final governance sign-off pending in docs/governance/GA_PROMOTION_SIGN_OFF.md §9
2.4.0-rc1 evidence baseline ✅ Technical PASS ✅ Wave 7/8/9 + sanitizer + pentest evidence complete See audit/AUDIT.md and audit/MATURITY_REPORT_2026-08.md
1.x and older ❌ Unsupported for current security posture claims ❌ Historical only Keep only as archival implementation history

🟢 Graph Module Phase 2.2 Security Verification (2026-07-01)

[!SUCCESS] Graph Module Phase 2.2 Security Sign-Off: All input validation and edge-case handling verified as production-quality.

Verification Summary

Scope: Graph module Phase 2.2 completion — explain_plan.cpp and path_constraints.cpp

Component Verification Status Notes
explain_plan.cpp Input validation for empty plans; toDot/toJson serialization guards ✅ PASS Defensive serialization patterns protect against malformed output
path_constraints.cpp Constraint evaluation edge cases; validation guards on uninitialized state ✅ PASS Edge-case guards prevent access to uninitialized constraint structures
Error Signals All empty returns documented and semantically correct ✅ PASS Error signals follow consistent defensive pattern taxonomy
Thread Safety Locking patterns reviewed for guard implementations ✅ PASS Appropriate lock types used where guards protect shared state
Test Coverage 39 gate tests passing (explain_plan, cost_model, path_constraints, constraint_propagation) ✅ PASS All defensive patterns verified by comprehensive unit tests

Key Findings

  • ✅ 0 new security gaps introduced in Phase 2.2
  • ✅ All input validation patterns verified as defensive and production-quality
  • ✅ No null-pointer or out-of-bounds vulnerabilities in edge-case handlers
  • ✅ Thread-safe access patterns confirmed in rotation/constraint modules

Evidence: ROADMAP.md § Graph Module Completion Phase 2.2 | docs/ARCHIVED/ai-working-history/GRAPH_PHASE_2_GATE_ANALYSIS.md

🚨 Reporting a Vulnerability

We take security vulnerabilities seriously. If you discover a security issue, please follow our responsible disclosure process.

❌ Do NOT

Caution

Never do these things:

  • ❌ Open a public GitHub issue for security vulnerabilities
  • ❌ Discuss the vulnerability publicly before it's addressed
  • ❌ Exploit the vulnerability beyond demonstration purposes

✅ Do

1️⃣ Report via GitHub Security Advisories (Recommended)
  1. Go to Security Advisories
  2. Create a new private security advisory
  3. Include:
    • 📝 Description of the vulnerability
    • 🔄 Steps to reproduce the issue
    • 💥 Potential impact assessment
    • 🛠️ Suggested fixes (optional)
2️⃣ Use Responsible Disclosure
  • ⏳ Give us reasonable time to address the issue
  • 🤐 No public disclosure before fix is released
  • 🤝 Coordinate disclosure timeline with security team
3️⃣ Provide Sufficient Detail

Help us reproduce and verify the issue:

  • 🖥️ Environment details (OS, version, configuration)
  • 📊 Proof-of-concept (PoC) code or steps
  • 📸 Screenshots or logs (if applicable)

Response Timeline

Timeframe Action Status
Within 24 hours Acknowledgment of your report 📨
Within 72 hours Initial assessment & severity classification 🔍
7-14 days Detailed response with remediation plan 📋
30-90 days Fix released (depending on severity/complexity) 🚀

Note

Critical vulnerabilities are prioritized and may receive expedited fixes within 7 days.

🧭 Governance and Escalation Ownership

To keep governance and community processes consistent across root-level documents:

Canonical contact/escalation channels:

🔁 Root-Dokument-Abgleich (Architektur / Audit / Tests / Performance)

Zur Auflösung von Widersprüchen zwischen Root-Leitdokumenten gilt folgende gemeinsame Baseline:

Bereich Verbindliche Aussage Primäre Nachweise
Architekturkonsistenz Sicherheitsmodell (Hardening, Transportschutz, AuthN/AuthZ, Audit-Trail) ist mit der Root-Architektur synchronisiert ARCHITECTURE.md, audit/AUDIT.md
Technische Kontrollen Auditierbare Kontrollen umfassen mindestens RBAC, verschlüsselte Audit-Logs, SAST/Secret/Container-Scans audit/AUDIT.md, audit/docs/audit-framework/AUDIT_RUNBOOK.md
Verifikationspfade Security-relevante Test-/Nachweiswege werden in CTest nachvollziehbar geführt CTEST.md
Performance-Randbedingungen Performance-Ziele und Optimierungen duerfen Sicherheitskontrollen nicht abschalten oder umgehen docs/performance/PERFORMANCE_EXPECTATIONS.md, docs/performance/PERFORMANCE_OPTIMIZATION_PLAN.md, docs/performance/PERFORMANCE_BOTTLENECKS.md

🧱 Security Tiering Model (Normativ)

ThemisDB uses a security tier model from trusted core modules to least-trusted plugin boundaries. This model is normative for architecture, implementation, and release review.

Primary reference: ARCHITECTURE.md

Tier Scope Mandatory Control Focus
T0: Trusted Core Core bootstrap and trust anchors Startup invariants, memory/lifecycle correctness, anti-tamper checks
T1: Security & Platform Services Identity, crypto, policy, config, audit RBAC, key isolation, immutable audit guarantees, production-mode enforcement
T2: Data Plane Engines Query, transaction, storage/index, replication/sharding Data integrity, recovery safety, quota/resource enforcement
T3: Interface & Protocol Edge HTTP/gRPC/Wire ingress and protocol handlers AuthN/AuthZ at ingress, parser bounds, DoS protection, tenant isolation
T4: Managed Extension Runtime In-tree extensions (LLM/content/model runtime) Capability gating, bounded runtime budgets, sanitized inputs/outputs
T5: Plugin Boundary Dynamic plugins and adapters Signature/provenance checks, sandboxing, capability-scoped invocation

⚠️ CRITICAL Security Gaps — Graph Module (Phase 2 Remediation)

Status: 2 CRITICAL semantic validation gaps in ontology_manager.cpp (T2: Data Plane Engines)

Gap Severity Description Mitigation Target
Type-Error Propagation 🔴 CRITICAL ontology_manager type constraints allow type mismatches to propagate unchecked; potential for silent data corruption in multi-model queries Phase 2.3 type-validation hardening; unit tests added to test_ontology_manager.cpp 2026-08-20
Semantic Constraint Bypass 🔴 CRITICAL path_constraints allows unvalidated constraint predicates in cross-shard queries; risk of query scope bypass (T3 → T2 boundary crossing) Phase 2.2 constraint-propagation audit; security-level test in test_constraint_propagation.cpp 2026-08-06

Primary Evidence: docs/ARCHIVED/ai-working-history/graph_l2_analysis.md Section 4 (Risk Assessment)
Action Items:

  1. Lock graph module from production releases until Phase 2.4 complete
  2. Assign T2/Security architect to Phase 2.3 validation work
  3. Add to SECURITY release checklist: graph module type/constraint tests must pass before RC candidate

Reference: ROADMAP.md § Graph Module Completion

Mandatory Tier Rules

  1. Dependencies are one-way: higher-numbered tiers can depend on lower-numbered tiers, never vice versa.
  2. T5 code must never directly invoke privileged T0/T1 internals without brokered policy checks.
  3. All T3/T4/T5 entry points require authentication, authorization, input validation, rate limiting, and audit events.
  4. Security decisions are fail-closed: uncertainty in auth/policy/config must reject the operation.
  5. Every tier-crossing public interface must document auth model, input contract, error behavior, and audit semantics.

Tier Evidence Required in PRs

  • State affected tier(s) and trust-boundary crossings in the PR description.
  • Provide at least one boundary-focused test for changed T3/T4/T5 code paths.
  • If a change alters effective trust level, include threat model delta and maintainer sign-off.

🛡️ Security Measures

ThemisDB implements defense-in-depth security across all layers:

🔑 Authentication & Authorization
  • ✅ RBAC (Role-Based Access Control) with 4-tier hierarchy
  • ✅ mTLS (Mutual TLS) for client authentication
  • ✅ Token-based API authentication
  • ✅ HashiCorp Vault integration for secrets management

Security Level: ⭐⭐⭐⭐⭐

🌐 Network Protocol Security (v1.3.0+)
Protocol Security Features TLS Version
HTTP/2 Server Push, TLS 1.3 required 1.3+
WebSocket WSS (WebSocket Secure) 1.2+
MQTT TLS/mTLS support, auth required 1.2+
PostgreSQL Wire SSL/TLS encryption, RBAC 1.2+
MCP Server Transport security (stdio/SSE/WS) 1.2+

[!IMPORTANT] All protocols require explicit opt-in build switches for production readiness.

🔒 Encryption

Data-at-Rest:

  • 🔐 AES-256-GCM encryption
  • 🗄️ Field-Level Encryption (schema-based selective encryption)
  • 🔑 Key Management: HSM (PKCS#11), Vault, or Mock providers

Data-in-Transit:

  • 🌐 TLS 1.3 (with TLS 1.2 fallback)
  • 🔗 Perfect Forward Secrecy (PFS)
  • 📜 Certificate pinning for HSM/TSA

🛡️ Security Hardening (v1.4.2+):

[!WARNING] NEW: HSM Stub Provider Gating

  • ⚠️ Requires explicit opt-in via THEMIS_ALLOW_HSM_STUB=1
  • ❌ Fails in production mode (THEMIS_PRODUCTION_MODE=1)
  • 🔍 Auto-detects production environments (ENVIRONMENT=production)
  • 📋 See: HSM Production Setup

[!NOTE] VaultSigningProvider Limitation

  • ✅ Signing operations only (Transit Engine)
  • ❌ Key management operations throw clear errors
  • 📖 Migration path: Use VaultKeyProvider for full key management
  • 📋 See: Vault Signing Provider

[!TIP] PKCS#11 Integration Strategy

  • 📁 Development: pkcs11_minimal.h (built-in, limited)
  • 🏭 Production: Vendor PKCS#11 headers (required)
  • ✅ Compile-time validation for header compatibility
  • 📋 See: PKCS#11 Integration
✅ Input Validation
  • 📋 JSON Schema validation
  • 💉 AQL injection prevention
  • 🚫 Path traversal protection
  • 📦 Request body size limits (10MB default)
  • 🔍 BPMN/EPK/YAML parser hardening (src/process/) — regex-based BPMN parser rejects malformed XML; EPK and VCC-VPB parsers validate schema before import
🚦 Rate Limiting & DoS Protection
  • ⏱️ Token bucket algorithm (100 req/min default)
  • 🌍 Per-IP rate limiting
  • 👤 Per-user rate limiting
  • ⚙️ Configurable thresholds
📊 Audit & Compliance

Audit Logging:

  • 📝 65+ security event types
  • 🔐 Encrypt-then-Sign audit logs
  • 🔗 Hash chain for tamper detection
  • 🔔 SIEM integration (Syslog RFC 5424, Splunk HEC)
  • 🗂️ Maintenance operations (src/maintenance/) — all schedule CRUD and job lifecycle events logged via AuditLogger; RBAC roles maintenance:read, maintenance:write, maintenance:admin

Compliance Ready:

  • ✅ GDPR/DSGVO
  • ✅ eIDAS
  • ✅ SOC 2
  • ✅ HIPAA

🔒 Security Hardening

Important

For production deployments, start with the Security Posture Guide — it explicitly lists every insecure default, why it is unsafe, and the exact environment variable to change it. Then follow the Production Runbook for the full reference of required and optional environment variables, startup sequence, and failure-mode mitigations.

Hardening Checklist

Step Action Priority
1️⃣ Set THEMIS_PRODUCTION_MODE=1 and THEMIS_ENVIRONMENT=production 🔴 Critical
2️⃣ Set THEMIS_TOKEN_ADMIN to a strong random secret (≥32 bytes) 🔴 Critical
3️⃣ Enable TLS with strong cipher suites 🔴 Critical
4️⃣ Configure RBAC with least-privilege principle 🔴 Critical
5️⃣ Use external key management: Vault or hardware HSM 🟡 High
6️⃣ Enable audit logging with encryption and SIEM sink 🟡 High
7️⃣ Enable WAL gRPC mTLS (THEMIS_WAL_GRPC_ENABLE_MTLS=1) 🟡 High
8️⃣ Configure rate limiting appropriately 🟢 Medium
9️⃣ Set up monitoring and alerting 🟢 Medium
🔟 Regular security updates and patching 🔴 Critical

📚 Security Documentation

⭐ Production Security (Start Here)
Core Security Guides
Advanced Security Topics
🆕 Knowledge Graph Protection (2026)

Protection against AI data theft and knowledge graph exfiltration:

Topics covered:

  • Systematic graph exfiltration detection
  • Vector embedding theft prevention
  • Training data extraction protection
  • Access pattern anomaly detection
  • Graph watermarking & fingerprinting (planned)

🤝 Vulnerability Disclosure Policy

We follow responsible disclosure practices:

1️⃣ Acknowledgment

Security researchers who responsibly disclose vulnerabilities will be acknowledged in our security advisories (unless they prefer to remain anonymous).

2️⃣ No Legal Action

We will not take legal action against security researchers who:

  • ✅ Act in good faith
  • ✅ Follow this security policy
  • ✅ Do not access or modify other users' data
  • ✅ Do not disrupt our services
3️⃣ CVE Coordination

For significant vulnerabilities, we will coordinate CVE assignment with MITRE.

🔍 Security Scanning

Automated security scanning is integrated into our CI/CD pipeline.

Tools

Tool Purpose Integration
Gitleaks Secret detection in source code ✅ CI/CD
clang-tidy Static analysis for C++ code ✅ CI/CD
cppcheck Additional C++ security checks ✅ CI/CD
Trivy Container image vulnerability scanning ✅ CI/CD
OWASP ZAP Dynamic application security testing 🚧 Planned
Comprehensive Audit Systematic security & compliance audit ✅ Available

Run Scans Locally

Comprehensive Security Audit (Recommended)

Run a systematic security audit covering SAST, dependency scanning, secret detection, and more:

# Full audit (requires tools: cppcheck, clang-tidy, trivy, gitleaks, semgrep)
./scripts/comprehensive-code-audit.sh

# Quick audit (skip time-consuming checks)
AUDIT_QUICK=1 ./scripts/comprehensive-code-audit.sh

# Audit with specific categories
./scripts/comprehensive-code-audit.sh --skip-dependencies --skip-dynamic

# View all options
./scripts/comprehensive-code-audit.sh --help

Audit Report: Results are saved in audit-results-<timestamp>/comprehensive-audit-report.md

Compliance Coverage: BSI C5, ISO 27001, DSGVO, NIS2, OWASP ASVS, NIST CSF

Individual Security Tools 
# Secret detection
gitleaks detect --source . --verbose

# Static analysis
cppcheck --enable=warning,style --inconclusive ./src ./include
clang-tidy src/**/*.cpp -- -std=c++20

# Dependency scanning
trivy fs --scanners vuln,secret,misconfig .

# Semgrep patterns
semgrep --config=auto src/ include/

📞 Security Contact

Method Purpose Link
🔒 GitHub Security Advisories Report vulnerabilities (Recommended) Report
💬 GitHub Issues Non-sensitive security discussions Issues
🔑 PGP Key Encrypted communications Available upon request

Note

Response Time: Within 24 hours for initial acknowledgment.

📅 Changelog

Date Event
2026-03 📝 Added src/process/ (BPMN parser hardening) and src/maintenance/ (RBAC audit trail) security notes
2026-01 🔒 Major security improvements in v1.3.4 (RocksDB, Docker, Updates)
2025-12 🔐 Update Checker security features & Manifest signing design
2025-11 📝 Initial security policy publication

🔒 Recent Security Work (archival v1.x context)

Note

Archival security summary (v1.3.0 - v1.3.4):
See Security Work Summary for detailed information about recent security improvements.

Highlights (v1.3.4)

RocksDB Wrapper Security Fixes:

  • ✅ 7 critical vulnerabilities fixed (use-after-free, null-pointer, memory leaks)
  • ✅ 8 medium-severity issues resolved (deadlocks, resource leaks)
  • 📊 100% elimination of segfault risks
  • 📖 Full Audit Report

Docker Security Improvements:

  • ✅ Ubuntu 24.04 LTS base image (extended security support)
  • ✅ Automated security updates during build
  • ✅ 80%+ reduction in CVEs
  • 📖 Docker Security Fixes

Update Checker Security:

  • ✅ Token masking and secure handling
  • ✅ HTTPS-only communication
  • ✅ Thread-safe implementation
  • 📖 Update Security Summary

Binary Authenticity (Design):

  • ✅ Cryptographic manifest signing architecture
  • ✅ SHA-256 hash verification
  • ✅ RSA-4096 digital signatures
  • 📖 Manifest Security

🔐 Security is a top priority at ThemisDB

🚨 Report a Vulnerability · 📖 Security Docs · 🛡️ Security Posture Guide

Zuletzt geprueft (Root-Sync): 2026-05-26