Admin Guide

Engagement Management

#

Creating Engagements

#

Engagements are isolated operational contexts with their own database, master key, agents, and credentials. Only admins can create engagements.

CLI:

1
2

tantoc2> engagements create "operation-name"
Engagement passphrase: ********

Web UI: Engagements page > “New Engagement” > fill name, description, passphrase > Create.

The passphrase derives the master key (PBKDF2) for at-rest encryption and is required to reopen the engagement after a restart. Store it securely.

Activating Engagements

#

Before agents and tasks can be processed, an engagement must be activated:

1

tantoc2> engagements use <engagement-id>

API: PUT /api/v1/engagements/<id>/activate

Archiving Engagements

#

Create an encrypted, portable backup:

1
2
3
4
5

curl http://localhost:8443/api/v1/engagements/<id>/archive \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"passphrase":"engagement-passphrase","output_path":"/backups/engagement.archive"}'

Importing Archives

#

1
2
3
4
5

curl http://localhost:8443/api/v1/engagements/import \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"archive_path":"/backups/engagement.archive","passphrase":"...","name":"imported-name"}'

Schema migrations are applied automatically during import, with a pre-migration backup.

Operator Management

#

Roles

#

TantoC2 uses four-tier RBAC:

Creating Operators

#

CLI:

1
2

tantoc2> operators create bob --role operator
Password for new operator: ********

API: POST /api/v1/operators/ with {"username", "password", "role"}

Granting Engagement Access

#

Non-admin operators must be explicitly granted access to each engagement:

1

tantoc2> operators grant <operator-id> <engagement-id>

Collector Dynamic Grants

#

Grant collectors temporary, scoped permissions:

1
2
3
4
5
6
7

POST /api/v1/collectors/grants
{
  "collector_id": "<id>",
  "permission": "manage_agents",
  "agent_ids": ["<agent-id>"],
  "expires_at": "2026-04-01T00:00:00Z"
}

Grants can be agent-scoped or global, time-limited or permanent.

Force Logout

#

Invalidate all tokens for an operator:

1
2

POST /api/v1/auth/force-logout
{"operator_id": "<id>"}

Background Services

#

The teamserver runs background services in-process. All intervals are configurable.

Dead Agent Detection

#

Scans agents and transitions status based on missed check-ins:

• Active → Dormant: No check-in for 3x beacon interval
• Dormant → Dead: No check-in for 10x beacon interval

Config: bg_dead_agent_interval (default: 60s)

Stale Task Cleanup

#

Expires tasks that have been pending or sent too long:

• Pending tasks: Expired after task_pending_ttl (default: 3600s)
• Sent tasks: Expired after task_sent_ttl (default: 7200s)

Config: bg_stale_task_interval (default: 300s)

Session Key Rotation

#

When enabled, rotates session keys exceeding the TTL. Agents renegotiate transparently on next check-in.

Config:

• key_rotation_enabled (default: false)
• key_rotation_session_ttl (default: 3600s)
• bg_key_rotation_interval (default: 300s)

Task Archival

#

Moves completed tasks older than a threshold to an archive table:

Config: task_archival_age (default: 86400s)

Manual trigger: POST /api/v1/tasks/archive

Backup and Recovery

#

Database Backup

#

Each engagement uses an isolated SQLite database under <data_dir>/<default_engagement_dir>/:

1

cp -r /opt/tantoc2/data /opt/tantoc2/data.backup.$(date +%Y%m%d)

Encrypted Archival

#

Use the engagement archive API for portable, encrypted backups of individual engagements. See Archiving Engagements above.