Plugin Architecture

How Plugins Work

#

TantoC2 ships as a bare core — no transports, tools, agents, or modules are included by default. Everything is a plugin, discovered at runtime through two mechanisms:

1. Entry points (recommended): Install a plugin package (pip install tantoc2-transport-http) and it is discovered automatically via Python entry points
2. Directory scanning: Drop a .py file in the appropriate plugin directory; the framework scans for PluginBase subclasses

No code changes to the core system are required to add new plugins.

Plugin Base Class

#

Every plugin extends PluginBase:

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

from tantoc2.server.plugins import PluginBase

class PluginBase(ABC):
    @classmethod
    @abstractmethod
    def plugin_name(cls) -> str:
        """Unique name for this plugin."""

    @classmethod
    @abstractmethod
    def plugin_type(cls) -> str:
        """Type of plugin (e.g., 'transport', 'module', 'agentless')."""

Plugin Types

#

Hot-Reload

#

Drop a .py file into the appropriate directory and trigger a refresh:

CLI:

1
2

tantoc2> modules refresh
tantoc2> tools refresh

API:

1
2

POST /api/v1/agentless/modules/refresh
POST /api/v1/agent-modules/refresh

No server restart required.

Plugin Inbox

#

For easy deployment, drop files into the plugin inbox directory (plugin_inbox_dir config). The plugin watcher automatically handles them:

• .py files: Auto-detected by type and moved to the correct plugin directory
• .whl files: Installed via pip, then registered through entry points

The inbox is checked every bg_plugin_watcher_interval seconds (default: 30).

Dependency Auto-Install

#

Modules can declare pip dependencies in their metadata via dependencies: list[str]. Missing packages are auto-installed at discovery time. If installation fails, the module is tracked as unavailable with a reason — queryable via the unavailable_modules property on the module manager.

Deployment

#

Standalone Package (Recommended)

#

Package your plugin as a Python wheel with entry points. Install with pip install and the framework discovers it automatically:

1
2
3

pip install tantoc2-transport-http    # Transport
pip install tantoc2-tool-ssh          # Tools module
pip install tantoc2-agent-shinobi     # Agent package

File Drop

#

Place a .py file in the appropriate directory:

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

plugins/
  transports/
    my_transport.py
  agentless/
    my_agentless.py
  agent_packages/
    my_agent.py
modules/
  my_module.py
agent_modules/
  bof/
    windows/
      my_module/
        manifest.yaml
        payload.o

Plugin Inbox

#

Drop .py or .whl files into the inbox for automatic routing and installation.

The plugin is discovered on the next server start, refresh, or inbox scan.

Next Steps

#

• Agent Packages — crypto, wire protocol, and capability declarations
• Agent Modules — compiled payloads loaded into agents
• Transport Plugins — listener implementations
• Tools Modules — direct protocol interaction