Encryption at Rest

Encryption at Rest

Configure encryption for sensitive data stored in the Mantis database.

Overview

What is Encrypted

Mantis encrypts sensitive data stored in PostgreSQL:

Data Type	Encryption	Storage
Storage credentials (S3, Git)	AES-256-GCM	Database
Sensitive variables	AES-256-GCM	Database
TOTP secrets & backup codes	AES-256-GCM	Database
CA and certificate private keys	AES-256-GCM	Database
Identity-provider client secrets	AES-256-GCM	Database
External-identity tokens	AES-256-GCM	Database
SMTP / Slack / webhook credentials	AES-256-GCM	Database
Execution plans & prompted values	AES-256-GCM	Database
Config-repo webhook secrets	AES-256-GCM	Database
AI analysis provider keys	AES-256-GCM	Database
API keys	Argon2 hash (not reversible)	Database

Each context is bound to its row with distinct additional authenticated data, so a ciphertext cannot be moved between rows. Losing the master key makes all of the above unreadable — including TOTP secrets and CA/certificate private keys.

Encryption Architecture

Encryption Key Configuration

Generating an Encryption Key

# Generate 256-bit master key: 44 base64 characters ending in "="
openssl rand -base64 32

Configuration

The encryption configuration is a single base64-encoded 32-byte key under the [encryption] table. There is no enabled toggle or algorithm selector — encryption is always AES-256-GCM, and supplying a valid key is what enables credential encryption.

Generate the key on the host that will hold it; never reuse one from documentation:

openssl rand -base64 32

[encryption]
key = "<output of openssl rand -base64 32>"

Environment Variable (Recommended)

Store the key as an environment variable instead of in the config file:

export MANTIS_ENCRYPTION_KEY="$(openssl rand -base64 32)"

Caution

Never commit the encryption key to version control. Use environment variables or secrets management.

Key Management

Mantis uses the configured 32-byte key directly as the AES-256-GCM key — there is no key-derivation (HKDF) step and no per-record or per-data-type key hierarchy. A fresh random 96-bit nonce is generated for each encryption operation, so the same key safely encrypts many records. Rotating the key re-encrypts all existing records (see Key Rotation).

Encryption Details

AES-256-GCM

Mantis uses AES-256-GCM (Galois/Counter Mode):

Property	Value
Algorithm	AES-256
Mode	GCM (authenticated encryption)
Key size	256 bits
IV size	96 bits (12 bytes)
Tag size	128 bits (16 bytes)

Benefits:

• Authenticated encryption (integrity + confidentiality)
• Parallelizable encryption/decryption
• Hardware acceleration support (AES-NI)

Storage Format

Encrypted values are stored as:

Base64(IV || Ciphertext || Tag)

Component	Size	Purpose
IV	12 bytes	Initialization vector
Ciphertext	Variable	Encrypted data
Tag	16 bytes	Authentication tag

Configuring Sensitive Fields

Variable Encryption

Mark a variable as sensitive when creating it through the REST API (or the Lens UI). A variable created with variable_type: "sensitive" is encrypted at rest and its value is masked on read:

curl -X POST "https://api.mantis.example.com/api/v1/variable-sets/$SET_ID/variables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "DB_PASSWORD", "value": "supersecret123", "variable_type": "sensitive"}'

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Create Variable                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name *                                                     │
│  [DB_PASSWORD                               ]               │
│                                                             │
│  Value *                                                    │
│  [••••••••••••••••                          ]               │
│                                                             │
│  ☑ Sensitive (encrypt value at rest)                        │
│                                                             │
│  Scope:                                                     │
│  ○ Global  ● Environment  ○ Target                         │
│                                                             │
│                              [Cancel]  [Create Variable]    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Credential Storage

Storage backends are database-managed resources created through the API, not a config section — Mandible’s config is deny_unknown_fields and has no [storage] table, so putting one in mandible.toml fails startup. secret_access_key is encrypted on write and never returned by a read:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "artifacts",
        "bucket": "mantis-artifacts",
        "region": "us-east-1",
        "auth_type": "static",
        "access_key_id": "AKIAIOSFODNN7EXAMPLE",
        "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }' \
    "https://api.mantis.local/api/v1/storage/s3"

Database Considerations

PostgreSQL Encryption

In addition to application-level encryption, consider:

Level	Method	Protection
Application	AES-256-GCM	Data at rest in DB
Database	pgcrypto extension	Additional layer
Storage	LUKS/dm-crypt	Disk encryption
Cloud	AWS RDS encryption	Managed encryption

pgcrypto Extension

Enable for additional database-level encryption:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

Transparent Data Encryption (TDE)

For cloud deployments:

Provider	Feature	Configuration
AWS RDS	Encryption at rest	Enable in RDS console
Azure	TDE	Enable in Azure portal
GCP	Cloud SQL encryption	Enabled by default

API Key Hashing

API keys are hashed with Argon2 before storage, using the library’s default Argon2 parameters. These parameters are not configurable — there is no [api_keys] configuration section.

How API Keys Work

Note

API keys cannot be retrieved after creation. Only the Argon2 hash and an HMAC-SHA256 blind index are stored.

Key Rotation

Master Key Rotation

Rotate the master key annually or if compromised:

Stop the services first — they hold the key in memory and would write undecryptable records if left running during rotation. Export DATABASE_URL too; mantisctl key rotate connects to the database directly and has no --database-url flag.

systemctl stop mandible
export DATABASE_URL="postgres://mantis:...@db-host:5432/mantis"

# Both keys come from the environment; passed as arguments they would be visible
# in the process list for the whole rotation.
export MANTIS_ENCRYPTION_KEY="$OLD_KEY"
export MANTIS_NEW_ENCRYPTION_KEY=$(openssl rand -base64 32)

mantisctl key rotate

# Set MANTIS_ENCRYPTION_KEY to the new key in Mandible's env, then:
systemctl start mandible

See Key Rotation for the full procedure and why the stop is mandatory.

Rotation Process

See Key Rotation for detailed procedures.

Backup Considerations

Encrypted Backups

Database backups contain encrypted data:

Backup Type	Encryption Status
pg_dump	Data remains encrypted
File backup	Data remains encrypted
Snapshot	Data remains encrypted

Master Key Backup

Danger

If the master key is lost, encrypted data cannot be recovered.

Backup the master key securely:

• Store in separate secure location
• Use secrets management (Vault, AWS Secrets Manager)
• Document key recovery procedure
• Test key recovery periodically

Disaster Recovery

For disaster recovery, you need:

1. Database backup
2. Master key
3. Configuration files

# Restore database
pg_restore -d mantis mantis_backup.dump

# Set master key (from secure backup)
export MANTIS_ENCRYPTION_KEY="backed-up-key"

# Start services
systemctl start mandible thorax

Troubleshooting

Decryption Failures

Problem: Decryption failed: authentication error (wrong key, AAD, or tampered data)

Causes:

• Wrong master key
• Corrupted data
• Data modified in database

Solution:

# Verify that all encrypted records decrypt with the configured key
# (reads MANTIS_ENCRYPTION_KEY, or pass --key explicitly)
mantisctl key verify

Key Misconfiguration

Problem: SECURITY ERROR: Encryption key is not configured (missing key) or SECURITY ERROR: Encryption key must be exactly 32 bytes (256 bits), got N bytes (wrong length) or SECURITY ERROR: Encryption key is not valid base64 (encoding error).

Diagnosis:

# Check key format (should be base64)
echo "$MANTIS_ENCRYPTION_KEY" | base64 -d | wc -c
# Should output: 32

Solution:

# Ensure key is properly formatted
export MANTIS_ENCRYPTION_KEY="$(cat /path/to/key | tr -d '\n')"

Performance Impact

Encryption adds minimal overhead:

AES-256-GCM on a single field is microseconds of CPU; the dominant cost is the database round trip. Rotation processes records in batches (--batch-size, default 100), sequentially — not in parallel.

If performance issues occur:

# Check for hardware acceleration
grep -m1 'aes' /proc/cpuinfo
# Should show: aes (AES-NI support)

Security Audit

Verify Encrypted Data

Confirm that every encrypted record can be decrypted with the configured key. This is the primary integrity check after a key change or restore:

# Uses MANTIS_ENCRYPTION_KEY, or pass --key "<base64 key>"
mantisctl key verify

To generate a fresh key (for example before a rotation), use:

mantisctl key generate

Best Practices

1. Environment Variables for Keys

# Good: Environment variable
export MANTIS_ENCRYPTION_KEY="..."

# Works, but leaves the key in a file on disk; prefer the environment in production
# [encryption]
# key = "..."

2. Secrets Management

Use a secrets manager:

Tool	Integration
HashiCorp Vault	KV secrets engine
AWS Secrets Manager	IAM integration
Azure Key Vault	Managed identity
GCP Secret Manager	Service account

Example with Vault:

export MANTIS_ENCRYPTION_KEY=$(vault kv get -field=key secret/mantis/encryption)

3. Key Rotation Schedule

Key Type	Rotation Period
Master key	Annually
After compromise	Immediately
After personnel change	As needed

4. Layered Encryption

Enable multiple layers:

[encryption]
key = "<base64 32-byte key>"       # Application-level AES-256-GCM

[database]
url = "postgres://...?sslmode=require"  # TLS in transit

# Plus: Disk encryption on database server
# Plus: Cloud provider encryption (RDS, etc.)

5. Documentation

Maintain documentation for:

• Key storage location
• Key recovery procedure
• Rotation schedule
• Emergency contacts

Next Steps

• Key Rotation - Detailed rotation procedures
• Security Overview - Overall security architecture
• Database Setup - Database configuration