This document describes the security features and architecture of OpenSentinel v2.0.0. As a self-hosted application, OpenSentinel keeps all data on your infrastructure. The security module is implemented across multiple files in src/core/security/.

• Authentication
• Auth Monitoring and Anomaly Detection
• Two-Factor Authentication (2FA)
• Biometric Verification
• Elevated Mode
• Sandboxing
• Data Protection
• Rate Limiting
• Enterprise Security

OpenSentinel uses per-channel allowlists to restrict access. Each communication platform has its own authentication mechanism based on platform-specific identifiers.

Messages from users or channels not in the allowlist are silently ignored. When no allowlist is configured for a platform, access control behavior depends on the specific integration.

The API server supports token-based authentication managed by the API key manager (src/core/security/api-key-manager.ts). API keys can be created, revoked, and rotated programmatically or through the web dashboard.

Sessions are managed by src/core/security/session-manager.ts using JWT tokens. Sessions include:

• Token-based session creation and validation
• Session expiration and automatic cleanup
• Per-user session tracking
• Session revocation (individual or all sessions for a user)

The AuthMonitor class (src/core/security/auth-monitor.ts) provides real-time monitoring of authentication events and detects anomalous patterns.

• info: Informational events logged for awareness. No immediate action required.
• warning: Suspicious activity that warrants investigation. Notifications are sent to configured alert channels.
• critical: Potentially malicious activity. Immediate notification and possible automatic countermeasures (e.g., temporary lockout).

Register custom alert handlers to receive anomaly notifications:

import { authMonitor } from "./core/security/auth-monitor";

authMonitor.onAlert(async (userId, anomaly) => {
  console.log(`[${anomaly.level}] User ${userId}: ${anomaly.message}`);
  // Send notification via Telegram, Discord, email, etc.
});

The auth monitor maintains per-user tracking data in memory:

• Login history: Up to 200 recent login attempts per user
• Known devices: Set of device identifiers from successful logins
• Known IPs: Set of IP addresses from successful logins
• Login hours: Historical distribution of login times

OpenSentinel supports TOTP-based two-factor authentication (src/core/security/two-factor-auth.ts) for protecting sensitive operations.

1. Initialize: Call initializeTwoFactor(userId) to generate a TOTP secret, QR code URL (otpauth://), and 10 recovery codes.
2. Verify: User scans the QR code with an authenticator app (Google Authenticator, Authy, etc.) and provides a verification code.
3. Enable: Call completeTwoFactorSetup(userId, secret, code) to activate 2FA after verifying the initial code.

• 10 recovery codes generated during setup
• Format: XXXX-XXXX (8 hex characters)
• Stored as HMAC-SHA256 hashes (not plaintext)
• Each code is single-use and removed after consumption
• Codes can be regenerated (requires current 2FA verification)

The following sensitive operations require 2FA verification when enabled:

2FA can only be disabled by providing a valid TOTP code or unused recovery code. This prevents unauthorized disabling of the security feature.

OpenSentinel supports biometric verification (src/core/security/biometric-handler.ts) via webhook-based communication with registered biometric devices.

• Fingerprint
• Face ID
• Voice
• Iris

Biometric devices must be registered and explicitly trusted before use:

1. Register: Provide device name, supported biometric types, webhook URL, and public key.
2. Trust: After initial verification, mark the device as trusted.
3. Use: Only trusted devices can respond to biometric challenges.

Registered devices are stored in Redis with a 1-year TTL and loaded into memory on startup.

1. OpenSentinel creates a biometric challenge with a unique ID, operation context, and 2-minute expiration.
2. The challenge is sent to the registered device via its webhook URL, signed with HMAC-SHA256.
3. The device performs biometric verification and sends back a signed response with a confidence score.
4. OpenSentinel verifies the webhook signature and requires a minimum 85% confidence score.
5. The challenge is resolved and the pending operation proceeds (or is rejected).

• Challenge expiration: 2 minutes
• Webhook timeout: 90 seconds
• Minimum confidence threshold: 85%
• Signature verification on all webhook communications
• Devices can have trust revoked at any time

Elevated mode provides time-limited enhanced privileges for administrative operations.

When elevated mode is active, the user can perform sensitive operations without re-verifying for each action. After the 30-minute window expires, elevated privileges are automatically revoked and subsequent sensitive operations require fresh verification.

OpenSentinel implements multiple layers of sandboxing to contain potentially dangerous operations.

• Allowlist/Blocklist: Configurable lists of permitted and prohibited shell commands.
• File path restrictions: Commands are restricted to approved directory paths.
• Output size limits: Shell command output is truncated to prevent memory exhaustion.

Plugins run in a sandboxed environment (src/core/plugins/plugin-sandbox.ts) with the following controls:

Each plugin declares required permissions in its manifest. The sandbox enforces these permissions at runtime:

Operations attempted without the required permission throw an error with a descriptive message.

Plugin HTTP requests are validated against:

• Domain allowlists (when configured, only specified domains are permitted)
• Domain blocklists (internal services, cloud metadata endpoints)
• Private/internal IP range blocking
• Per-plugin rate limiting

The memory vault (src/core/security/memory-vault.ts) provides encrypted storage for sensitive data such as API keys, tokens, and personal information. Vault entries are encrypted at rest and require authentication to access.

OpenSentinel is fully self-hosted. All data is stored locally on your infrastructure:

• Conversations and memories: PostgreSQL database
• Session data and cache: Redis
• Generated files: Local filesystem (/app/data)
• Logs: Local filesystem (/app/logs)

No data is sent to external services except for API calls to configured integrations (Claude API, Telegram, Discord, etc.).

The GDPR compliance module (src/core/security/gdpr-compliance.ts) provides:

• Data export: Export all user data in a portable format
• Data deletion: Complete deletion of all user data (right to erasure)
• Data retention: Configurable retention policies (src/core/security/data-retention.ts) for automatic cleanup of old data

All security-relevant actions are logged by the audit logger (src/core/security/audit-logger.ts):

• Authentication attempts (success and failure)
• 2FA setup, verification, and disabling
• Biometric device registration and verification
• Sensitive operation execution
• Settings changes
• API key creation and revocation
• Data export and deletion requests

Audit logs include timestamps, user IDs, action types, resource identifiers, and operation-specific details.

The rate limiter (src/core/security/rate-limiter.ts) provides:

• Per-user request limits: Configurable maximum requests per time window
• API rate limiting: Protects the HTTP API from abuse
• Plugin rate limiting: Each plugin is limited to 100 requests per minute (configurable per sandbox)

Rate-limited requests receive appropriate error responses with retry-after information.

The enterprise module (src/core/enterprise/) provides additional security features for organizational deployments.

Support for enterprise identity providers:

• SAML 2.0: Integration with SAML identity providers
• OAuth 2.0: Standard OAuth flows
• OpenID Connect (OIDC): OIDC-compliant authentication

• Define roles with specific permission sets
• Assign roles to users
• Enforce permission checks at the API and tool level

• Per-user API call quotas
• Per-organization resource limits
• Configurable quota periods and thresholds
• Quota usage tracking and reporting

1. Always set allowlists: Configure *_ALLOWED_USER_IDS or *_ALLOWED_NUMBERS for every enabled communication platform.
2. Enable 2FA: Set up TOTP two-factor authentication for sensitive operations.
3. Use strong database passwords: Set DB_PASSWORD to a strong, unique password in your .env file.
4. Enable SSL in production: Use the nginx production profile with valid SSL certificates.
5. Restrict network access: Use firewall rules to limit access to PostgreSQL (5445) and Redis (6379) ports.
6. Review audit logs: Regularly review audit logs for anomalous activity.
7. Keep backups: Follow the backup strategy in the Deployment Guide for data recovery.
8. Update regularly: Keep OpenSentinel and its dependencies up to date for security patches.