Compliance Guide
Comprehensive guidance for deploying Aegis-DB in regulated environments
Table of Contents
- Overview
- Supported Frameworks
- Quick Start
- GDPR Compliance
- CCPA Compliance
- HIPAA Compliance
- FERPA Compliance
- SOC 2 Type II
- Breach Detection
- Audit Trail
- Consent Management
- API Reference
- Best Practices
- Overview
- Supported Frameworks
- Quick Start
- GDPR Compliance
- CCPA Compliance
- HIPAA Compliance
- FERPA Compliance
- SOC 2 Type II
- Breach Detection
- Audit Trail
- Consent Management
- 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.
Record Consent
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"
}
}'
Supported Consent Purposes
| 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 |
Get Consent Status
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:9090/api/v1/compliance/consent/user@example.com"
Check Specific Consent
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:9090/api/v1/compliance/consent/user@example.com/check/marketing"
Withdraw Consent
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"
}'
Get Consent History (Audit Trail)
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"]
}'
Consent for Disclosures
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"
Export Consent Audit Trail
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:9090/api/v1/compliance/consent/user@example.com/history"
Consent Management
Consent Statistics
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.
Export Consent Data
For GDPR data portability of consent records:
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:9090/api/v1/compliance/consent/user@example.com/export"
Delete Consent Data
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
- Define retention policies - Set appropriate retention periods for each data type
- Automate deletion - Schedule automated deletion of expired data
- Document exceptions - Record legal hold requirements
Consent Collection
- Clear language - Use plain language for consent requests
- Granular options - Allow users to consent to specific purposes
- Easy withdrawal - Make consent withdrawal as easy as granting
- Version tracking - Track which privacy policy version consent was given under
Incident Response
- Monitor continuously - Enable breach detection and alerting
- Respond quickly - Acknowledge incidents within SLA
- Document thoroughly - Keep detailed resolution notes
- Learn and improve - Review incidents to improve security
Audit Compliance
- Regular verification - Periodically verify audit log integrity
- Secure storage - Store audit logs in tamper-evident storage
- Retention - Keep audit logs for required retention periods (7 years for HIPAA)
- Access control - Restrict access to audit logs
Document Version: 1.0.0 Last Updated: January 2026 Maintainer: AutomataNexus Compliance Team