TLS Certificates

Configure TLS certificates for secure communication between Mantis components.

Certificate Requirements

Component Certificates

Component	Certificate Type	Purpose
Mandible	Server certificate	HTTPS for API clients
Thorax	Server certificate	gRPC server for agents
Tarsus	Client certificate	mTLS authentication

Certificate Standards

Requirement	Specification
Key Algorithm	RSA 2048+ or ECDSA P-256+
Signature	SHA-256 or stronger
Validity	1 year recommended
Format	PEM encoded

Development Certificates

Quick Setup

For development environments, use the provided script:

just dev-certs

This generates:

Self-signed CA certificate and private key
Thorax server certificate (CN=thorax, serverAuth + clientAuth)
Tarsus listen-mode client certificate (CN=tarsus-dev, clientAuth + serverAuth)
Mandible dispatch certificate (CN=mandible, clientAuth only — required for Mandible→Thorax deployment dispatch)
Mandible server certificate (CN=mandible, serverAuth — for HTTPS on port 3000)
Lens dev-server certificate (CN=localhost, serverAuth — for Vite HTTPS on port 5173)

Development Certificate Location

certs/
├── ca-cert.pem          # CA certificate
├── ca-key.pem           # CA private key
├── server-cert.pem      # Thorax server certificate (serverAuth + clientAuth)
├── server-key.pem       # Thorax server private key
├── client-cert.pem      # Tarsus listen-mode client certificate (clientAuth + serverAuth)
├── client-key.pem       # Tarsus client private key
├── dispatch-cert.pem    # Mandible dispatch certificate (clientAuth, CN=mandible)
├── dispatch-key.pem     # Mandible dispatch private key
├── mandible-cert.pem    # Mandible server certificate (serverAuth, CN=mandible)
├── mandible-key.pem     # Mandible server private key
├── lens-cert.pem        # Lens dev-server certificate (serverAuth, CN=localhost)
└── lens-key.pem         # Lens dev-server private key

Production Certificates

Certificate Authority Options

Option	Use Case	Complexity
Public CA	Internet-facing services	Low
Private CA	Internal infrastructure	Medium
Self-managed CA	Air-gapped environments	High

Public CA Certificates

For internet-facing Mandible deployments:

# Using Let's Encrypt with certbot
certbot certonly --standalone -d mantis.example.com

# Certificate files
/etc/letsencrypt/live/mantis.example.com/fullchain.pem
/etc/letsencrypt/live/mantis.example.com/privkey.pem

Private CA Setup

For internal infrastructure:

# Create CA private key
openssl genrsa -out ca.key 4096

# Create CA certificate
openssl req -x509 -new -nodes -key ca.key \
  -sha256 -days 3650 \
  -subj "/CN=Mantis Internal CA/O=Your Organization" \
  -out ca.crt

Mandible TLS Configuration

Configuration File

[server]
host = "0.0.0.0"
port = 3000

[server.tls]
cert_path = "/etc/mantis/certs/server.crt"
key_path = "/etc/mantis/certs/server.key"

Environment Variables

Variable	Description	Example
`MANDIBLE__SERVER__PORT`	Server port	`3000`
`MANDIBLE__SERVER__TLS__CERT_PATH`	Certificate path	`/etc/mantis/certs/server.crt`
`MANDIBLE__SERVER__TLS__KEY_PATH`	Private key path	`/etc/mantis/certs/server.key`

Certificate Chain

For certificates signed by an intermediate CA:

# Concatenate certificate chain
cat server.crt intermediate.crt > fullchain.crt

Configure with the full chain:

[server.tls]
cert_path = "/etc/mantis/certs/fullchain.crt"
key_path = "/etc/mantis/certs/server.key"

Thorax TLS Configuration

Server Certificate

[grpc]
address = "0.0.0.0"
port = 50051

[tls]
auth_mode = "thumbprint"
cert_path = "/etc/mantis/certs/thorax.crt"
key_path = "/etc/mantis/certs/thorax.key"
ca_cert_path = "/etc/mantis/certs/ca.crt"

mTLS Settings

Thorax always requires client certificates (mTLS is mandatory). The auth_mode controls how they are validated:

[tls]
auth_mode = "ca_signed"
cert_path = "/etc/mantis/certs/thorax.crt"
key_path = "/etc/mantis/certs/thorax.key"
ca_cert_path = "/etc/mantis/certs/ca.crt"

Auth Mode	Description
`thumbprint`	Self-signed certs accepted, thumbprint verified at app layer (default)
`ca_signed`	Client certs must be CA-signed at TLS layer

Tarsus TLS Configuration

Client Certificate

[tls]
cert_path = "/etc/tarsus/cert.pem"
key_path = "/etc/tarsus/key.pem"
ca_cert_path = "/etc/tarsus/ca.crt"

Self-Signed Certificate Generation

For thumbprint mode, Tarsus automatically generates a certificate on first run if one is not configured. You can also generate one manually:

# Generate self-signed certificate using OpenSSL
openssl req -new -x509 -nodes \
  -keyout /etc/tarsus/key.pem \
  -out /etc/tarsus/cert.pem \
  -days 365 \
  -subj "/CN=$(hostname)/O=Mantis Agent"

# View the thumbprint
tarsus show-thumbprint

CA-Signed Certificate

For CA-signed mode:

# Generate CSR
openssl req -new -nodes \
  -keyout /etc/tarsus/key.pem \
  -out /etc/tarsus/client.csr \
  -subj "/CN=tarsus-web-prod-01/O=Your Organization"

# Sign with CA (on CA server)
openssl x509 -req -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt -days 365 -sha256

# Install on agent
cp client.crt /etc/tarsus/cert.pem

Certificate Generation

Server Certificate

# Generate server private key
openssl genrsa -out server.key 2048

# Generate CSR
openssl req -new -key server.key \
  -subj "/CN=mantis.example.com/O=Your Organization" \
  -out server.csr

# Create certificate with SAN
cat > server.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = mantis.example.com
DNS.2 = *.mantis.example.com
IP.1 = 10.0.0.10
EOF

# Sign with CA
openssl x509 -req -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt -days 365 \
  -extfile server.ext

Client Certificate

# Generate client private key
openssl genrsa -out client.key 2048

# Generate CSR
openssl req -new -key client.key \
  -subj "/CN=tarsus-agent-01/O=Your Organization" \
  -out client.csr

# Create certificate
cat > client.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature
extendedKeyUsage = clientAuth
EOF

# Sign with CA
openssl x509 -req -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt -days 365 \
  -extfile client.ext

Certificate Verification

Verify Certificate Chain

# Verify server certificate against CA
openssl verify -CAfile ca.crt server.crt

# Expected output:
# server.crt: OK

Check Certificate Details

# View certificate information
openssl x509 -in server.crt -text -noout

# Check expiration date
openssl x509 -in server.crt -enddate -noout

# Get thumbprint
openssl x509 -in server.crt -fingerprint -sha256 -noout

Test TLS Connection

# Test Mandible HTTPS
openssl s_client -connect mantis.example.com:3000 \
  -servername mantis.example.com

# Test Thorax gRPC with client cert
openssl s_client -connect thorax.example.com:50051 \
  -cert client.crt -key client.key -CAfile ca.crt

Certificate Storage

File Permissions

# Secure private keys
chmod 600 /etc/mantis/certs/*.key
chown mantis:mantis /etc/mantis/certs/*.key

# Certificates can be readable
chmod 644 /etc/mantis/certs/*.crt

Directory Structure

/etc/mantis/certs/
├── ca.crt              # CA certificate (readable)
├── server.crt          # Server certificate (readable)
├── server.key          # Server private key (restricted)
└── chain.crt           # Certificate chain (readable)

Secrets Management

For production, consider using:

Solution	Integration
HashiCorp Vault	PKI secrets engine
AWS Secrets Manager	Certificate storage
Kubernetes Secrets	cert-manager integration

Certificate Renewal

Manual Renewal

# Generate new CSR with existing key
openssl req -new -key server.key \
  -subj "/CN=mantis.example.com" \
  -out server.csr

# Sign new certificate
openssl x509 -req -in server.csr \
  -CA ca.crt -CAkey ca.key \
  -out server-new.crt -days 365

# Replace certificate (with brief downtime)
mv server-new.crt server.crt
systemctl restart mantis-mandible

Automated Renewal

For Let’s Encrypt certificates:

# Certbot auto-renewal
certbot renew --deploy-hook "systemctl reload mantis-mandible"

# Add to crontab
0 0 * * * certbot renew --quiet --deploy-hook "systemctl reload mantis-mandible"

Zero-Downtime Renewal

TLS Protocol Configuration

The TLS protocol version and cipher suites are not configurable. Mandible’s [server.tls] section accepts only cert_path and key_path; there are no min_version or cipher_suites keys. The underlying rustls stack negotiates TLS 1.2/1.3 with modern, secure cipher suites by default and rejects deprecated versions (TLS 1.0/1.1).

Version	Status
TLS 1.0	Not offered (deprecated)
TLS 1.1	Not offered (deprecated)
TLS 1.2	Supported
TLS 1.3	Supported (preferred)

Troubleshooting

Certificate Errors

Error	Cause	Solution
`certificate verify failed`	CA not trusted	Add CA to trust store
`certificate has expired`	Certificate expired	Renew certificate
`hostname mismatch`	Wrong CN or SAN	Regenerate with correct names
`unable to get local issuer`	Missing intermediate	Include full chain

Common Issues

Certificate chain incomplete:

# Check chain
openssl s_client -connect mantis.example.com:3000 -showcerts

# Fix: concatenate certificates
cat server.crt intermediate.crt > fullchain.crt

Permission denied on key file:

# Check permissions
ls -la /etc/mantis/certs/

# Fix permissions
chmod 600 /etc/mantis/certs/server.key
chown mantis:mantis /etc/mantis/certs/server.key

Wrong certificate format:

# Convert DER to PEM
openssl x509 -in cert.der -inform DER -out cert.pem -outform PEM

# Convert PKCS12 to PEM
openssl pkcs12 -in cert.p12 -out cert.pem -nodes

Next Steps

mTLS Authentication - Configure mutual TLS
Thumbprint Mode - Self-signed certificate mode
CA-Signed Mode - PKI-based authentication
Key Rotation - Certificate renewal procedures