Security Guide
Security features, best practices, and configuration for production deployments
Table of Contents
- Overview
- TLS/HTTPS Configuration
- Authentication
- Password Security
- Rate Limiting
- Secrets Management
- Nginx Reverse Proxy
- Security Headers
- Audit Logging
- Data Encryption
- Breach Detection and Response
- Regulatory Compliance
- Best Practices
- Reporting Security Issues
- Overview
- TLS/HTTPS Configuration
- Authentication
- Password Security
- Rate Limiting
- Secrets Management
- Nginx Reverse Proxy
- Security Headers
- Audit Logging
- Data Encryption
- Breach Detection and Response
- Regulatory Compliance
- Best Practices
Overview
AegisDB v0.1.8+ includes production-ready security features:
| Feature | Implementation | Status |
|---|---|---|
| TLS/HTTPS | axum-server with rustls | ✅ Production Ready |
| Password Hashing | Argon2id | ✅ Production Ready |
| Rate Limiting | Token Bucket Algorithm | ✅ Production Ready |
| Secrets Management | HashiCorp Vault | ✅ Production Ready |
| Authentication | Local, LDAP, OAuth2 | ✅ Production Ready |
| MFA/2FA | TOTP (RFC 6238) | ✅ Production Ready |
| RBAC | 25+ Permissions | ✅ Production Ready |
| Audit Logging | Comprehensive Activity Log | ✅ Production Ready |
TLS/HTTPS Configuration
Native TLS Support
AegisDB supports native TLS via rustls:
# Start server with TLS
cargo run -p aegis-server -- \
--tls \
--tls-cert /path/to/server.crt \
--tls-key /path/to/server.key
Environment Variables
export AEGIS_TLS_CERT=/path/to/server.crt
export AEGIS_TLS_KEY=/path/to/server.key
cargo run -p aegis-server -- --tls
Generate Self-Signed Certificates (Development)
# Create certificates directory
mkdir -p certs
# Generate self-signed certificate
openssl req -x509 -newkey rsa:4096 \
-keyout certs/server.key \
-out certs/server.crt \
-days 365 -nodes \
-subj "/CN=localhost/O=Aegis-DB/C=US"
# Add Subject Alternative Names for local testing
openssl req -x509 -newkey rsa:4096 \
-keyout certs/server.key \
-out certs/server.crt \
-days 365 -nodes \
-subj "/CN=localhost/O=Aegis-DB/C=US" \
-addext "subjectAltName=DNS:localhost,DNS:aegis.local,IP:127.0.0.1"
Production Certificates
For production, use certificates from a trusted CA:
# Let's Encrypt (via certbot)
sudo certbot certonly --standalone -d aegis.example.com
# Use the generated certificates
cargo run -p aegis-server -- \
--tls \
--tls-cert /etc/letsencrypt/live/aegis.example.com/fullchain.pem \
--tls-key /etc/letsencrypt/live/aegis.example.com/privkey.pem
TLS Configuration
The server uses secure defaults:
- Protocols: TLSv1.2, TLSv1.3
- Cipher Suites: Modern ECDHE-based ciphers
- Session Tickets: Disabled for forward secrecy
Authentication
Supported Methods
| Method | Description | Configuration |
|---|---|---|
| Local | Username/password stored in AegisDB | Default |
| LDAP | Active Directory / OpenLDAP | auth.method = "ldap" |
| OAuth2/OIDC | Okta, Auth0, Azure AD, etc. | auth.method = "oauth2" |
Local Authentication
Users are authenticated against locally stored credentials. Configure credentials via environment variables:
# Set credentials before starting the server
export AEGIS_ADMIN_USERNAME=your_admin_username
export AEGIS_ADMIN_PASSWORD=your_secure_password
# Login
curl -X POST https://localhost:9090/api/v1/auth/login \
-H "Content-Type: application/json" \
-d "{\"username\": \"$AEGIS_ADMIN_USERNAME\", \"password\": \"$AEGIS_ADMIN_PASSWORD\"}"
# Response
{
"token": "abc123...",
"user": {
"username": "your_username",
"role": "admin",
"mfa_enabled": false
}
}
MFA/2FA (TOTP)
Multi-factor authentication using TOTP (RFC 6238):
# Enable MFA for a user (returns secret)
POST /api/v1/auth/mfa/enable
# Verify MFA code after login
POST /api/v1/auth/mfa/verify
{
"token": "temporary-token",
"code": "123456"
}
Password Security
Argon2id Hashing
Passwords are hashed using Argon2id, the winner of the Password Hashing Competition:
| Parameter | Value | Purpose |
|---|---|---|
| Memory Cost | 19 MiB | Resist GPU attacks |
| Time Cost | 2 iterations | Increase computation time |
| Parallelism | 1 | Single-threaded |
| Output Length | 32 bytes | 256-bit hash |
| Salt | Random 16 bytes | Unique per password |
Implementation
use argon2::{Argon2, Algorithm, Version, Params, PasswordHasher};
const ARGON2_MEMORY_COST: u32 = 19_456; // 19 MiB
const ARGON2_TIME_COST: u32 = 2;
const ARGON2_PARALLELISM: u32 = 1;
pub fn hash_password(password: &str) -> Result<String, String> {
let salt = SaltString::generate(&mut OsRng);
let argon2 = Argon2::new(
Algorithm::Argon2id,
Version::V0x13,
Params::new(ARGON2_MEMORY_COST, ARGON2_TIME_COST, ARGON2_PARALLELISM, None)
.expect("Invalid Argon2 params")
);
argon2
.hash_password(password.as_bytes(), &salt)
.map(|hash| hash.to_string())
.map_err(|e| e.to_string())
}
Rate Limiting
Token Bucket Algorithm
AegisDB implements token bucket rate limiting to prevent brute force attacks:
| Endpoint Category | Limit | Window |
|---|---|---|
| Login endpoints | 30 requests | per minute per IP |
| General API | 1000 requests | per minute per IP |
Response Headers
Rate limit information is included in response headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706288400
Rate Limited Response
When rate limited, the API returns:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
"error": "Rate limit exceeded. Try again in 60 seconds."
}
Configuration
[rate_limit]
requests_per_minute = 1000
login_requests_per_minute = 30
Secrets Management
HashiCorp Vault Integration
AegisDB integrates with HashiCorp Vault for enterprise secrets management.
Environment Variables
# Vault server address
export VAULT_ADDR=https://vault.example.com:8200
# Authentication methods (choose one):
# 1. Token-based (simplest)
export VAULT_TOKEN=hvs.your-vault-token
# 2. AppRole (recommended for production)
export VAULT_ROLE_ID=your-role-id
export VAULT_SECRET_ID=your-secret-id
# 3. Kubernetes (for K8s deployments)
export VAULT_KUBERNETES_ROLE=aegis-db
Vault Secret Paths
| Secret | Vault Path | Environment Fallback |
|---|---|---|
| TLS Certificate Path | secret/data/aegis/tls_cert_path | AEGIS_TLS_CERT |
| TLS Key Path | secret/data/aegis/tls_key_path | AEGIS_TLS_KEY |
| Database Password | secret/data/aegis/db_password | AEGIS_DB_PASSWORD |
Vault Policy
# aegis-db-policy.hcl
path "secret/data/aegis/*" {
capabilities = ["read"]
}
path "secret/metadata/aegis/*" {
capabilities = ["list"]
}
Provider Priority
Secrets are resolved in order:
- HashiCorp Vault (if configured and available)
- Environment variables
- Default values (where applicable)
Nginx Reverse Proxy
Recommended Configuration
For production deployments, use Nginx as a reverse proxy:
# /etc/nginx/sites-available/aegis-db
upstream aegis_backend {
server 127.0.0.1:9090;
keepalive 32;
}
server {
listen 443 ssl http2;
server_name aegis.example.com;
# SSL Configuration
ssl_certificate /etc/letsencrypt/live/aegis.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/aegis.example.com/privkey.pem;
# Modern SSL settings
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:50m;
# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# API proxy
location /api {
proxy_pass http://aegis_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Health check
location = /health {
proxy_pass http://aegis_backend/health;
}
# Dashboard static files
location / {
root /opt/Aegis-DB/crates/aegis-dashboard/dist;
index index.html;
try_files $uri $uri/ /index.html;
}
}
# HTTP to HTTPS redirect
server {
listen 80;
server_name aegis.example.com;
return 301 https://$server_name$request_uri;
}
Security Headers
AegisDB (via Nginx) adds the following security headers:
| Header | Value | Purpose |
|---|---|---|
X-Frame-Options | SAMEORIGIN | Prevent clickjacking |
X-Content-Type-Options | nosniff | Prevent MIME sniffing |
X-XSS-Protection | 1; mode=block | XSS filter |
Strict-Transport-Security | max-age=31536000 | Force HTTPS |
Referrer-Policy | strict-origin-when-cross-origin | Control referrer |
Audit Logging
Activity Log
All security-relevant actions are logged:
{
"timestamp": "2026-01-26T15:30:00Z",
"event_type": "login",
"user": "admin",
"ip_address": "192.168.1.100",
"success": true,
"details": {
"method": "local",
"mfa_used": true
}
}
Logged Events
| Event | Description |
|---|---|
login | User authentication attempt |
logout | User session termination |
mfa_enable | MFA enabled for user |
mfa_verify | MFA code verification |
password_change | Password modification |
user_create | New user created |
user_delete | User deleted |
role_change | User role modified |
query | Database query executed |
config_change | Configuration modified |
Log Locations
| Log | Location |
|---|---|
| Activity Log | /var/log/aegis/activity.log |
| Server Log | /var/log/aegis/server.log |
| Audit Log | /var/log/aegis/audit.log |
Data Encryption
AegisDB provides comprehensive encryption for data protection at rest and in transit.
Data at Rest Encryption
Enable encryption for stored data using AES-256-GCM:
# Set encryption key (must be 32 bytes / 256 bits, base64 encoded)
export AEGIS_ENCRYPTION_KEY=your-base64-encoded-32-byte-key
# Generate a secure encryption key
openssl rand -base64 32
| Feature | Algorithm | Key Size |
|---|---|---|
| Data at Rest | AES-256-GCM | 256-bit |
| Key Derivation | HKDF-SHA256 | 256-bit |
| IV/Nonce | Random | 96-bit |
Configuration
[encryption]
enabled = true
algorithm = "aes-256-gcm"
key_rotation_days = 90
Encrypted Backups
All backups are encrypted by default when AEGIS_ENCRYPTION_KEY is configured:
# Create encrypted backup
curl -X POST https://localhost:9090/api/v1/admin/backup \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"encrypted": true}'
# Backup metadata includes encryption info
{
"backup_id": "backup-2026-01-26-153000",
"encrypted": true,
"encryption_algorithm": "aes-256-gcm",
"created_at": "2026-01-26T15:30:00Z",
"size_bytes": 104857600
}
Key Management
| Practice | Recommendation |
|---|---|
| Key Storage | Use HashiCorp Vault or AWS KMS |
| Key Rotation | Rotate every 90 days |
| Key Backup | Store in separate secure location |
| Access Control | Limit key access to authorized personnel |
TLS for Data in Transit
All client-server communication should use TLS 1.2 or higher:
# Verify TLS configuration
openssl s_client -connect localhost:9090 -tls1_3
# Check supported cipher suites
nmap --script ssl-enum-ciphers -p 9090 localhost
See TLS/HTTPS Configuration for detailed setup instructions.
Breach Detection and Response
AegisDB includes built-in breach detection and automated notification capabilities.
How Breach Detection Works
The breach detection system monitors for:
| Indicator | Detection Method | Severity |
|---|---|---|
| Multiple failed logins | Threshold-based (>10 in 5 min) | High |
| Unusual access patterns | Anomaly detection | Medium |
| Privilege escalation attempts | Rule-based | Critical |
| Data exfiltration signals | Volume/rate monitoring | Critical |
| SQL injection attempts | Pattern matching | High |
| Unauthorized API access | Token validation failures | Medium |
Detection Configuration
[breach_detection]
enabled = true
failed_login_threshold = 10
failed_login_window_minutes = 5
anomaly_detection = true
data_exfiltration_threshold_mb = 100
Configuring Webhook Notifications
Configure automated alerts when potential breaches are detected:
# Set webhook URL for breach notifications
export AEGIS_BREACH_WEBHOOK_URL=https://your-incident-management.example.com/webhook
# Optional: Set webhook authentication
export AEGIS_BREACH_WEBHOOK_SECRET=your-webhook-secret
Webhook Payload Format
When a breach is detected, AegisDB sends a POST request:
{
"event_type": "security_breach",
"severity": "critical",
"timestamp": "2026-01-26T15:30:00Z",
"breach_type": "multiple_failed_logins",
"details": {
"ip_address": "192.168.1.100",
"username": "admin",
"failed_attempts": 15,
"time_window_minutes": 5
},
"recommended_action": "Block IP address and investigate",
"instance_id": "aegis-prod-01"
}
Integration Examples
Slack Integration:
export AEGIS_BREACH_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX
PagerDuty Integration:
export AEGIS_BREACH_WEBHOOK_URL=https://events.pagerduty.com/v2/enqueue
export AEGIS_BREACH_WEBHOOK_SECRET=your-pagerduty-routing-key
Incident Response Procedures
When a breach is detected:
- Immediate Actions (0-15 minutes)
- Automated webhook notification sent
- Suspicious IP addresses temporarily blocked
- Affected user sessions invalidated
- Audit logs preserved
- Investigation Phase (15-60 minutes)
- Review audit logs at
/var/log/aegis/audit.log - Identify scope of potential breach
- Determine affected data and users
- Document timeline of events
- Review audit logs at
- Containment (1-4 hours)
- Isolate affected systems if necessary
- Revoke compromised credentials
- Apply emergency patches if vulnerability exploited
- Enable enhanced monitoring
- Recovery (4-24 hours)
- Restore from encrypted backups if needed
- Reset affected user passwords
- Re-enable services with additional monitoring
- Communicate with stakeholders
- Post-Incident (24-72 hours)
- Complete incident report
- Identify root cause
- Implement preventive measures
- Update security policies
- Notify regulatory bodies if required (see Regulatory Compliance)
Incident Response API
# Get active security alerts
GET /api/v1/admin/security/alerts
# Acknowledge an alert
POST /api/v1/admin/security/alerts/{alert_id}/acknowledge
# Block an IP address
POST /api/v1/admin/security/block-ip
{
"ip_address": "192.168.1.100",
"reason": "Multiple failed login attempts",
"duration_hours": 24
}
# Get blocked IPs
GET /api/v1/admin/security/blocked-ips
Regulatory Compliance
AegisDB includes features to help organizations meet regulatory compliance requirements.
HIPAA Compliance
For organizations handling Protected Health Information (PHI):
| Requirement | AegisDB Feature | Configuration |
|---|---|---|
| Access Controls | RBAC with 25+ permissions | [rbac] section |
| Audit Controls | Comprehensive audit logging | [audit] section |
| Transmission Security | TLS 1.2/1.3 encryption | --tls flag |
| Encryption | AES-256-GCM at rest | AEGIS_ENCRYPTION_KEY |
| Integrity Controls | Checksums and WAL | Built-in |
| Automatic Logoff | Session timeout | session_timeout_minutes |
Encrypted Backups for HIPAA:
# Configure HIPAA-compliant backups
export AEGIS_ENCRYPTION_KEY=your-256-bit-key
export AEGIS_BACKUP_ENCRYPTION=required
# Backup with PHI must be encrypted
curl -X POST https://localhost:9090/api/v1/admin/backup \
-H "Authorization: Bearer $TOKEN" \
-d '{"encrypted": true, "compliance_mode": "hipaa"}'
Audit Log Requirements:
All access to PHI is logged with:
- User identity
- Date and time of access
- Type of action performed
- Data accessed
- Source IP address
Breach Notification:
Configure automated breach notification (required within 60 days for HIPAA):
export AEGIS_BREACH_WEBHOOK_URL=https://your-compliance-system.example.com/hipaa-breach
export AEGIS_BREACH_NOTIFICATION_REQUIRED=true
GDPR Compliance
For organizations handling EU personal data:
| GDPR Right | AegisDB Feature | API Endpoint |
|---|---|---|
| Right to Erasure | Data deletion API | DELETE /api/v1/gdpr/erasure |
| Right to Portability | Data export (JSON/CSV) | GET /api/v1/gdpr/export |
| Right to Access | Data retrieval API | GET /api/v1/gdpr/access |
| Consent Management | Consent tracking | POST /api/v1/gdpr/consent |
| Data Minimization | Retention policies | [retention] config |
Right to Erasure (Article 17):
# Request data erasure for a user
curl -X DELETE https://localhost:9090/api/v1/gdpr/erasure \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"subject_id": "user-12345",
"reason": "user_request",
"verification_token": "verification-abc123"
}'
# Response
{
"erasure_id": "erasure-2026-01-26-001",
"status": "completed",
"records_deleted": 1547,
"completed_at": "2026-01-26T15:35:00Z",
"audit_reference": "audit-gdpr-12345"
}
Data Portability (Article 20):
# Export user data in portable format
curl -X GET "https://localhost:9090/api/v1/gdpr/export?subject_id=user-12345&format=json" \
-H "Authorization: Bearer $TOKEN" \
-o user-data-export.json
# Supported formats: json, csv, xml
Consent Management:
# Record consent
curl -X POST https://localhost:9090/api/v1/gdpr/consent \
-H "Authorization: Bearer $TOKEN" \
-d '{
"subject_id": "user-12345",
"purpose": "marketing",
"granted": true,
"timestamp": "2026-01-26T15:30:00Z"
}'
# Query consent status
curl -X GET "https://localhost:9090/api/v1/gdpr/consent?subject_id=user-12345" \
-H "Authorization: Bearer $TOKEN"
Data Retention Configuration:
[retention]
enabled = true
default_retention_days = 365
pii_retention_days = 90
audit_log_retention_days = 2555 # 7 years for compliance
auto_delete_expired = true
CCPA Compliance
For organizations handling California consumer data:
| CCPA Right | AegisDB Feature | Implementation |
|---|---|---|
| Right to Know | Data access API | GET /api/v1/ccpa/access |
| Right to Delete | Data deletion API | DELETE /api/v1/ccpa/delete |
| Right to Opt-Out | Do Not Sell flag | POST /api/v1/ccpa/opt-out |
| Non-Discrimination | Access logging | Audit trail |
Do Not Sell Implementation:
# Set Do Not Sell flag for a consumer
curl -X POST https://localhost:9090/api/v1/ccpa/opt-out \
-H "Authorization: Bearer $TOKEN" \
-d '{
"consumer_id": "consumer-12345",
"opt_out_type": "do_not_sell",
"effective_date": "2026-01-26"
}'
# Response
{
"opt_out_id": "optout-2026-01-26-001",
"consumer_id": "consumer-12345",
"status": "active",
"effective_date": "2026-01-26",
"confirmation_number": "CCPA-DNX-12345"
}
Data Deletion Request:
# Process CCPA deletion request
curl -X DELETE https://localhost:9090/api/v1/ccpa/delete \
-H "Authorization: Bearer $TOKEN" \
-d '{
"consumer_id": "consumer-12345",
"request_type": "consumer_request",
"verification_method": "email_verified"
}'
# Response includes service provider notification list
{
"deletion_id": "del-2026-01-26-001",
"status": "processing",
"estimated_completion": "2026-02-10T00:00:00Z",
"service_providers_notified": [
"analytics-provider",
"backup-service"
]
}
SOC 2 Controls
AegisDB implements controls aligned with SOC 2 Trust Service Criteria:
| Category | Control | AegisDB Implementation |
|---|---|---|
| Security | CC6.1 Logical Access | RBAC, MFA, session management |
| Security | CC6.2 System Boundaries | Network isolation, TLS |
| Security | CC6.3 Access Removal | User deprovisioning API |
| Security | CC6.6 Security Events | Audit logging, breach detection |
| Security | CC6.7 Transmission Security | TLS 1.2/1.3 required |
| Availability | A1.1 Capacity Planning | Metrics and monitoring |
| Availability | A1.2 Recovery | Encrypted backups, replication |
| Confidentiality | C1.1 Data Classification | Field-level encryption |
| Confidentiality | C1.2 Data Disposal | Secure deletion API |
| Processing Integrity | PI1.1 Data Validation | Input validation, checksums |
SOC 2 Audit Evidence Collection:
# Generate SOC 2 compliance report
curl -X GET https://localhost:9090/api/v1/admin/compliance/soc2-report \
-H "Authorization: Bearer $TOKEN" \
-o soc2-evidence.json
# Report includes:
# - Access control logs
# - Configuration change history
# - Security event summary
# - Encryption status
# - Backup verification logs
Continuous Compliance Monitoring:
[compliance]
soc2_monitoring = true
alert_on_control_failure = true
evidence_retention_days = 365
automated_evidence_collection = true
Compliance Dashboard
Access compliance status via the admin dashboard:
# Get compliance status summary
GET /api/v1/admin/compliance/status
# Response
{
"hipaa": {
"status": "compliant",
"last_audit": "2026-01-15",
"controls_met": 18,
"controls_total": 18
},
"gdpr": {
"status": "compliant",
"last_audit": "2026-01-15",
"pending_erasure_requests": 0,
"pending_access_requests": 2
},
"ccpa": {
"status": "compliant",
"do_not_sell_count": 1547,
"pending_deletion_requests": 1
},
"soc2": {
"status": "monitoring",
"controls_implemented": 45,
"controls_total": 50
}
}
Best Practices
Production Deployment Checklist
- Enable TLS - Never run without encryption in production
- Use strong certificates - Obtain from trusted CA (Let’s Encrypt)
- Configure Vault - Use HashiCorp Vault for secrets
- Configure secure credentials - Set
AEGIS_ADMIN_USERNAMEandAEGIS_ADMIN_PASSWORDenvironment variables - Enable MFA - Require 2FA for admin accounts
- Use Nginx - Deploy behind reverse proxy
- Configure rate limiting - Protect against brute force
- Enable audit logging - Track all security events
- Regular updates - Keep AegisDB and dependencies updated
- Network segmentation - Isolate database from public internet
Password Requirements
For user accounts, enforce:
- Minimum 12 characters
- Mix of uppercase, lowercase, numbers, symbols
- No common passwords
- No username in password
Session Security
- Session tokens are cryptographically random (256 bits)
- Tokens expire after configurable timeout (default: 30 minutes)
- Tokens are invalidated on logout
- Concurrent session limits can be configured
Network Security
- Bind to
127.0.0.1by default (localhost only) - Use firewall rules to restrict access
- Deploy behind VPN for internal-only access
- Use private subnets in cloud deployments
Reporting Security Issues
If you discover a security vulnerability in AegisDB, please report it responsibly:
- Do not open a public GitHub issue
- Email security concerns to: security@automatanexus.com
- Include detailed steps to reproduce
- Allow 90 days for patch before public disclosure
Document Version: 1.0.0 Last Updated: January 2026 Maintainer: AutomataNexus Security Team