maltego-transform-build

Maltego Transform Build Skill

Purpose

Guide agents through implementing SDK-native transforms. Focus on async @register_transform patterns, typed entities, and clean SDK idioms.

Step-by-Step: Build a Transform

1. Load Basics If Needed

Load maltego-transform-basics for surface-level mechanics such as function signatures, settings injection, context.log, entity returns, graph returns, and IntegrationClient calls. Skip it if you already have the pattern.

2. Set Up the Transform Function

from maltego.server import register_transform
from maltego.model.context import MaltegoContext
from maltego.entities import Domain, IPv4Address  # always use standard entities first

@register_transform(display_name="Domain to IP")
async def domain_to_ip(input_entity: Domain, context: MaltegoContext) -> list[IPv4Address]:
    ...

Rules:

• Always async — sync functions are not supported in the SDK.
• Type-annotate the first parameter with the correct entity class — do not pass input_entity= to the decorator.
• Import entities from maltego.entities — check standard entities first. (maltego.entities ships in the maltego-transforms-std-entities package; install it alongside the SDK.)

3. Access Input Entity Values

• Primary value: input_entity.value
• Typed properties: input_entity.first_name, input_entity.domain, etc.
• Do NOT use string-based property lookups — use typed attributes.

4. Make HTTP Calls via IntegrationClient

from maltego.util import IntegrationClient

# Instantiate a shared client for your project
client = IntegrationClient()

@register_transform(...)
async def my_transform(input_entity: Domain, context: MaltegoContext) -> list[IPv4Address]:
    # Pass context to every call
    response = await client.get("/api/endpoint", params={"q": input_entity.value}, context=context)
    data = response.json()

• Pass context=context to all client methods so limits and errors are tracked properly.
• The client always raises on non-2xx responses and network errors (there is no suppress flag). Catch the relevant exception from maltego.model.exception: