TantoC2 runs as a single Python process with no external service dependencies.
Design Principles
#- Per-engagement isolation: Each engagement gets its own SQLite database. Data from one engagement is invisible to another.
- Plugin architecture: Transports, tools modules, agent packages, and agent modules are all discovered at runtime.
- Modular agent protocol: Each agent package brings its own CryptoProvider and ProtocolCodec. Magic bytes route to the correct handler.
- Capability-driven agents: Each agent package declares its supported module formats, built-in commands, and capabilities. The teamserver uses these declarations to filter compatible modules and present appropriate options to operators.
- Dual module loading modes: Agent modules can be loaded in managed mode (results flow through loading agent) or daemonized mode (payload runs independently, may register as a new agent).
- No external dependencies: No Redis, Celery, or external database. Everything runs in-process with SQLAlchemy + SQLite.
Process Architecture
#
graph TB
subgraph Teamserver
Flask[Flask REST API]
SIO[Flask-SocketIO]
BG[Background Services]
Flask --> Auth[Auth / RBAC]
SIO --> Events[Event Manager]
Auth --> Pipeline[Message Pipeline]
Pipeline --> AM[Agent Manager]
Pipeline --> AMR2[Agent Module Registry]
AM --> DB[(SQLAlchemy)]
AMR2 --> DB
AMR[Agent Module Registry] --> DB
CS[Credential Service] --> DB
ALM[Tools Manager] --> DB
BldM[Build Manager] --> DB
BG --> DeadAgent[Dead Agent Scan]
BG --> StaleTask[Stale Task GC]
BG --> KeyRot[Key Rotation]
BG --> Archive[Task Archival]
BG --> PluginWatch[Plugin Watcher]
end
CLI[tantoc2-cli] -->|REST API| Flask
WebUI[Web UI] -->|REST + WS| Flask
WebUI -->|WebSocket| SIO
Listeners[Listeners] --> Pipeline
Agents[Agents] --> Listeners
Agents -->|P2P Relay| Agents
Code Layout
# 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
| src/tantoc2/
server/
app.py # Flask factory and startup
config.py # Configuration dataclass and loader
models.py # SQLAlchemy ORM models
engagements.py # Engagement lifecycle
auth.py # Authentication (tokens, passwords)
rbac.py # RBAC roles and permissions
audit.py # Audit logging
listeners.py # Listener manager
pipeline.py # Message pipeline
agents.py # Agent registration, check-in, tasks, lifecycle
messages.py # InternalMessage schema and MessageType enum
crypto.py # At-rest encryption primitives (PBKDF2, AES-256-GCM)
crypto_provider.py # CryptoProviderBase abstract class
protocol_codec.py # ProtocolCodecBase abstract class
agent_package.py # AgentPackageBase, BuildConfig, CryptoMaterial
module_manager.py # Server module discovery and execution
module_base.py # AbstractModule base class
credentials.py # Credential store
plugins.py # Plugin registry
build_manager.py # Agent build pipeline
file_transfers.py # File transfer management
agentless_manager.py # Tools module execution
agentless_base.py # AgentlessModuleBase abstract class
agentless_sessions.py # Interactive tools sessions
background.py # Background services
events.py # WebSocket event manager
database.py # Database manager (central + per-engagement)
api/ # Flask blueprints
auth_routes.py # /api/v1/auth/*
engagement_routes.py # /api/v1/engagements/*
operator_routes.py # /api/v1/operators/*
agent_routes.py # /api/v1/agents/*
agent_module_routes.py # /api/v1/agent-modules/*
module_routes.py # /api/v1/modules/*
credential_routes.py # /api/v1/credentials/*
plugin_routes.py # /api/v1/plugins/*
listener_routes.py # /api/v1/listeners/*
build_routes.py # /api/v1/builds/*
agentless_routes.py # /api/v1/agentless/*
file_routes.py # /api/v1/agents/<id>/files/*
audit_routes.py # /api/v1/audit/*
archive_routes.py # /api/v1/tasks/archive
collector_routes.py # /api/v1/collectors/grants
collection_request_routes.py # /api/v1/collection-requests/*
agent_module_registry.py # Agent module discovery and compatibility
plugin_watcher.py # Plugin inbox hot-reload watcher
cli/
app.py # CLI main loop and prompt
commands.py # CommandRouter with all handlers
agent_commands.py # Agent-scoped commands
agent_shell.py # Per-agent interactive shell
group_shell.py # Multi-agent group shell
tools_shell.py # Agentless tools shell
tui.py # Textual TUI implementation
output.py # Rich output helpers
tabs.py # Tab manager
themes.py # Color themes
client/
client.py # TantoC2Client
engagements.py # Engagement API methods
agents.py # Agent API methods
modules.py # Module API methods
credentials.py # Credential API methods
listeners.py # Listener API methods
builds.py # Build API methods
agentless.py # Agentless API methods
file_transfers.py # File transfer API methods
operators.py # Operator API methods
|
Component Interactions
#| Component | Responsibility |
|---|
| Flask API | REST endpoints, request validation, RBAC enforcement |
| Flask-SocketIO | Real-time event push to authenticated clients |
| Message Pipeline | Magic routing → crypto → codec → handler chain |
| Agent Manager | Registration, check-in processing, task CRUD, lifecycle, capability tracking |
| Agent Module Registry | Agent module discovery, YAML manifest validation, compatibility filtering by format/platform/arch |
| Tools Manager | Direct service interaction (SSH, SMB, etc.), proxy/tunnel routing |
| Credential Service | Encrypted storage, auto-extraction, export |
| Build Manager | Config stamping, template selection, output format selection, binary generation |
| Background Services | Dead agent detection, stale task cleanup, key rotation, archival, plugin watching |