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/thorax.crt"
key_path = "/etc/mantis/certs/thorax.key"

# 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/thorax.crt
export MANTIS_TLS_KEY_PATH=/etc/mantis/certs/thorax.key

Tarsus Configuration

[tls]
cert_path = "/etc/tarsus/cert.pem"
key_path = "/etc/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/tarsus/ca.crt"

Certificate Generation

Generate Self-Signed Certificate

Tarsus automatically generates a self-signed certificate on first run if one is not configured. You can also generate certificates manually using OpenSSL.

Manual Generation

# Generate private key
openssl genrsa -out /etc/tarsus/key.pem 2048

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

Certificate Parameters

Parameter	Recommended Value
Key size	2048 bits (RSA) or P-256 (ECDSA)
Validity	365 days
CN	Hostname or agent name
Signature	SHA-256

Thumbprint Management

Extract Thumbprint

# Get thumbprint from certificate
tarsus show-thumbprint

# Output:
# abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

# Using OpenSSL
openssl x509 -in /etc/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)

# 1. On agent: get thumbprint
tarsus show-thumbprint
# 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

Private Key Security

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

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

Certificate Renewal

Self-signed certificates should be renewed before expiry:

# Check expiration
openssl x509 -in /etc/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/tarsus/key.pem \
  -out /etc/tarsus/cert.pem \
  -days 365 \
  -subj "/CN=$(hostname)/O=Mantis Agent"

# Get new thumbprint
tarsus show-thumbprint

# 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 "$(tarsus show-thumbprint)"

Bulk Operations

Multiple Agents

For deploying multiple agents:

#!/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 "tarsus show-thumbprint")

  # 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: tarsus show-thumbprint
  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 -f

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

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

Thumbprint Mismatch

Problem: Agent rejected with “thumbprint mismatch”

Diagnosis:

# Get actual thumbprint from agent
tarsus show-thumbprint

# 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 'tarsus show-thumbprint')"

Certificate Expired

Problem: Agent rejected with “certificate expired”

Solution:

# On agent: regenerate 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"

# Get new thumbprint
tarsus show-thumbprint

# 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

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:

Deploy CA infrastructure (see CA-Signed Mode)
Issue CA-signed certificates to agents
Update Thorax configuration to auth_mode = "ca_signed"
Agents re-register with new certificates
Thumbprints still verified (defense-in-depth)

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