Security Best Practices

Guidelines for secure integration with Raven Protocol.

Overview

Raven is designed with security as a core principle. However, proper integration is essential to maintain the security guarantees. This guide covers best practices for secure integration.

API Key Security

Do

- Store API keys in environment variables or secrets managers
- Use different API keys for development, staging, and production
- Create keys with minimal required scopes
- Rotate keys periodically (every 90 days recommended)
- Revoke keys immediately if compromised
- Monitor API key usage for anomalies

Don't

- Never commit API keys to version control
- Never expose API keys in client-side code
- Never share API keys in public channels
- Never log API keys in application logs
- Never use production keys in development

Scope Recommendations

Create different keys for different use cases:

Use Case	Recommended Scopes
Agent Runtime	`memory:read memory:write conversations:read conversations:write`
Analytics/Monitoring	`memory:read users:read conversations:read tenant:read`
User Management	`users:read users:write`
Admin Dashboard	`All scopes (use sparingly)`

Network Security

Use HTTPS

Always use HTTPS for API connections. Never send API keys over unencrypted connections.

IP Allowlisting

If self-hosting, restrict API access to known IP ranges.

Rate Limiting

Implement client-side rate limiting to avoid hitting server limits and protect against abuse.

Timeouts

Set appropriate request timeouts (30s recommended) to prevent hanging connections.

Data Privacy

User Identification

Use pseudonymous identifiers for users to minimize PII exposure:

// Good: Use opaque identifiers
external_ref: "usr_7f3k2j1"

// Bad: Don't use PII directly
external_ref: "john.doe@email.com"
external_ref: "+1-555-123-4567"

Sensitive Content

Important

While memory is encrypted at rest, avoid storing highly sensitive data like passwords, financial details, or health information. Implement content filtering in your agent before ingestion.

Data Retention

→Set appropriate retention_days for your compliance requirements

→Implement user data deletion workflows for GDPR/CCPA compliance

→Document what data is stored and for how long

→Provide users visibility into their stored data

Encryption Configuration

Production Recommendations

Recommended Production Config

# Use external KMS for production
ENCRYPTION_KEY_STORAGE=kms
KMS_PROVIDER=aws  # or gcp, azure, vault
KMS_KEY_ID=arn:aws:kms:region:account:key/id

# Enable strict encryption mode
ENCRYPTION_ENABLED=true

# Audit logging for key access
KMS_AUDIT_LOG=true

Key Rotation

Implement regular key rotation:

Generate new encryption key version

Configure new key as active for new encryptions

Keep old key available for decryption

Optionally re-encrypt old blobs with new key

Retire old key after migration period

Self-Hosting Security

If self-hosting Raven, additional considerations:

Firewall Configuration

Only expose necessary ports. Redis should never be publicly accessible.

Monitoring

Set up logging, metrics, and alerting for security events.

Updates

Keep all dependencies updated. Subscribe to security advisories.

Backups

Implement encrypted backups with tested restoration procedures.

Auditing

Enable audit logs for all administrative actions.

Security Checklist

Pre-Production Checklist

Security Reporting

If you discover a security vulnerability in Raven Protocol, please report it responsibly. Email security@raven.protocol with details. Do not disclose vulnerabilities publicly until they have been addressed.