Skip to content

Introduction to Tuoni server Plugins

One of the cornerstones of the Tuoni C2 framework is its modular plugin architecture, which simplifies the implementation of new features. This architecture supports both first-party and third-party plugins. All listeners, commands, and payloads available out of the box for Tuoni are, in fact, plugins.

This documentation covers the various types of plugins, how to implement your own, and best practices for plugin development.

Disclaimer

ShellDot is not responsible for any harm caused by third-party plugins. Please carefully verify any third-party plugin that you use. Tuoni is strictly an educational and training tool. ShellDot does not endorse and actively discourages the development of plugins intended to cause monetary or other damages to individuals or organizations.

Backwards Compatibility

Warning

The Tuoni plugin SDK is under active development. While the ShellDot team strives to maintain backwards compatibility between SDK versions, we cannot guarantee that breaking changes won’t occur before version 1.0.0. In such cases, we will first deprecate the changing functionality in one release before removing it entirely.

When developing a plugin, please update to new SDK versions as they are released and refactor any code with deprecation warnings. This documentation will be updated with guides on how to migrate to new SDK versions.

Plugin Types

Currently, there are three types of plugins supported by the Tuoni Plugin SDK:

  • Command Plugins - Provide command templates for sending commands to agents.
  • Listener Plugins - Offer functionality to create listeners that communicate with agents.
  • Payload Plugins - Provide payload templates for generating payloads to create and start agents.

Each plugin can only be of one type; it is not possible for a plugin to simultaneously be a Command Plugin and a Listener Plugin. However, there is some overlap between the types. For example, Listener Plugins can also provide command templates if it makes sense for the listener type to have its own command for communication or relaying purposes.

Command Plugins

Command plugins in the Tuoni C2 framework are designed to provide the Tuoni server with Command Templates. These templates allow users to define new commands that can be sent to agents, facilitating customized agent-server interactions.

Command Templates are essentially classes that provide to the Tuoni users a name, description and configuration schema for creating new commands. Commands can have background logic and threads, but their main purpose is to generate shellcode that are to be executed by agents and to parse results that are sent back from the agents.

Command Plugins do not handle the transportation of shellcode or results between the server and agents; this is managed by Listener Plugins.

Listener Plugins

Listener plugins are responsible for creating listeners that manage communication with agents. They listen and wait for agent communications and typically provide shellcode that is injected into the agent payload, enabling the agent to call back to the listener. Additionally, listeners keep track of connected agents and relay commands from the server to these agents.

Types of Listener Plugins:

  • Shellcode Listener - Provides shellcode for payloads that communicate with the listener. The server can only send shellcode commands to agents connected via this listener.

  • Generic Shell Listener - Expects agents that connect to it to not be initiated from Tuoni payloads and to have no inherent knowledge of Tuoni’s inner workings. Suitable for basic shell interactions, such as with netcat. The server can only send generic commands to agents of this listener.

  • External Listener - Facilitates communication with external integrations. Similar to Generic Shell Listeners in that it does not provide shellcode and does not rely on Tuoni payloads. Agents connected through this listener are expected to understand and interact with Tuoni, unlike generic shell listeners. Useful for managing other C2 frameworks and their agents via the Tuoni API/UI or for creating agents in environments where shellcode is not applicable (e.g., Python, JavaScript, or browser-based agents).

Payload Plugins

Payload plugins provide the Tuoni server with Payload Templates. These templates allow users to define new payloads that can be used to create agent executables.

Payload templates must specify their architecture and operating system compatibility, as well as the shellcode that is injected into the payload. The shellcode is responsible for establishing a connection to a listener and executing commands sent by the server.