TuoniC2¶

class tuoni.TuoniC2(verify: str | bool = False)[source]¶

The primary class for establishing connections to and managing interactions with the Tuoni server. It provides functionality for controlling server operations and facilitating communication.

Parameters:: verify (str | bool) – A flag to enable or disable SSL verification. If a string is provided, it is treated as the path to a CA bundle file.

add_alias(name, description, command_type, command_conf={}, files=None)[source]¶

Add a new alias.

Parameters:

name (str) – The name of the alias to create.
description (str) – A description of the alias.
command_type (str | TuoniDefaultCommand) – The base command to associate with the alias.
command_conf (dict) – Configuration settings for the alias.
files (dict) – File parameters associated with the alias.

Returns:

The newly created alias.

Return type:

TuoniAlias

Examples

>>> alias1 = tuoni_server.add_alias(
>>>     "ls1",
>>>     "Alias made with python lib based on 'ls' default command class",
>>>     TuoniCommandLs,
>>>     {"depth": 1}
>>> )

>>> alias2 = tuoni_server.add_alias(
>>>     "ls2",
>>>     "Alias made with python lib based on command string name",
>>>     "ls",
>>>     {"depth": 2}
>>> )

>>> alias3 = tuoni_server.add_alias(
>>>     "easm",
>>>     "Alias for execute assembly default command class",
>>>     TuoniCommandexecuteAssembly,
>>>     {},
>>>     files = {
>>>         "executable": ["dotnet.exe",open("dotnet.exe", "rb").read()]
>>>     }
>>> )

>>> alias4 = tuoni_server.add_alias(
>>>     "bof1",
>>>     "Alias for bof based on command string name",
>>>     "bof",
>>>     files = {
>>>         "bofFile": ["bof.o",open("bof.o", "rb").read()]
>>>     }
>>> )

>>> alias5 = tuoni_server.add_alias(
>>>     "bof2",
>>>     "Alias for bof based on command ID",
>>>     "2ac58f33-d35e-4afd-a1ac-00e460ceb9f4",
>>>     files = {
>>>         "bofFile": ["bof.o",open("bof.o", "rb").read()]
>>>     }
>>> )

add_datamodel_credential(username, password, host, realm, source, note)[source]¶

Add a credential data model entry.

Parameters:

username (str) – The username.
password (str) – The password.
host (str) – Host where credential works.
realm (str) – Credential realm.
source (str) – Source of the credential.
note (str) – Additional notes.

Returns:

The newly created credential.

Return type:

TuoniDataCredential

Examples

>>> credential = tuoni_server.add_datamodel_credential(
>>>     "rick",
>>>     "NeverGonnaBypassYourEDR",
>>>     "10.20.30.40",
>>>     "", "", ""
>>> )

add_datamodel_host(address, name, note)[source]¶

Add a host data model entry.

Parameters:

address (str) – The host address.
name (str) – Given name to the host.
note (str) – Additional notes.

Returns:

The newly created host.

Return type:

TuoniDataHost

Examples

>>> host = tuoni_server.add_datamodel_host("10.20.30.40", "WS1", "Open windows machine")

add_datamodel_service(address, port, protocol, banner, note)[source]¶

Add a service data model entry.

Parameters:

address (str) – The service address.
port (int) – Port number.
protocol (str) – Service protocol.
banner (str) – Service banner.
note (str) – Additional notes.

Returns:

The newly created service.

Return type:

TuoniDataService

Examples

>>> service = tuoni_server.add_datamodel_service("10.20.30.40", "443", "HTTPS", "", "")

add_hosted(filename, file_content, original_filename=None)[source]¶

Add a hosted file.

Parameters:

filename (str) – The name of the file to host.
file_content (bytes) – The content of the file in bytes.

Returns:

The API URI for the uploaded file.

Return type:

str

Examples

>>> tuoni_server.add_hosted("/hosted/file/here.txt", b"HELLO WORLD")

add_user(username, password, authorities)[source]¶

Add a new user.

Parameters:

username (str) – The username for the new user.
password (str) – The initial password for the user.
authorities (list[str]) – A list of authorities or roles assigned to the user.

Returns:

The newly created user.

Return type:

TuoniUser

Examples

>>> user = tuoni_server.add_user(
>>>     "cool_new_user",
>>>     "cool_new_password",
>>>     [
>>>         "MANAGE_LISTENERS",
>>>         "MANAGE_USERS",
>>>         "SEND_COMMANDS",
>>>         "MANAGE_PAYLOADS",
>>>         "MODIFY_FILES",
>>>         "VIEW_RESOURCES",
>>>         "MANAGE_AGENTS"
>>>     ]
>>> )

create_payload(payload_template: str, payload_listener: int, payload_conf: dict, encrypted: bool = True, payload_name: str = None)[source]¶

Create a new payload.

Parameters:

payload_template (str) – The payload template to use.
payload_listener (int) – The ID of the listener associated with this payload.
payload_conf (dict) – A dictionary containing the payload’s configuration.
encrypted (bool) – Specifies whether traffic for this payload should be encrypted.
payload_name (str) – The name to assign to the payload.

Returns:

The unique ID of the created payload.

Return type:

Examples

>>> payload_id = tuoni_server.create_payload(
>>>     "shelldot.payload.windows-x64",
>>>     listener_id,
>>>     {"type": "executable"}
>>> )

delete_hosted(hosted)[source]¶

Delete a hosted file.

Returns:: None

download_payload(payload_id: int, file_name: str)[source]¶

Download a payload.

Parameters:

payload_id (int) – The unique ID of the payload to download.
file_name (str) – The name of the file to save the downloaded payload.

let_it_run()[source]¶: Block execution and wait indefinitely if any callback functions are initialized, or until all monitoring threads have completed.

load_agents(active=True, unactive=False)[source]¶

Retrieve a list of agents.

Parameters:

active (bool) – Should active agents be returned
unactive (bool) – Should unactive agents be returned

Returns:

A list of agents.

Return type:

list[TuoniAgent]

load_aliases()[source]¶

Retrieve a list of aliases.

Returns:: A list of aliases.
Return type:: list[TuoniAlias]

load_datamodel_credentials(page=0, pageSize=256, filter=None)[source]¶

Retrieve a list of credentials.

Returns:: A list of credentials.
Return type:: list[TuoniDataCredential]

load_datamodel_hosts(page=0, pageSize=256, filter=None)[source]¶

Retrieve a list of hosts.

Returns:: A list of hosts.
Return type:: list[TuoniDataHost]

load_datamodel_services(page=0, pageSize=256, filter=None)[source]¶

Retrieve a list of services.

Returns:: A list of services.
Return type:: list[TuoniDataService]

load_hosted()[source]¶

Retrieve a list of hosted files.

Returns:: A list of objects containing the details of hosted files.
Return type:: list[TuoniFile]

load_listener_plugins()[source]¶

Retrieve a list of listener plugins.

Returns:: A list of available listener plugins.
Return type:: list[TuoniListenerPlugin]

Examples

>>> http_listener_plugin = tuoni_server.load_listener_plugins()[
>>>     "shelldot.listener.agent-reverse-http"
>>> ]
>>> conf = http_listener_plugin.conf_examples["default"]
>>> conf["sleep"] = 2
>>> conf["instantResponses"] = True
>>> listener = http_listener_plugin.create(conf)

load_listeners()[source]¶

Retrieve a list of listeners.

Returns:: A list of active listeners.
Return type:: list[TuoniListener]

load_payload_plugins()[source]¶

Retrieve a list of payload plugins.

Returns:: A list of available payload plugins.
Return type:: list[TuoniPayloadPlugin]

load_users()[source]¶

Retrieve a list of users.

Returns:: A list of users.
Return type:: list[TuoniUser]

login(url: str, username: str, password: str)[source]¶

Parameters:

url (str) – The URL of the Tuoni server to connect to.
username (str) – The username for authentication.
password (str) – The password for authentication.

Examples

>>> tuoni_server = TuoniC2()
# Disabling SSL verification
>>> tuoni_server = TuoniC2(verify=False)
# Set path for CA bunle
>>> tuoni_server = TuoniC2(verify="/path/to/ca_bundle.pem")
# Login to the server
>>> tuoni_server.login("https://localhost:8443", "my_user", "S3cr37")

on_new_agent(function, interval: int = 1)[source]¶

Set a callback function to be triggered when a new agent connects.

Parameters:

function (func) – The function to execute when a new agent connects.
interval (int) – The interval, in seconds, to check for new connections.

Examples

>>> def new_agent_callback(agent):
>>>     print(
>>>         f"We got outselves a new agent {agent.guid} from {agent.metadata['hostname']}"
>>>     )
>>>
>>> tuoni_server.on_new_agent(new_agent_callback)

request_delete(uri: str, json_data: dict = None)[source]¶

Send a DELETE request to the Tuoni server.

Parameters:

uri (str) – The URI endpoint to send the request to.
json_data (dict) – A dictionary containing the JSON payload to include in the DELETE request.

Returns:

The server’s response as a dictionary.

Return type:

dict

request_get(uri: str, result_as_json: bool = True)[source]¶

Send a GET request to the Tuoni server.

Parameters:

uri (str) – The URI endpoint to send the request to.
result_as_json (bool) – If True, the server’s response is treated as JSON and converted to a dictionary.

Returns:

The server’s response, either as a raw string or a dictionary if result_as_json is True.

Return type:

str | dict

request_get_file(uri: str, file_name: str)[source]¶

Send a GET request to the Tuoni server and save the result to the filesystem.

Parameters:

uri (str) – The URI endpoint to send the request to.
file_name (str) – The name of the file where the response will be saved.

request_patch(uri: str, json_data: dict = None, files: dict = None)[source]¶

Send a PATCH request to the Tuoni server.

Parameters:

uri (str) – The URI endpoint to send the request to.
json_data (dict) – A dictionary containing the JSON payload to include in the POST request.
files (dict) – A dictionary of files to upload with the POST request.

Returns:

The server’s response as a dictionary.

Return type:

dict

request_post(uri: str, json_data: dict = None, files: dict = None)[source]¶

Send a POST request to the Tuoni server.

Parameters:

uri (str) – The URI endpoint to send the request to.
json_data (dict) – A dictionary containing the JSON payload to include in the POST request.
files (dict) – A dictionary of files to upload with the POST request.

Returns:

The server’s response as a dictionary.

Return type:

dict

Examples

>>> tuoni = TuoniC2()
>>> tuoni_server.request_post(
>>>     "/api/v1/command-alias",
>>>     {
>>>         "name": "bofX",
>>>         "description": "Example",
>>>         "baseTemplate": "bof",
>>>         "fixedConfiguration": {"method": "go"}
>>>     },
>>>     {"bofFile" : ["some_bof.o", open("some_bof", "rb").read()]}
>>> )

request_put(uri: str, json_data: dict = None)[source]¶

Send a PUT request to the Tuoni server.

Parameters:

uri (str) – The URI endpoint to send the request to.
json_data (dict) – A dictionary containing the JSON payload to include in the PUT request.

Returns:

The server’s response as a dictionary.

Return type:

dict

wait_new_agent(interval: int = 1, max_wait: int = 0)[source]¶

Wait for a new agent to connect.

Parameters:

interval (int) – The interval, in seconds, to check for new connections.
max_wait (int) – The maximum time to wait, in seconds. A value of 0 means to wait indefinitely.

Returns:

The newly connected agent.

Return type:

TuoniAgent