Security Overview

Security Overview

Mantis implements defense-in-depth security with multiple layers of protection.

Security Architecture

Security Layers

Layer	Protection	Components
Network	TLS 1.3, firewall rules	Load balancer, WAF
Transport	mTLS, certificate pinning	Thorax ↔ Tarsus
Authentication	JWT, OIDC/SSO	Mandible, Identity Providers
Authorization	RBAC, tenant isolation	All components
Data	Encryption at rest	PostgreSQL, credentials

Authentication Methods

User Authentication

Method	Use Case	Configuration
Local	Built-in accounts	POST /api/v1/admin/users (or Lens)
OIDC	Enterprise SSO	Identity provider config
API Keys	Service accounts	POST /api/v1/auth/api-keys (or Lens)

Agent Authentication

Mode	Security Level	Complexity
Thumbprint	High	Low
CA-Signed	Highest	Medium

Security Components

TLS Certificates

All communication is encrypted:

Connection	Protocol	Certificate
Client → Mandible	HTTPS	Server cert
Mandible → Thorax	gRPC + TLS	Server cert
Thorax ↔ Tarsus	mTLS	Client + Server certs

See TLS Certificates for configuration.

mTLS Authentication

Mutual TLS ensures both parties are authenticated:

See mTLS Authentication for details.

JWT Configuration

JSON Web Tokens secure API access:

Algorithm	Use Case	Key Management
HS256	Simple deployments	Shared secret
RS256	Enterprise	Public/private keys

See JWT Configuration for setup.

Encryption at Rest

Sensitive data is encrypted in the database:

Data Type	Encryption	Key Source
Credentials	AES-256-GCM	Master key
API keys	Argon2 hash	N/A
Secrets	AES-256-GCM	Master key

See Encryption at Rest for configuration.

Authentication Modes

Thumbprint Mode (Default)

Self-signed certificates with thumbprint verification:

┌─────────────────────────────────────────────────────────────┐
│  Thumbprint Mode Flow                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Tarsus generates self-signed certificate               │
│  2. Certificate thumbprint (SHA-256) extracted             │
│  3. Thumbprint registered in Mantis                        │
│  4. On connect: TLS validates cert, app verifies thumbprint│
│                                                             │
│  Pros: No CA infrastructure required                        │
│  Cons: Manual thumbprint management                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

See Thumbprint Mode for configuration.

CA-Signed Mode

Traditional PKI with certificate authority:

┌─────────────────────────────────────────────────────────────┐
│  CA-Signed Mode Flow                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Mantis CA issues client certificates                   │
│  2. Tarsus CSR submitted and signed                        │
│  3. TLS layer validates CA signature                       │
│  4. App layer verifies thumbprint (defense-in-depth)       │
│                                                             │
│  Pros: Centralized certificate management                   │
│  Cons: CA infrastructure required                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

See CA-Signed Mode for configuration.

Access Control

RBAC Overview

Role-Based Access Control governs all operations:

Role	Scope	Typical Permissions
Admin	Global	All operations
Operator	Tenant	Deploy, manage targets
Viewer	Tenant	Read-only access

See RBAC Overview for details.

Tenant Isolation

Multi-tenant data isolation:

Isolation Level	Enforcement
Database	Application-layer tenant filtering
API	JWT tenant claims
Audit	Separate audit chains

Key Management

Rotation Schedule

Key Type	Recommended Rotation	Emergency Rotation
JWT signing key	90 days	Immediately on compromise
Encryption master key	365 days	Immediately on compromise
TLS certificates	365 days	On expiry or compromise
Agent certificates	365 days	On compromise

See Key Rotation for procedures.

Security Checklist

Pre-Production

• TLS certificates configured
• mTLS enabled for agents
• JWT secret/keys configured
• Encryption at rest enabled
• RBAC roles defined
• Admin password changed
• Network segmentation applied

Ongoing

• Certificate expiry monitoring
• Key rotation schedule
• Access review schedule
• Security patch schedule
• Audit log review

Common Security Tasks

Task	Command/Action
Generate TLS certs	just dev-certs (dev) or use CA
Rotate JWT key	Update config, restart with overlap
Revoke agent	mantisctl cert revoke <id>
Audit access	Review /api/v1/audit/logs endpoint
Check cert expiry	openssl x509 -enddate -in cert.pem

Security Best Practices

1. Defense in Depth

Layer multiple security controls:

Internet → Firewall → WAF → TLS → Auth → RBAC → Audit

2. Least Privilege

• Grant minimum required permissions
• Use tenant-scoped roles where possible
• Review and revoke unused access

3. Secure Secrets

• Never commit secrets to version control
• Use environment variables for sensitive config
• Rotate secrets regularly

4. Monitor and Audit

• Enable audit logging
• Monitor for unusual activity
• Set up alerting on security events

5. Keep Updated

• Apply security patches promptly
• Update TLS configurations
• Review and update security settings

Threat Model

Threat	Mitigation
Man-in-the-middle	TLS/mTLS everywhere
Credential theft	JWT expiry, refresh tokens
Unauthorized access	RBAC, tenant isolation
Data breach	Encryption at rest
Rogue agent	Thumbprint verification
Audit tampering	Hash chain integrity

Next Steps

1. TLS Certificates - Set up transport security
2. mTLS Authentication - Configure agent auth
3. JWT Configuration - Set up API auth
4. Encryption at Rest - Protect stored data