TuoniC2¶

class tuoni.TuoniC2[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.

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_hosted(filename, file_content)[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:: The updated list of hosted files after deletion.
Return type:: dict

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()[source]¶

Retrieve a list of agents.

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_hosted()[source]¶

Retrieve a list of hosted files.

Returns:: A dictionary containing the details of hosted files.
Return type:: dict

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()
>>> 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_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