graph_protection.yaml

# Graph Protection Configuration Example
#
# This configuration file demonstrates recommended settings for protecting
# knowledge graphs and vector embeddings from unauthorized extraction.
#
# Based on research: "Making Stolen Data Unusable for AI Training" (2026)
# https://www.golem.de/news/schutz-fuer-wissensgraphen-forscher-machen-gestohlene-daten-fuer-ki-unbrauchbar-2601-203870.html

# ============================================================================
# GRAPH PROTECTION SETTINGS
# ============================================================================

graph_protection:
  # Enable graph-specific security features
  enabled: true
  
  # -------------------------------------------------------------------------
  # ACCESS MONITORING
  # Track and analyze access patterns to detect potential data exfiltration
  # -------------------------------------------------------------------------
  access_monitoring:
    enabled: true
    
    # Log all graph traversal operations (BFS, DFS, shortest path, etc.)
    track_traversals: true
    
    # Log all bulk export operations
    track_exports: true
    
    # Log vector embedding queries
    track_embedding_access: true
    
    # Enable real-time anomaly detection
    anomaly_detection: true
    
    # Anomaly detection thresholds
    anomaly_thresholds:
      # Alert if user traverses more than N nodes per minute
      max_nodes_per_minute: 5000
      
      # Alert if user performs more than N deep traversals per hour
      max_deep_traversals_per_hour: 50
      
      # Alert if user exports more than N MB per day
      max_export_mb_per_day: 500
      
      # Alert if user accesses embeddings more than N times per minute
      max_embedding_queries_per_minute: 100
    
    # Suspicious pattern detection
    patterns:
      # Detect systematic node enumeration (e.g., sequential PK access)
      detect_enumeration: true
      
      # Detect exhaustive graph crawling
      detect_crawling: true
      
      # Detect time-of-day anomalies (e.g., bulk access at 3 AM)
      detect_temporal_anomalies: true
      
      # Detect geographic anomalies (e.g., access from unusual locations)
      detect_geographic_anomalies: true
  
  # -------------------------------------------------------------------------
  # RATE LIMITING
  # Restrict query volume and complexity to prevent bulk extraction
  # -------------------------------------------------------------------------
  rate_limits:
    # Graph traversal limits
    max_traversal_depth: 5                # Maximum BFS/DFS depth
    max_nodes_per_query: 1000            # Maximum nodes returned per query
    max_edges_per_query: 10000           # Maximum edges returned per query
    
    # Vector search limits
    max_embeddings_per_query: 500        # Maximum embeddings per KNN search
    max_vector_dimensions: 1536          # Maximum embedding dimensions
    
    # Query frequency limits (per user)
    queries_per_minute: 50               # General query limit
    graph_queries_per_minute: 30         # Graph-specific queries
    vector_queries_per_minute: 100       # Vector search queries
    traversals_per_hour: 200             # Deep traversal operations
    
    # Bulk operation limits
    bulk_operations_per_day: 10          # Maximum bulk exports per day
    
    # Concurrent query limits
    max_concurrent_queries: 5            # Per user
    
    # Time-window based limits
    hourly_node_access_limit: 50000      # Nodes per hour
    daily_data_transfer_limit_mb: 1000   # MB per day
  
  # -------------------------------------------------------------------------
  # EXPORT CONTROLS
  # Restrict and monitor bulk data exports
  # -------------------------------------------------------------------------
  export_controls:
    # Disable bulk export by default (enable only for approved users)
    bulk_export_enabled: false
    
    # Require manual approval for large exports
    require_approval: true
    approval_threshold_mb: 100           # Exports > 100 MB require approval
    
    # Maximum export size limits
    max_export_size_mb: 500              # Hard limit per export
    max_export_nodes: 100000             # Maximum nodes per export
    max_export_edges: 500000             # Maximum edges per export
    
    # Export audit trail
    audit_all_exports: true
    include_export_hash: true            # Hash exported data for tracking
    
    # Watermarking for exports (Phase 2 - optional)
    watermark_exports: false             # Enable after watermarking implemented
    
    # Export scheduling (restrict to business hours)
    restrict_to_business_hours: false
    business_hours:
      start: "08:00"
      end: "18:00"
      timezone: "UTC"
  
  # -------------------------------------------------------------------------
  # GRAPH WATERMARKING (Phase 2 - Future Feature)
  # Embed imperceptible marks in graph structure for theft detection
  # -------------------------------------------------------------------------
  watermarking:
    # Enable graph watermarking (requires implementation)
    enabled: false
    
    # Watermark strength (low, medium, high)
    # Higher strength = more robust but potentially more detectable
    strength: medium
    
    # Watermark method
    method: edge_perturbation      # Options: edge_perturbation, dummy_nodes, weight_modification
    
    # Watermark key rotation
    key_rotation_days: 90
    
    # Watermark verification
    verify_on_export: true
    verify_on_query: false         # May impact performance
  
  # -------------------------------------------------------------------------
  # EMBEDDING PROTECTION (Phase 2 - Future Feature)
  # Add imperceptible noise to embeddings for fingerprinting
  # -------------------------------------------------------------------------
  embedding_protection:
    # Enable embedding fingerprinting (requires implementation)
    enabled: false
    
    # Noise magnitude (0.0 - 1.0)
    # Lower values = less impact on search quality
    noise_magnitude: 0.01
    
    # Noise method
    method: deterministic_gaussian  # Options: deterministic_gaussian, laplace, uniform
    
    # Fingerprint verification
    verify_on_access: false        # May impact performance
    
    # Secret key management
    key_rotation_days: 90
    use_hsm: true                  # Use Hardware Security Module if available
  
  # -------------------------------------------------------------------------
  # DIFFERENTIAL PRIVACY (Phase 3 - Future Feature)
  # Add noise to aggregations for privacy preservation
  # -------------------------------------------------------------------------
  differential_privacy:
    # Enable differential privacy (requires implementation)
    enabled: false
    
    # Privacy parameters
    epsilon: 1.0                   # Privacy budget (lower = more private)
    delta: 1e-5                    # Failure probability
    
    # Apply to specific query types
    apply_to_aggregations: true
    apply_to_counts: true
    apply_to_statistics: true
    
    # Noise mechanism
    mechanism: laplace             # Options: laplace, gaussian
    
    # Privacy budget management
    budget_per_user_per_day: 10.0
    budget_reset_interval_hours: 24

# ============================================================================
# INTEGRATION WITH EXISTING SECURITY FEATURES
# ============================================================================

security:
  # -------------------------------------------------------------------------
  # RBAC INTEGRATION
  # Define graph-specific permissions
  # -------------------------------------------------------------------------
  rbac:
    enabled: true
    
    # Example roles with graph permissions
    roles:
      - name: data_viewer
        graph_permissions:
          read: true
          traverse: true
          max_depth: 3
          export: false
          
      - name: data_analyst
        graph_permissions:
          read: true
          traverse: true
          max_depth: 5
          export: true
          export_approval_required: true
          
      - name: data_scientist
        graph_permissions:
          read: true
          traverse: true
          max_depth: 10
          export: true
          bulk_export: true
          export_approval_required: false
          
      - name: admin
        graph_permissions:
          read: true
          write: true
          traverse: true
          max_depth: -1  # unlimited
          export: true
          bulk_export: true
          configure_protection: true
  
  # -------------------------------------------------------------------------
  # AUDIT LOGGING
  # Enhanced logging for graph operations
  # -------------------------------------------------------------------------
  audit:
    enabled: true
    
    # Graph-specific events
    log_events:
      - GRAPH_TRAVERSAL
      - BULK_NODE_ACCESS
      - BULK_EDGE_ACCESS
      - EMBEDDING_EXPORT
      - GRAPH_EXPORT
      - TEMPORAL_QUERY
      - ANOMALY_DETECTED
      
    # Include detailed metadata
    include_query_details: true
    include_access_patterns: true
    include_data_volume: true
    
    # Retention
    retention_days: 365
    
    # SIEM integration
    siem_enabled: true
  
  # -------------------------------------------------------------------------
  # ENCRYPTION
  # Protect data at rest and in transit
  # -------------------------------------------------------------------------
  encryption:
    # Field-level encryption for sensitive graph attributes
    field_encryption: true
    
    # Vector embedding encryption
    vector_encryption: true
    
    # Encrypt audit logs
    audit_log_encryption: true

# ============================================================================
# MONITORING & ALERTING
# ============================================================================

monitoring:
  # Prometheus metrics
  prometheus:
    enabled: true
    
    # Graph-specific metrics
    metrics:
      - themis_graph_traversal_depth
      - themis_graph_nodes_accessed
      - themis_graph_edges_accessed
      - themis_embeddings_queried
      - themis_graph_exports_total
      - themis_graph_anomalies_detected
      
  # Alert rules
  alerts:
    - name: SuspiciousGraphTraversal
      condition: rate(themis_graph_traversal_depth_bucket{le="10"}[5m]) > 10
      severity: warning
      description: "Unusual deep graph traversal detected"
      
    - name: BulkGraphExport
      condition: rate(themis_graph_nodes_exported[5m]) > 1000
      severity: critical
      description: "Large-scale graph export detected"
      
    - name: EmbeddingTheft
      condition: rate(themis_embeddings_queried[5m]) > 500
      severity: warning
      description: "Suspicious embedding access pattern"
      
    - name: GraphAnomalyDetected
      condition: themis_graph_anomalies_detected > 0
      severity: high
      description: "Anomalous graph access pattern detected"

# ============================================================================
# DEPLOYMENT RECOMMENDATIONS
# ============================================================================

# For production deployments:
# 1. Start with conservative limits and adjust based on legitimate usage
# 2. Enable access monitoring and review logs regularly
# 3. Configure alerts for suspicious activities
# 4. Conduct regular security audits
# 5. Plan for Phase 2 features (watermarking, fingerprinting) if needed
# 6. Document approved export workflows
# 7. Train users on security best practices

# For high-security environments:
# 1. Enable all monitoring features
# 2. Set strict rate limits
# 3. Require approval for all exports
# 4. Implement watermarking (Phase 2)
# 5. Enable differential privacy (Phase 3) for aggregations
# 6. Use HSM for key management
# 7. Deploy in air-gapped network if possible