Tuoni Script Engine type stubs

Type hints for Python scripts run by Tuoni. Install this package locally to get editor completion, API documentation, and static type checking for tuoni_script_engine.

The package contains type information only. Tuoni provides the actual tuoni_script_engine module when it runs a server-side script.

Python 3.12 or newer is required.

Installation

python -m pip install tuoni-script-engine-stubs

To check a script with Pyright:

python -m pip install pyright
python -m pyright path/to/script.py

Quick example

import tuoni_script_engine as tse

for agent in tse.agents.list(status=tse.AgentStatus.ACTIVE):
    print(agent.guid, agent.metadata.hostname)

tse.discovery.services.create(
    "10.10.20.15",
    445,
    protocol="tcp",
    banner="SMB",
)

API overview

APIs that accept configuration use one of these types:

tuoni_script_engine.JsonConfiguration({"key": "value"})
tuoni_script_engine.BinaryConfiguration(b"content")
tuoni_script_engine.MultipartConfiguration(
    files={"payload.bin": b"content"},
    json={"key": "value"},
)

Dynamic command aliases

A dynamic alias adds a command to Tuoni for as long as its script is loaded. Register an object that implements these methods:

• configuration_schema() returns the command configuration as JSON Schema.
• can_send_to_agent(agent) decides whether the command is available for an agent.
• validate_config(config, agent) performs any additional validation. Raise ValidationError when the input should be rejected.
• execute(ctx, config, agent) runs the alias. Use ctx to queue child commands, publish results, and finish or fail the alias.

The following alias exposes the native ps command under a new name:

import tuoni_script_engine as tse


class ProcessListAlias(tse.DynamicAlias):
    description = "List running processes"

    def configuration_schema(self) -> str:
        return '{"type":"object","properties":{},"additionalProperties":false}'

    def can_send_to_agent(self, agent: tse.Agent) -> bool:
        return agent.type is tse.AgentType.SHELLCODE_AGENT

    def validate_config(
        self,
        config: tse.Configuration,
        agent: tse.Agent,
    ) -> None:
        pass

    def execute(
        self,
        ctx: tse.AliasContext,
        config: tse.Configuration,
        agent: tse.Agent,
    ) -> None:
        command = ctx.queue_command("ps", tse.JsonConfiguration({}))

        if not command.wait_for_completion(timeout=300):
            command.cancel()
            ctx.fail("Process listing timed out")
            return

        if command.is_failed():
            error = command.result.error_message if command.result else None
            ctx.fail(error or "Process listing failed")
            return

        if command.result:
            ctx.set_result(command.result.entries)
        ctx.finish()


tse.commands.register_dynamic_alias("script-ps", ProcessListAlias())

An alias must eventually call ctx.finish() or ctx.fail(). It may call ctx.set_result(...) before completion to publish ongoing or final result entries.