Compliance Guide

Comprehensive guidance for deploying Aegis-DB in regulated environments


Table of Contents

  1. Overview
  2. Supported Frameworks
    1. HIPAA (Healthcare)
    2. GDPR (EU Privacy)
    3. CCPA/CPRA (California Privacy)
    4. FERPA (Education)
    5. SOC 2 Type II
  3. Quick Start
    1. Environment Variables
    2. Minimum Configuration
    3. Verify Compliance Endpoints
  4. GDPR Compliance
    1. Right to Erasure (Article 17)
      1. Delete Data Subject
      2. Deletion Scopes
      3. Delete from Specific Collections
    2. Deletion Certificates
      1. List All Certificates
      2. Get Specific Certificate
      3. Verify Certificate Integrity
    3. Right to Data Portability (Article 20)
      1. Export Data (JSON Format)
      2. Export Data (CSV Format)
      3. Export with Date Range
      4. Export Specific Collections
    4. Consent Management (Article 7)
      1. Record Consent
      2. Supported Consent Purposes
      3. Get Consent Status
      4. Check Specific Consent
      5. Withdraw Consent
      6. Get Consent History (Audit Trail)
  5. CCPA Compliance
    1. Do Not Sell
      1. Opt Out of Data Sale
      2. Get Do Not Sell List
      3. Check Do Not Sell Status
    2. Right to Delete
    3. Right to Know
  6. HIPAA Compliance
    1. Encryption Requirements
      1. Enable TLS (In Transit)
      2. Enable Encryption at Rest
    2. Audit Logging
      1. View Audit Log
      2. Verify Audit Log Integrity
    3. Breach Notification
  7. FERPA Compliance
    1. Access Control
    2. Consent for Disclosures
  8. SOC 2 Type II
    1. Security Monitoring
    2. Change Management
    3. Incident Response
  9. Breach Detection
    1. Configuration
      1. Set Detection Thresholds
    2. Webhook Setup
    3. Security Event Types
    4. List Breach Incidents
      1. Filter by Status
      2. Filter by Severity
    5. Incident Response
      1. Acknowledge Incident
      2. Resolve Incident
      3. Mark as False Positive
    6. Generate Incident Report
    7. Get Breach Statistics
    8. List Security Events
      1. Filter by Event Type
  10. Audit Trail
    1. Hash Chain Verification
    2. Verify Integrity
    3. Compliance Reports
      1. Export Deletion Audit Trail
      2. Export Consent Audit Trail
  11. Consent Management
    1. Consent Statistics
    2. Export Consent Data
    3. Delete Consent Data
  12. API Reference
    1. Compliance Endpoints Summary
  13. Best Practices
    1. Data Retention
    2. Consent Collection
    3. Incident Response
    4. Audit Compliance

  1. Overview
  2. Supported Frameworks
  3. Quick Start
  4. GDPR Compliance
  5. CCPA Compliance
  6. HIPAA Compliance
  7. FERPA Compliance
  8. SOC 2 Type II
  9. Breach Detection
  10. Audit Trail
  11. Consent Management
  12. API Reference

Overview

Aegis-DB provides built-in compliance features to help organizations meet regulatory requirements:

Feature Description Regulations
Right to Erasure Delete all data for a data subject GDPR Art. 17, CCPA
Data Portability Export data in machine-readable formats GDPR Art. 20, CCPA
Consent Management Track and enforce user consent GDPR Art. 7, CCPA
Do Not Sell CCPA-specific opt-out tracking CCPA/CPRA
Breach Detection Real-time security monitoring GDPR, HIPAA, SOC 2
Audit Logging Immutable hash-chain audit trail All frameworks
Encryption AES-256 at rest, TLS 1.3 in transit HIPAA, SOC 2
Access Control RBAC with 25+ permissions All frameworks

All compliance endpoints are available under /api/v1/compliance/ and require authentication.


Supported Frameworks

HIPAA (Healthcare)

The Health Insurance Portability and Accountability Act requires safeguards for Protected Health Information (PHI).

Aegis-DB HIPAA Features:

  • Encryption at rest (AES-256) and in transit (TLS 1.3)
  • Comprehensive audit logging with tamper detection
  • Breach detection and notification system
  • Role-based access control
  • Automatic session timeout
  • MFA/2FA support

GDPR (EU Privacy)

The General Data Protection Regulation governs personal data processing for EU residents.

Aegis-DB GDPR Features:

  • Right to erasure (Article 17)
  • Right to data portability (Article 20)
  • Consent management (Article 7)
  • Data processing records
  • Breach notification within 72 hours
  • Privacy by design

CCPA/CPRA (California Privacy)

The California Consumer Privacy Act and California Privacy Rights Act protect California residents.

Aegis-DB CCPA Features:

  • Right to know (data export)
  • Right to delete
  • Do Not Sell tracking
  • Opt-out mechanisms
  • Non-discrimination enforcement

FERPA (Education)

The Family Educational Rights and Privacy Act protects student education records.

Aegis-DB FERPA Features:

  • Access control by role
  • Audit logging of record access
  • Consent management for disclosures
  • Data minimization support

SOC 2 Type II

Service Organization Control 2 covers security, availability, processing integrity, confidentiality, and privacy.

Aegis-DB SOC 2 Features:

  • Security monitoring and alerting
  • Access control and authentication
  • Change management tracking
  • Incident response procedures
  • Comprehensive audit trails

Quick Start

Environment Variables

# Enable compliance features
export AEGIS_COMPLIANCE_ENABLED=true

# Configure breach notification webhook
export AEGIS_BREACH_WEBHOOK_URL=https://your-alerting-system.com/webhook

# Configure audit log retention (days)
export AEGIS_AUDIT_RETENTION_DAYS=2555  # 7 years for HIPAA

# Enable encryption at rest
export AEGIS_ENCRYPTION_AT_REST=true
export AEGIS_ENCRYPTION_KEY=/path/to/encryption.key

# TLS configuration
export AEGIS_TLS_CERT=/path/to/server.crt
export AEGIS_TLS_KEY=/path/to/server.key

Minimum Configuration

# Start server with TLS and compliance features
cargo run -p aegis-server -- \
  --tls \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

Verify Compliance Endpoints

# Authenticate first
TOKEN=$(curl -s -X POST http://localhost:9090/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your_password"}' | jq -r '.token')

# Test compliance endpoints
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9090/api/v1/compliance/consent/stats

GDPR Compliance

Right to Erasure (Article 17)

GDPR Article 17 grants data subjects the right to have their personal data erased. Aegis-DB provides a comprehensive deletion endpoint that removes data from all stores (KV, documents, SQL tables, and graph).

Delete Data Subject

# Delete all data for a user
curl -X DELETE "http://localhost:9090/api/v1/compliance/data-subject/user@example.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "requestor": "privacy-team@company.com",
    "reason": "GDPR erasure request",
    "scope": {"type": "all"},
    "secure_erase": true
  }'

Response:

{
  "success": true,
  "certificate": {
    "id": "DEL-20260126153000-user@exa",
    "subject_id": "user@example.com",
    "timestamp": "2026-01-26T15:30:00Z",
    "total_items": 47,
    "total_bytes": 125840,
    "verification_hash": "a1b2c3d4e5f6...",
    "verified_by": "node-1",
    "secure_erase_performed": true
  },
  "message": "Data deletion completed successfully"
}

Deletion Scopes

Scope Description Use Case
all Delete from all data stores Standard GDPR request
specific_collections Delete from named collections only Partial deletion
exclude_audit_logs Delete all except audit logs Legal hold scenario

Delete from Specific Collections

curl -X DELETE "http://localhost:9090/api/v1/compliance/data-subject/user@example.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "requestor": "admin@company.com",
    "reason": "Partial deletion request",
    "scope": {
      "type": "specific_collections",
      "collections": ["users", "orders", "preferences"]
    }
  }'

Deletion Certificates

Each deletion generates a cryptographically signed certificate for compliance proof.

List All Certificates

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/certificates"

Get Specific Certificate

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/certificates/DEL-20260126153000-user@exa"

Verify Certificate Integrity

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/certificates/DEL-20260126153000-user@exa/verify"

Response:

{
  "valid": true,
  "certificate": { ... },
  "message": "Certificate is valid and has not been tampered with"
}

Right to Data Portability (Article 20)

GDPR Article 20 grants data subjects the right to receive their data in a structured, commonly used, machine-readable format.

Export Data (JSON Format)

curl -X POST "http://localhost:9090/api/v1/compliance/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "format": "json"
  }'

Response:

{
  "success": true,
  "export_id": "EXP-20260126153000-user@exa",
  "subject_id": "user@example.com",
  "format": "json",
  "generated_at": "2026-01-26T15:30:00Z",
  "total_items": 156,
  "data": {
    "subject_id": "user@example.com",
    "data": {
      "kv": [
        {
          "location": "kv_store",
          "item_id": "user:preferences:user@example.com",
          "data": { "theme": "dark", "language": "en" }
        }
      ],
      "document": [
        {
          "location": "users",
          "item_id": "doc-123",
          "data": { "name": "John Doe", "email": "user@example.com" }
        }
      ],
      "sql": [
        {
          "location": "orders",
          "item_id": "email=user@example.com/row-0",
          "data": { "order_id": 1001, "total": 99.99 }
        }
      ],
      "graph": [
        {
          "location": "graph_store",
          "item_id": "node-user-123",
          "data": { "id": "node-user-123", "label": "User", "edges": [] }
        }
      ]
    }
  }
}

Export Data (CSV Format)

curl -X POST "http://localhost:9090/api/v1/compliance/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "format": "csv"
  }'

Export with Date Range

curl -X POST "http://localhost:9090/api/v1/compliance/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "format": "json",
    "date_range": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2026-01-01T00:00:00Z"
    }
  }'

Export Specific Collections

curl -X POST "http://localhost:9090/api/v1/compliance/export" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "format": "json",
    "scope": {
      "type": "specific_collections",
      "collections": ["users", "orders"]
    }
  }'

Consent Management (Article 7)

GDPR Article 7 requires demonstrable consent for data processing.

curl -X POST "http://localhost:9090/api/v1/compliance/consent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "purpose": "marketing",
    "granted": true,
    "source": "web_form",
    "version": "2.0",
    "metadata": {
      "ip_address": "192.168.1.100",
      "consent_text": "I agree to receive marketing communications"
    }
  }'
Purpose Description
marketing Marketing communications
analytics Usage tracking and analytics
third_party_sharing Sharing data with third parties
data_processing General data processing
personalization Personalized recommendations
location_tracking Geolocation services
profiling Automated decision-making
cross_device_tracking Cross-device tracking
advertising Targeted advertising
research Research and statistics
do_not_sell CCPA Do Not Sell opt-out
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com"
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com/check/marketing"
curl -X DELETE "http://localhost:9090/api/v1/compliance/consent/user@example.com/marketing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User requested withdrawal via email"
  }'
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com/history"

CCPA Compliance

Do Not Sell

CCPA requires businesses to honor consumer requests to opt out of the sale of personal information.

Opt Out of Data Sale

curl -X POST "http://localhost:9090/api/v1/compliance/consent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user@example.com",
    "purpose": "do_not_sell",
    "granted": true,
    "source": "web_form",
    "version": "1.0"
  }'

Get Do Not Sell List

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/do-not-sell"

Check Do Not Sell Status

Before selling or sharing data, check if the user has opted out:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com/check/do_not_sell"

Response:

{
  "subject_id": "user@example.com",
  "purpose": "do_not_sell",
  "granted": true
}

If granted is true, do NOT sell this user’s data.

Right to Delete

Same as GDPR Right to Erasure. See Right to Erasure.

Right to Know

Same as GDPR Data Portability. See Right to Data Portability.


HIPAA Compliance

Encryption Requirements

HIPAA requires encryption of Protected Health Information (PHI) at rest and in transit.

Enable TLS (In Transit)

# Generate or obtain certificates
# Then start server with TLS
cargo run -p aegis-server -- \
  --tls \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

Enable Encryption at Rest

export AEGIS_ENCRYPTION_AT_REST=true
export AEGIS_ENCRYPTION_KEY=/path/to/encryption.key

# Generate a secure encryption key
openssl rand -base64 32 > /path/to/encryption.key
chmod 600 /path/to/encryption.key

Audit Logging

HIPAA requires logging of all access to PHI.

View Audit Log

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/audit/user@example.com"

Verify Audit Log Integrity

The audit log uses a hash chain for tamper detection:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/audit/verify"

Response:

{
  "valid": true,
  "entries_verified": 1547,
  "message": "Audit log integrity verified successfully"
}

Breach Notification

HIPAA requires notification within 60 days of discovering a breach affecting 500+ individuals.

See Breach Detection section.


FERPA Compliance

For educational institutions, Aegis-DB provides:

Access Control

Configure roles to restrict access to student records:

# Create a role for registrar staff
curl -X POST "http://localhost:9090/api/v1/admin/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "registrar",
    "permissions": ["read:students", "write:grades"]
  }'

Track consent for sharing student records:

curl -X POST "http://localhost:9090/api/v1/compliance/consent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "student-12345",
    "purpose": "third_party_sharing",
    "granted": true,
    "source": "paper_form",
    "version": "1.0",
    "metadata": {
      "recipient": "Graduate School XYZ",
      "purpose": "Admission application"
    }
  }'

SOC 2 Type II

Security Monitoring

See Breach Detection for security event monitoring.

Change Management

All configuration changes are logged:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/admin/activities?type=config"

Incident Response

See Breach Detection for incident tracking and response.


Breach Detection

Aegis-DB includes a real-time breach detection system that monitors for security threats.

Configuration

Set Detection Thresholds

The breach detector uses configurable thresholds:

Parameter Default Description
Failed login threshold 5 Failed logins before alert
Failed login window 300s Time window for counting
Unusual access threshold 100 Accesses per minute
Mass data threshold 1000 Rows for bulk operation alert

Webhook Setup

Configure a webhook to receive breach notifications:

export AEGIS_BREACH_WEBHOOK_URL=https://your-alerting-system.com/webhook
export AEGIS_BREACH_WEBHOOK_HEADER_Authorization="Bearer your-webhook-token"

Webhook payload format:

{
  "incident_id": "inc-000000000001",
  "detected_at": "2026-01-26T15:30:00Z",
  "type": "failed_login",
  "severity": "medium",
  "description": "Multiple failed login attempts detected",
  "affected_subjects": ["user@example.com"],
  "involved_ips": ["192.168.1.100"],
  "status": "open",
  "source": "aegis-db"
}

Security Event Types

Event Type Severity Description
failed_login Medium Multiple failed login attempts
unauthorized_access Medium Permission denied
unusual_access_pattern Medium High volume data access
admin_from_unknown_ip High Admin action from untrusted IP
mass_data_export High Large data export
mass_data_deletion Critical Large data deletion
session_hijacking High Session security violation
sql_injection High SQL injection attempt
brute_force_attack Critical Brute force detected
privilege_escalation Critical Privilege escalation attempt

List Breach Incidents

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/breaches"

Filter by Status

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/breaches?status=open"

Filter by Severity

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/breaches?severity=critical"

Incident Response

Acknowledge Incident

curl -X POST "http://localhost:9090/api/v1/compliance/breaches/inc-000000000001/acknowledge" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acknowledged_by": "security-team@company.com"
  }'

Resolve Incident

curl -X POST "http://localhost:9090/api/v1/compliance/breaches/inc-000000000001/resolve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_notes": "Investigated and blocked IP. User notified.",
    "false_positive": false
  }'

Mark as False Positive

curl -X POST "http://localhost:9090/api/v1/compliance/breaches/inc-000000000001/resolve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_notes": "Legitimate admin activity from new office location",
    "false_positive": true
  }'

Generate Incident Report

For compliance documentation:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/breaches/inc-000000000001/report"

Get Breach Statistics

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/breaches/stats"

Response:

{
  "total_incidents": 47,
  "open_incidents": 3,
  "acknowledged_incidents": 2,
  "resolved_incidents": 40,
  "false_positives": 2,
  "by_severity": {
    "low": 5,
    "medium": 30,
    "high": 10,
    "critical": 2
  },
  "by_type": {
    "failed_login": 25,
    "unauthorized_access": 15,
    "unusual_access_pattern": 5,
    "mass_data_export": 2
  }
}

List Security Events

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/security-events?limit=100"

Filter by Event Type

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/security-events?event_type=failed_login&limit=50"

Audit Trail

Hash Chain Verification

The audit log uses a cryptographic hash chain to detect tampering. Each entry contains:

  • Entry ID
  • Event type
  • Timestamp
  • Actor (who performed the action)
  • Details
  • Hash of previous entry
  • Hash of current entry

Verify Integrity

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/audit/verify"

If tampering is detected:

{
  "valid": false,
  "entries_verified": 0,
  "message": "Hash chain broken at entry 1523: expected prev_hash '...', got '...'"
}

Compliance Reports

Export Deletion Audit Trail

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/audit/user@example.com"
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com/history"

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/stats"

Response:

{
  "total_subjects": 15000,
  "total_records": 45000,
  "total_history_entries": 52000,
  "do_not_sell_count": 1200,
  "consents_by_purpose": {
    "marketing": [8000, 7000],
    "analytics": [12000, 3000],
    "third_party_sharing": [5000, 10000]
  }
}

The consents_by_purpose shows [granted_count, denied_count] for each purpose.

For GDPR data portability of consent records:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/v1/compliance/consent/user@example.com/export"

For GDPR right to erasure of consent records:

curl -X DELETE "http://localhost:9090/api/v1/compliance/consent/user@example.com" \
  -H "Authorization: Bearer $TOKEN"

API Reference

Compliance Endpoints Summary

Method Endpoint Description
DELETE /api/v1/compliance/data-subject/:id Delete all data for subject
POST /api/v1/compliance/export Export subject data
GET /api/v1/compliance/certificates List deletion certificates
GET /api/v1/compliance/certificates/:id Get specific certificate
GET /api/v1/compliance/certificates/:id/verify Verify certificate
GET /api/v1/compliance/audit/:subject_id Get audit trail for subject
GET /api/v1/compliance/audit/verify Verify audit log integrity
POST /api/v1/compliance/consent Record consent
GET /api/v1/compliance/consent/stats Get consent statistics
GET /api/v1/compliance/consent/:subject_id Get consent status
DELETE /api/v1/compliance/consent/:subject_id Delete consent data
GET /api/v1/compliance/consent/:subject_id/history Get consent history
GET /api/v1/compliance/consent/:subject_id/export Export consent data
GET /api/v1/compliance/consent/:subject_id/check/:purpose Check specific consent
DELETE /api/v1/compliance/consent/:subject_id/:purpose Withdraw consent
GET /api/v1/compliance/do-not-sell Get Do Not Sell list
GET /api/v1/compliance/breaches List breach incidents
GET /api/v1/compliance/breaches/stats Get breach statistics
POST /api/v1/compliance/breaches/cleanup Trigger cleanup of old events
GET /api/v1/compliance/breaches/:id Get specific incident
POST /api/v1/compliance/breaches/:id/acknowledge Acknowledge incident
POST /api/v1/compliance/breaches/:id/resolve Resolve incident
GET /api/v1/compliance/breaches/:id/report Generate incident report
GET /api/v1/compliance/security-events List security events

Best Practices

Data Retention

  1. Define retention policies - Set appropriate retention periods for each data type
  2. Automate deletion - Schedule automated deletion of expired data
  3. Document exceptions - Record legal hold requirements
  1. Clear language - Use plain language for consent requests
  2. Granular options - Allow users to consent to specific purposes
  3. Easy withdrawal - Make consent withdrawal as easy as granting
  4. Version tracking - Track which privacy policy version consent was given under

Incident Response

  1. Monitor continuously - Enable breach detection and alerting
  2. Respond quickly - Acknowledge incidents within SLA
  3. Document thoroughly - Keep detailed resolution notes
  4. Learn and improve - Review incidents to improve security

Audit Compliance

  1. Regular verification - Periodically verify audit log integrity
  2. Secure storage - Store audit logs in tamper-evident storage
  3. Retention - Keep audit logs for required retention periods (7 years for HIPAA)
  4. Access control - Restrict access to audit logs

Document Version: 1.0.0 Last Updated: January 2026 Maintainer: AutomataNexus Compliance Team