Tool authoring reference

The reference for authoring a custom Tool definition: the fields a Tool needs, how parameters and targets work, the Compiler and Processor contracts, how to validate and register, and a set of worked examples.

Follow Create and publish a Tool for the product workflow. This page describes the definition fields and implementation interfaces.

The Tool definition

The Tool definition describes the metadata, inputs, execution, and output processing for the capability. In the code editor, tool.json holds the definition and can reference separate Compiler and Processor files. The authoring tools resolve those files when submitting the definition to Method.

Families

A Tool belongs to exactly one MITRE tactic family:

RECONNAISSANCE, RESOURCE_DEVELOPMENT, INITIAL_ACCESS, EXECUTION, PERSISTENCE, PRIVILEGE_ESCALATION, DEFENSE_EVASION, CREDENTIAL_ACCESS, DISCOVERY, LATERAL_MOVEMENT, COLLECTION, COMMAND_AND_CONTROL, EXFILTRATION, IMPACT.

Authoring workflow

The Tool’s output determines its generated Object Types and success criteria. Its inputs determine the Compiler’s parameters and targets. The Processor connects the two by interpreting execution output as Objects and relationships.

For the build sequence, follow Create and publish a Tool.

Parameters

A Tool takes two kinds of input.

Direct parameters

Ontology parameters

An Ontology parameter points at an Object Type by its identifier. Common ones:

Requirements

The definition’s requirements field describes which parameter groups the Compiler requires.

Keep requirements aligned with the parameters and targets used by the Compiler. Validate representative input combinations, including missing required values, before publishing.

Compilers

A Compiler deterministically turns typed Tool inputs and selected Ontology Objects into the execution plan a Jackal receives. It is not a place for an AI to improvise commands. Keep parameters minimal, validate every value that changes behavior, and reject unsupported combinations with a clear CompileException before the Tool runs.

A Tool uses exactly one compiler type.

Script Tool

Script Tools are the simplest shape and need no packaged binary, only named shell commands. They run on a deployed Jackal.

OS targeting supports Linux (any distribution or a specific one such as Ubuntu), macOS, and Windows (desktop or Server).

Prefer generic Linux with distribution: null unless the Tool genuinely depends on a narrower distribution. Explicitly list every supported architecture. Most portable Linux Tools support both AMD_64 and ARM_64.

Static script tools

A static Script Tool runs fixed commands with no parameter substitution. Each command has a name and a shell string. The name is how the Processor identifies that command’s stdout output.

Parameterized script tools

To use direct parameters in shell commands, add populateParameters and reference values as <<name>> placeholders.

class ResolveScriptParameters(MethodToolScriptCompiler):
    def compile(self, input: MethodToolCompileInput, replacements: ScriptReplacements) -> None:
        domain = input.get("domain")
        timeout = input.get("timeout") or 5
        if not domain or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9.-]*", str(domain)):
            raise CompileException("domain must contain only hostname characters")
        if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout < 1 or timeout > 60:
            raise CompileException("timeout must be an integer from 1 to 60")
        replacements.set("domain", str(domain))
        replacements.set("timeout", str(timeout))

timeout '<<timeout>>' getent ahosts '<<domain>>' || true

Target-aware script tools

Targets are selected from configured Ontology Parameters. When a target is set, the Tool runs once per resolved Object. Use the target access pattern for the compiler branch you selected, and validate target assumptions before adding them to a command. Use the Compiler validator with representative target Objects to inspect the final command for every supported platform and architecture.

CLI Tool

Use cliTool when execution is a binary plus arguments. Method resolves the binary, then appends fixed commandArgs and the dynamic arguments from populateParameters.

class BuildCliArguments(MethodToolCliCompiler):
    def compile(self, input: MethodToolCompileInput, arguments: CliArguments) -> None:
        target = input.get("targetHost")
        timeout = input.get("timeout") or 30
        verbose = input.get("verbose") or False
        if not target:
            raise CompileException("targetHost is required")
        arguments.add_argument("--target", str(target))
        arguments.add_argument("--timeout", str(timeout))
        if verbose:
            arguments.add_argument("--verbose", "true")

Tool locations

Courier Tool

Use courierTool when the Tool needs direct control over a Courier workflow, such as composed actions, explicit outcomes, file transfer, cleanup, or a Jackal-specific action. Prefer Script or CLI when their higher-level primitives express the capability cleanly. Courier is more flexible, but it exposes more execution details and failure modes.

Define one MethodToolCourierCompiler subclass in populateParameters. Its compile method adds one or more workflows to the injected CourierWorkflows collection. Do not add imports: Method injects Workflow, CourierWorkflows, MethodToolCompileInput, and CompileException into the sandbox.

class GatherFileCompiler(MethodToolCourierCompiler):
    def compile(self, input: MethodToolCompileInput, workflows: CourierWorkflows) -> None:
        file_identifier = input.get("fileIdentifier")
        if not file_identifier:
            raise CompileException("fileIdentifier is required")
        workflow = Workflow()
        steps = [
            workflow.actions.download_file(
                file_identifier=file_identifier,
                target_path="/tmp/tool-input",
                signal="downloaded",
            ),
            workflow.actions.exfil_file(
                path="/tmp/tool-input",
                signal="exfiltrated",
                base64_contents="file_base64",
            ),
        ]
        workflows.add_workflow(workflow.build(steps=steps))

Each output that a Processor needs must be a named Signal. First-class actions declare the Signal when you pass signal="name". For custom actions, explicitly declare the Signal in the enclosing step’s outcomes. Otherwise the action can run successfully but the Processor cannot receive its output.

workflow = Workflow()
action = workflow.actions.custom(action_type_id=9001, action_contents=b"tool-input")
outcomes = workflow.outcomes.create(generates_signals=["custom_output"])
step = workflow.steps.create(action=action, outcomes=outcomes)
workflows.add_workflow(workflow.build(steps=[step]))

Processors

A Processor turns raw Signals into durable, reusable Ontology knowledge. It is not an execution log. Model what the Tool discovered, such as a host, service, account, credential, vulnerability, configuration, or finding. Keep commands, wrappers, timestamps, exit codes, and raw diagnostics in Signals, where Method retains them for auditability.

Define exactly one MethodToolProcessor subclass and return generated Ontology Objects in ProcessResult.

Working in restricted Python

Inline Processor code runs in a restricted sandbox. Repository source files can include SDK imports supplied by starter templates; follow the authoring environment’s source-loading and validation guidance for those files. For code passed directly to the restricted runtime:

• Do not use import. Method injects json, re, method_ontology_sdk, generated Ontology constructors, and the SDK base and result classes.
• Define exactly one Processor subclass.
• Do not access private or dunder attributes such as __dict__.
• Do not perform file, network, subprocess, eval, dynamic import, or package installation.
• Do not define helpers whose names begin with _.
• Every Object Type your Processor creates must appear in generatesTypes.
• Use the connected Method development tools to look up Object schemas, constructor fields, and link helper names.

class JsonReportProcessor(MethodToolProcessor):
    def process(self, output: MethodToolOutput) -> ProcessResult:
        raw = output.get_raw_output()
        if not raw:
            return ProcessResult(success=False, error_message="missing report output")
        try:
            data = json.loads(raw)
        except ValueError as exc:
            return ProcessResult(success=False, error_message=f"invalid report JSON: {exc}")
        addresses = [
            IpAddress(ip_address=item["ip"])
            for item in data.get("addresses") or []
            if item.get("ip")
        ]
        return ProcessResult(success=bool(addresses), new_ontology=addresses)

When the Tool emits exactly one output, call output.get_raw_output(). For multiple named Signals or workflow steps, call output.get_raw_output(step="signal_name"). Use generated constructors and link helpers to create Objects and their relationships:

ip = IpAddress(ip_address="192.0.2.10")
host = Host(hostname="WEB01").with_ip_address(ip)
return ProcessResult(success=True, new_ontology=[ip, host])

Handle output according to the Tool’s semantics. Empty output can be a valid result for an enumeration Tool. Malformed output should fail or warn intentionally. Never silently create placeholder Objects from an incomplete report.

Success criteria

successCriteria is an Object search filter that should match the Object that best proves the Tool worked.

Keep the Processor’s success=True aligned with the success criteria you set. A run that reports success but creates no matching Object makes the UI and recommendation logic inconsistent.

Validation and registration

The authoring tools validate three parts of a Tool:

Changes to any of these parts can affect the others. The guides describe the full validation sequence to repeat before publication.

Published versions are immutable. Saving a draft, editing source, committing, pushing, and validating are separate from publishing a runnable version. The Method extension’s Publish action saves and commits pending changes, pushes the release, and publishes the version. See Create and publish a Tool for the procedure.

Validation checks a definition, a compiled plan, and sample output. It does not execute the Tool in a target environment. Test the published version separately to verify its real execution and resulting Objects.

Examples

Script Tool, no target: host inventory

The Jackal host itself is the target, so the Tool needs no Ontology input. A good first Tool.

OS: Linux, any distribution

Commands:

class HostInventoryProcessor(MethodToolProcessor):
    def process(self, output: MethodToolOutput) -> ProcessResult:
        host_lines = (output.get_raw_output(step="hostname") or "").strip().splitlines()
        host_name = host_lines[0].strip() if host_lines else None
        ip_objects = [
            IpAddress(ip_address=ip)
            for ip in re.findall(
                r"(?:\d{1,3}\.){3}\d{1,3}", output.get_raw_output(step="addresses") or ""
            )
        ]
        if not host_name and not ip_objects:
            return ProcessResult(success=False)
        if not host_name:
            return ProcessResult(success=True, new_ontology=ip_objects)
        host = Host(hostname=host_name)
        for ip in ip_objects:
            host = host.with_ip_address(ip)
        return ProcessResult(success=True, new_ontology=[*ip_objects, host])

Script Tool, IP targets: reachability check

The user selects IP Address Objects, and the script runs once per target.

OS: Linux, any distribution Target: IP Address (one run per selected Object)

Commands:

class ReachabilityProcessor(MethodToolProcessor):
    def process(self, output: MethodToolOutput) -> ProcessResult:
        raw = output.get_raw_output(step="ping") or ""
        addresses = [
            IpAddress(ip_address=match)
            for match in re.findall(r"(?m)^REACHABLE target=([^\s]+)$", raw)
        ]
        return ProcessResult(success=bool(addresses), new_ontology=addresses)

CLI Tool, direct URLs: JSON report

The binary downloads per OS and architecture and emits one JSON report.

Location: Direct URLs (Linux x86_64 and arm64) Fixed arguments: discover dns forward Target: FQDN (one run per selected Object)

class DnsForwardProcessor(MethodToolProcessor):
    def process(self, output: MethodToolOutput) -> ProcessResult:
        data = json.loads(output.get_raw_output() or "{}")
        addresses = []
        for lookup in (data.get("result") or {}).get("lookups") or []:
            ip = lookup.get("ipAddress")
            if not ip:
                continue
            addresses.append(IpAddress(ip_address=ip))
        return ProcessResult(success=bool(addresses), new_ontology=addresses)

Common pitfalls

Final review checklist

• Tool name is lowercase alphanumeric and versioned.
• Risk level accurately reflects expected operational impact.
• Required parameters match the Compiler’s assumptions.
• Every Ontology target parameter appears in Compiler targets.
• Script substitution values are validated, quoted for the target shell, and fully substituted.
• CLI commandArgs do not include the binary path.
• Processor defines exactly one MethodToolProcessor subclass.
• generatesTypes includes every Object Type the Processor creates.
• Success criteria matches a created Object Type.
• A valid sample output and an empty or negative output were both tested.
• Compiler validation passed for every OS and architecture you support.