Thumbprint Mode

Thumbprint Mode

Thumbprint mode enables mTLS authentication using self-signed certificates verified by their SHA-256 fingerprint.

Overview

How Thumbprint Mode Works

Authentication Flow

When to Use Thumbprint Mode

Ideal Use Cases

Scenario	Why Thumbprint Mode
Quick setup	No CA infrastructure needed
Small deployments	Manual management is feasible
Development	Simple to configure
Isolated networks	No external CA dependencies
POC/testing	Minimal setup time

Comparison with CA-Signed

Aspect	Thumbprint	CA-Signed
Setup complexity	Low	Medium
CA required	No	Yes
Scalability	Manual per-agent	Automated
Certificate management	Per-agent	Centralized
Best for	Small deployments	Enterprise

Configuration

Thorax Configuration

[tls]
auth_mode = "thumbprint"

# Server certificate
cert_path = "/etc/mantis/certs/server-cert.pem"
key_path = "/etc/mantis/certs/server-key.pem"

# No CA cert needed for thumbprint mode
# But can still be provided for server cert chain

Environment Variables

# Enable thumbprint mode
export MANTIS_TLS_AUTH_MODE=thumbprint
export MANTIS_TLS_CERT_PATH=/etc/mantis/certs/server-cert.pem
export MANTIS_TLS_KEY_PATH=/etc/mantis/certs/server-key.pem

Tarsus Configuration

[tls]
cert_path = "/etc/mantis/certs/tarsus-cert.pem"
key_path = "/etc/mantis/certs/tarsus-key.pem"

# Thorax's server certificate thumbprint (SHA-256, 64 hex chars).
# Required in thumbprint mode: Tarsus verifies the Thorax server cert by
# its fingerprint rather than a CA chain (Thorax presents a self-signed cert).
trust_server_thumbprint = "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"

# CA certificate used to verify the Thorax server and, in listen mode, to
# enforce mTLS on inbound connections. Required in all modes — without it
# Tarsus refuses to start.
ca_cert_path = "/etc/mantis/certs/ca-cert.pem"

Certificate Generation

Generate Self-Signed Certificate

Tarsus automatically generates a self-signed certificate on first run if one is not configured, and mantisctl cert generate-server/generate-client produce correctly-shaped certs (right EKUs and SANs) when you need to pre-generate one. Prefer those over hand-rolled OpenSSL.

Manual Generation (air-gapped fallback)

Only if the shipped tooling is unavailable.

The certificate must carry both clientAuth and serverAuth, plus a SAN for the hostname Thorax dials — in listen mode Thorax connects to the agent, so the agent presents this certificate as a server. A clientAuth-only certificate is rejected with UnsupportedCertificate on the first listen-mode connection.

cat > /tmp/agent-ext.cnf <<'EOF'
basicConstraints = CA:FALSE
keyUsage         = digitalSignature, keyEncipherment
extendedKeyUsage = clientAuth, serverAuth
subjectAltName   = DNS:web-prod-01.example.com
EOF

openssl req -new -x509 -nodes -newkey rsa:2048 \
  -keyout /etc/mantis/certs/tarsus-key.pem \
  -out /etc/mantis/certs/tarsus-cert.pem \
  -days 365 -sha256 \
  -subj "/CN=$(hostname)/O=Mantis Agent" \
  -extensions v3_req -config <(cat /etc/ssl/openssl.cnf /tmp/agent-ext.cnf)

systemctl restart tarsus@<instance>

Restarting is required — Tarsus reads its certificate once at startup and does not watch the file or handle SIGHUP.

Certificate Parameters

Parameter	Recommended Value
Key size	2048 bits (RSA) or P-256 (ECDSA)
Validity	365 days
CN	Hostname or agent name
Extended Key Usage	clientAuth, serverAuth
Subject Alt Name	DNS name Thorax dials (listen mode)
Signature	SHA-256

mantisctl cert generate-server --name <agent> --sans <hostname> produces a certificate with these properties without the OpenSSL config dance.

Thumbprint Management

Extract Thumbprint

# Get thumbprint from certificate
mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem

# Output:
# abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

# Using OpenSSL
openssl x509 -in /etc/mantis/certs/tarsus-cert.pem -fingerprint -sha256 -noout | \
  sed 's/SHA256 Fingerprint=//' | tr -d ':' | tr '[:upper:]' '[:lower:]'

Thumbprint Format

Format	Example
Mantis	abcdef1234567890abcdef1234567890... (64 chars)
OpenSSL	AB:CD:EF:12:34:56:78:90:... (colon-separated)

Convert between formats:

# OpenSSL to Mantis format
echo "AB:CD:EF:12:..." | tr -d ':' | tr '[:upper:]' '[:lower:]'

# Mantis to OpenSSL format (for display)
echo "abcdef12..." | sed 's/../&:/g' | sed 's/:$//' | tr '[:lower:]' '[:upper:]'

Registration Workflows

Pre-Registration (Recommended)

Register thumbprint before agent connects:

# 1. On agent: get thumbprint
mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem
# abcdef1234567890...

# 2. Share thumbprint securely with admin
# (phone, encrypted email, secure chat)

# 3. Admin pre-registers thumbprint
mantisctl cert pre-register \
  --name "web-prod-01" \
  --thumbprint "abcdef1234567890..."

# 4. Agent connects and is auto-approved
tarsus run

Post-Connection Approval

Approve after agent connects:

# 1. Agent connects (no pre-registration)
tarsus run
# Status: Pending (awaiting approval)

# 2. Admin sees pending registration
mantisctl cert list --status pending
# CLIENT         THUMBPRINT          HOSTNAME
# unknown-01     xyz789...          server.local

# 3. Admin verifies and approves (by registration ID or thumbprint prefix)
mantisctl cert approve "<REGISTRATION_UUID>" \
  --notes "Verified web-prod-01 out of band"

# 4. Agent is now authenticated

Via Lens UI

┌─────────────────────────────────────────────────────────────┐
│  Pending Registrations                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┬───────────────┬─────────────────────┐  │
│  │ Client         │ Thumbprint    │ Actions             │  │
│  ├────────────────┼───────────────┼─────────────────────┤  │
│  │ unknown-01     │ xyz789...     │ [Approve] [Reject]  │  │
│  │ unknown-02     │ abc123...     │ [Approve] [Reject]  │  │
│  └────────────────┴───────────────┴─────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Security Considerations

Thumbprint Verification

Always verify thumbprints through a secure channel:

Channel	Security Level	Use Case
In-person	Highest	High-security
Phone call	High	Verbal confirmation
Encrypted email	Medium	Audit trail
Secure chat	Medium	Quick verification

Caution

Never exchange thumbprints via unencrypted email or public channels.

Private Key Security

# Secure key file permissions
chmod 600 /etc/mantis/certs/tarsus-key.pem
chown root:root /etc/mantis/certs/tarsus-key.pem

# Verify
ls -la /etc/mantis/certs/tarsus-key.pem
# -rw------- 1 root root 1679 Jan 15 10:00 /etc/mantis/certs/tarsus-key.pem

Certificate Renewal

Self-signed certificates should be renewed before expiry:

# Check expiration
openssl x509 -in /etc/mantis/certs/tarsus-cert.pem -enddate -noout
# notAfter=Jan 15 10:00:00 2026 GMT

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

# Get new thumbprint
mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem

# Re-register with the new thumbprint (revoke old, pre-register new — there is no
# in-place "update thumbprint" verb)
mantisctl cert revoke "$OLD_REGISTRATION_ID" --reason "thumbprint rotation"
mantisctl cert pre-register --name "web-prod-01" --thumbprint "$(mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem)"

Bulk Operations

Multiple Agents

For deploying multiple agents:

deploy-agents.sh

#!/bin/bash
SERVERS="web-01 web-02 api-01 api-02"

for server in $SERVERS; do
  # Get thumbprint from server (assumes SSH access)
  thumbprint=$(ssh $server "mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem")

  # Pre-register in Mantis
  mantisctl cert pre-register \
    --name "$server" \
    --thumbprint "$thumbprint"

  echo "Registered: $server"
done

From Configuration Management

Ansible example:

- name: Get Tarsus thumbprint
  command: mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem
  register: thumbprint

- name: Register with Mantis
  uri:
    url: '{{ mantis_api_url }}/api/v1/registrations/pre-register'
    method: POST
    headers:
      Authorization: 'Bearer {{ mantis_token }}'
    body_format: json
    body:
      client_name: '{{ inventory_hostname }}'
      thumbprint: '{{ thumbprint.stdout }}'
      tenant_id: '{{ tenant_id }}'

Troubleshooting

Agent Not Connecting

Problem: Agent shows “Connecting…” but never authenticates

Diagnosis:

# Check agent logs
journalctl -u tarsus@<instance> -f

# Verify certificate
openssl x509 -in /etc/mantis/certs/tarsus-cert.pem -text -noout

# Test connection
openssl s_client -connect thorax.example.com:50051 \
  -cert /etc/mantis/certs/tarsus-cert.pem \
  -key /etc/mantis/certs/tarsus-key.pem

Thumbprint Mismatch

Problem: Agent rejected with “thumbprint mismatch”

Diagnosis:

# Get actual thumbprint from agent
mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem

# Compare with the registered thumbprint (by registration ID or thumbprint prefix)
mantisctl cert show "agent-registration-id"

# If different, certificate was regenerated

Solution:

# Re-register with the current thumbprint (revoke old, pre-register new)
mantisctl cert revoke "$OLD_REGISTRATION_ID" --reason "thumbprint rotation"
mantisctl cert pre-register --name "agent-name" \
  --thumbprint "$(ssh agent-server 'mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem')"

Certificate Expired

Problem: Agent rejected with “certificate expired”

Solution:

# On agent: regenerate certificate using OpenSSL
openssl req -new -x509 -nodes \
  -keyout /etc/mantis/certs/tarsus-key.pem \
  -out /etc/mantis/certs/tarsus-cert.pem \
  -days 365 \
  -subj "/CN=$(hostname)/O=Mantis Agent"

# Get new thumbprint
mantisctl cert thumbprint /etc/mantis/certs/tarsus-cert.pem

# Re-register with the new thumbprint (revoke old, pre-register new)
mantisctl cert revoke "$OLD_REGISTRATION_ID" --reason "certificate renewal"
mantisctl cert pre-register --name "agent-name" \
  --thumbprint "new-thumbprint-here"

# Restart agent
systemctl restart tarsus@<instance>

Common Errors

Error	Cause	Solution
no certificate presented	TLS config wrong	Check cert_path path
thumbprint not found	Not registered	Pre-register or approve
registration pending	Awaiting approval	Approve in Mantis
registration revoked	Agent was revoked	Re-register
certificate expired	Cert past validity	Regenerate certificate

Migration to CA-Signed

When ready to migrate from thumbprint to CA-signed mode:

1. Deploy CA infrastructure (see CA-Signed Mode)
2. Issue CA-signed certificates to agents
3. Update Thorax configuration to auth_mode = "ca_signed"
4. Agents re-register with new certificates

Migrating changes your admission control

CA-signed mode replaces thumbprint verification rather than adding to it. Once an agent presents a CA-signed certificate, Thorax trusts the CA signature and stops: it checks neither the thumbprint nor the approval status. Any agent holding a certificate from your CA is admitted, so CA issuance becomes your admission control.

Revocation still works — mantisctl cert revoke applies in both modes and takes effect within 60 seconds.

Agents whose certificate the CA did not sign continue to be thumbprint-validated, so the two schemes coexist during a migration.

Best Practices

1. Pre-Register When Possible

Pre-registration is more secure than post-connection approval:

• Reduces window of vulnerability
• Ensures only expected agents connect
• Creates audit trail before deployment

2. Use Meaningful Names

# Good: descriptive names
mantisctl cert pre-register --name "web-prod-01" --thumbprint "..."
mantisctl cert pre-register --name "api-staging-02" --thumbprint "..."

# Bad: generic names
mantisctl cert pre-register --name "server1" --thumbprint "..."
mantisctl cert pre-register --name "agent" --thumbprint "..."

3. Document Registrations

Maintain records of:

• Who requested the registration
• Purpose of the agent
• Expected thumbprint value
• Verification method used

4. Regular Audits

# List all registrations
mantisctl cert list

# Review pending approvals
mantisctl cert list --status pending

Next Steps

• CA-Signed Mode - PKI-based authentication
• mTLS Authentication - mTLS overview
• Key Rotation - Certificate renewal