Client Registration Overview

Manage target agent registration and approval for secure deployments.

What is Client Registration?

Client registration is the process by which Tarsus agents (targets) establish trust with Mantis:

Registration Workflow

1. Agent Generates Certificate

When a Tarsus agent starts, it automatically generates a self-signed certificate if one is not configured:

# Tarsus generates certificate on first run and starts
tarsus run

# Output:
# Generated certificate with thumbprint:
# AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:...
# Waiting for registration approval...

2. Agent Requests Registration

The agent connects to Mantis and submits its certificate:

┌─────────────────────────────────────────────────────────────┐
│  Registration Request                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Client Name: web-prod-01                                   │
│  Hostname: web-prod-01.example.com                          │
│  IP Address: 192.168.1.100                                  │
│  Machine ID: abc123def456                                   │
│                                                             │
│  Certificate Thumbprint:                                    │
│  AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:...        │
│                                                             │
│  Status: Pending                                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3. Administrator Reviews

Administrators see pending registrations in Lens:

┌─────────────────────────────────────────────────────────────┐
│  Pending Registrations (3)                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────────┬────────────────┬──────────────────────┐│
│  │ Client         │ Hostname       │ Registered           ││
│  ├────────────────┼────────────────┼──────────────────────┤│
│  │ web-prod-01    │ 192.168.1.100  │ 5 minutes ago        ││
│  │ web-prod-02    │ 192.168.1.101  │ 3 minutes ago        ││
│  │ api-prod-01    │ 192.168.1.110  │ 1 minute ago         ││
│  └────────────────┴────────────────┴──────────────────────┘│
│                                                             │
└─────────────────────────────────────────────────────────────┘

4. Approve or Reject

After verifying the agent is legitimate:

Action	Result
Approve	Agent can receive deployments
Reject	Registration marked as Revoked, agent cannot connect until re-registered
Ignore	Remains pending

Registration Status

Status	Description	Can Deploy?
Pending	Awaiting administrator approval	No
Approved	Authorized to receive deployments	Yes
Revoked	Access denied (rejected while pending, or revoked after approval)	No

Registration Methods

Manual Registration (Default)

Most secure method - requires administrator approval:

1. Agent generates certificate and registers
2. Administrator verifies agent identity
3. Administrator approves registration
4. Agent begins receiving deployments

Token-Based Registration

Registration using pre-shared tokens:

1. Administrator creates registration token
2. Token is configured on agent
3. Agent registers with token
4. Automatically approved (if token allows)

See Registration Tokens for details.

Pre-Registration

Register a thumbprint before the agent connects:

1. Administrator adds thumbprint manually
2. Agent generates certificate with that thumbprint
3. Agent connects and is automatically recognized
4. Registration is immediately approved

See Certificate Thumbprints for details.

Viewing Registrations

Registration List

┌─────────────────────────────────────────────────────────────┐
│  Client Registrations                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Filter: [All            ▼]  Search: [_______________]      │
│                                                             │
│  ┌────────────────┬────────────┬────────────┬────────────┐ │
│  │ Client         │ Status     │ Hostname   │ Last Seen  │ │
│  ├────────────────┼────────────┼────────────┼────────────┤ │
│  │ web-prod-01    │ ● Approved │ 192.168... │ 2 min ago  │ │
│  │ web-prod-02    │ ● Approved │ 192.168... │ 5 min ago  │ │
│  │ api-prod-01    │ ○ Pending  │ 192.168... │ 1 min ago  │ │
│  │ old-server     │ ✗ Revoked  │ 192.168... │ 30 days    │ │
│  └────────────────┴────────────┴────────────┴────────────┘ │
│                                                             │
│  Showing 4 of 4 registrations                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Registration Detail

┌─────────────────────────────────────────────────────────────┐
│  Registration: web-prod-01                                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Status: ● Approved                                         │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│  Client Information:                                        │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Client Name: web-prod-01                              │ │
│  │ Hostname: web-prod-01.example.com                     │ │
│  │ IP Address: 192.168.1.100                             │ │
│  │ Machine ID: abc123def456789                           │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Certificate:                                               │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Thumbprint: AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:...   │ │
│  │ [View Full Certificate]                               │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  Timeline:                                                  │
│  ┌───────────────────────────────────────────────────────┐ │
│  │ Registered: January 15, 2024 10:30 AM                 │ │
│  │ Approved: January 15, 2024 10:35 AM by admin          │ │
│  │ Last Seen: January 20, 2024 2:15 PM                   │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│                                              [Revoke]       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via CLI

List Registrations

Client certificate registrations are managed with mantisctl cert.

# List all registrations
mantisctl cert list

# Filter by status
mantisctl cert list --status pending
mantisctl cert list --status approved
mantisctl cert list --status revoked

View Registration Details

# Show a registration by ID or thumbprint prefix
mantisctl cert show <registration-id>

# Output:
# ID: 550e8400-e29b-41d4-a716-446655440000
# Client: web-prod-01
# Status: approved
# Hostname: web-prod-01.example.com
# IP Address: 192.168.1.100
# Thumbprint: ABCDEF1234567890...
# Registered: 2024-01-15 10:30:00
# Approved: 2024-01-15 10:35:00 by admin
# Last Seen: 2024-01-20 14:15:00

Approve Registration

# Approve a pending registration (by ID or thumbprint prefix)
mantisctl cert approve <registration-id>

# Approve with notes
mantisctl cert approve <registration-id> \
  --notes "Verified via hostname and IP"

Revoke Registration

# Revoke an approved registration
mantisctl cert revoke <registration-id> \
  --reason "Server decommissioned"

Security Considerations

Verify Before Approving

Always verify the agent’s identity:

Verification	Method
Hostname	Matches expected server name
IP Address	From expected network range
Thumbprint	Matches pre-shared value (if pre-registered)
Timing	Registration matches expected deployment

Thumbprint Exchange

For high-security environments, exchange thumbprints out-of-band:

1. Generate certificate on target server
2. Record thumbprint securely
3. Pre-register thumbprint in Mantis
4. Start Tarsus agent
5. Registration auto-approves

Revocation

Revoke registrations when:

• Server is being decommissioned
• Security incident detected
• Certificate compromise suspected
• Agent misbehavior observed

Caution

Revoking a registration immediately prevents the agent from connecting. Active deployments may fail.

Best Practices

1. Review Pending Registrations Promptly

Don’t let registrations sit pending:

Practice	Benefit
Regular review schedule	Catch rogue agents quickly
Alert on new registrations	Immediate awareness
Auto-reject after timeout	Prevent stale entries

2. Use Registration Tokens for Automation

For large-scale deployments:

# Create token for automated registration (~365 days)
mantisctl registration create --name "CI/CD Deployments" \
  --max-uses 100 \
  --expires-hours 8760 \
  --auto-approve true

3. Document Approval Decisions

Add notes when approving:

mantisctl cert approve <id> \
  --notes "Ticket: OPS-1234, verified by infrastructure team"

4. Audit Registrations Regularly

Review approved registrations periodically:

• Remove revoked entries
• Verify active agents are still needed
• Check for unusual registration patterns

Troubleshooting

Registration Not Appearing

Cause: Network connectivity issue

Solution:

1. Verify Tarsus can reach Mantis server
2. Check firewall rules
3. Confirm TLS certificate is valid

Cannot Approve Registration

Cause: Insufficient permissions

Solution:

1. Verify user has registration management role
2. Check RBAC configuration
3. Contact administrator

Agent Shows “Pending” After Approval

Cause: Agent hasn’t reconnected

Solution:

1. Restart Tarsus agent
2. Check agent logs for errors
3. Verify network connectivity

Next Steps

• Approving Registrations - Detailed approval workflow
• Registration Tokens - Automated registration
• Certificate Thumbprints - Pre-registration workflow