SDK API Reference

This article is the consolidated API reference for the Maltego Transforms SDK (maltego-transforms): the core classes you import from maltego.server (and a couple of supporting modules) when writing transforms, entities, and transform servers. For these classes used in context, see the SDK Examples and Writing Your First Transform (Quickstart) articles in this folder.

MaltegoGraph

MaltegoGraph (maltego.server.MaltegoGraph, defined in maltego.model.graph) represents a Maltego graph as provided to a transform function: a collection of entities and the links between them. Use it as a transform's input type to receive a whole selection of entities, or as a return type to produce multiple entities with custom links between them.

Use MaltegoGraph as an input annotation to receive the entire selected graph:

from maltego.server import register_transform, MaltegoGraph
from maltego.entities import Phrase


@register_transform(
    display_name="Count Entities and Links [My Transforms]",
)
async def count_graph(graph: MaltegoGraph) -> Phrase:
    num_entities = len(graph.entities)
    num_links = len(graph.links)
    return Phrase(f"Graph has {num_entities} entities and {num_links} links")

To restrict the graph to specific entity types, use a generic type parameter, e.g. MaltegoGraph[Person] (this also restricts which selections the transform appears for in the client). A transform can also return a MaltegoGraph to produce multiple entities with custom links between them, built via graph.add_entity() and graph.add_link():

from maltego.server import register_transform, MaltegoGraph
from maltego.entities import Phrase


@register_transform(
    display_name="Create Linked Chain [My Transforms]",
)
async def create_chain(graph: MaltegoGraph) -> MaltegoGraph:
    # Add entities to the output graph
    previous = graph.add_entity(Phrase("Start"))


    for i in range(5):
        entity = graph.add_entity(Phrase(f"Node {i}"))
        # Create a link between entities
        graph.add_link(previous, entity)
        previous = entity


    return graph

Links can be traversed with graph.get_source() / graph.get_target():

from maltego.server import register_transform, MaltegoGraph
from maltego.entities import Phrase


@register_transform(
    display_name="Analyze Connections [My Transforms]",
)
async def analyze_links(graph: MaltegoGraph) -> Phrase:
    for link in graph.links:
        source = graph.get_source(link)  # Source entity
        target = graph.get_target(link)  # Target entity
        label = link.label               # Link label (if any)
        # Analyze the relationship...


    return Phrase(f"Analyzed {len(graph.links)} connections")

These examples aren't exhaustive; see the SDK Examples article for more variations, including using Union types to accept multiple entity types in a typed graph input.

Constructor parameters:

Key methods and properties:

MaltegoEntity

MaltegoEntity (maltego.server.MaltegoEntity, defined in maltego.model.entity) is the typed base class for all Maltego entities. Transform inputs and outputs are MaltegoEntity subclasses (either the standard entities from maltego.entities or custom entities you define), and custom entity classes are declared as Python classes decorated with @register_entity.

Constructor parameters (also available as instance attributes/properties):

Key methods:

MaltegoEntityConfig

MaltegoEntityConfig (maltego.server.MaltegoEntityConfig, defined in maltego.model.entity.config) configures how a custom entity class is displayed and categorized in the Maltego client. It is assigned to a custom entity's Config class attribute.

Constructor parameters (all optional):

MaltegoEntityProperty

MaltegoEntityProperty (maltego.server.MaltegoEntityProperty, a function defined in maltego.model.entity.property) declares a single property on a custom entity class.

from maltego.entities import Person
from maltego.server import (
    MaltegoEntityConfig,
    MaltegoEntityProperty,
    register_entity,
)


@register_entity
class StaffMember(Person):
    Config = MaltegoEntityConfig(display_name="Staff Member")


    employee_id: str = MaltegoEntityProperty(
        display_name="Employee ID",
        sample_value="E-42",
    )

Parameters:

MaltegoLink

MaltegoLink (maltego.server.MaltegoLink, defined in maltego.model.link) represents a link between two entities in a MaltegoGraph. Links are usually created via graph.add_link() or graph.add_child() rather than instantiated directly.

Constructor parameters:

Key methods and properties:

TransformSetting

TransformSetting (maltego.server.TransformSetting, defined in maltego.model.transform.setting) defines a configurable transform setting: a value the Maltego client lets the user provide per-transform (such as an API key or a numeric limit).

Constructor parameters:

For usage guidance, naming behavior, and worked examples, see the Transform Settings article in this folder.

MaltegoContext

MaltegoContext (maltego.server.MaltegoContext, defined in maltego.model.context) is the server-side execution context passed into a transform function, carrying request data, logging, prompts, and authentication information for the current transform run.

Selected constructor parameters (a MaltegoContext is built by the SDK server, not typically constructed by transform authors):

Key attributes and methods:

Authentication fields

context.identity is populated only from trusted auth validation results. When AuthSettings(expose_unverified_claims=True) or MALTEGO_SERVER_AUTH_EXPOSE_UNVERIFIED_CLAIMS=true is configured, context.unverified_auth_claims may contain syntactically decoded bearer JWT/OIDC or SAML claims. This can be enabled even when auth validation itself is disabled. Those claims are not signature-verified and must not be used for authorization, tenancy, billing, auditing, or rate limiting.

TransformMiddleware

TransformMiddleware (maltego.middlewares.middlewares.TransformMiddleware) is an abstract base class for hooking into the transform execution lifecycle. Subclass it and implement both abstract methods to run custom logic before and after every transform execution.

Abstract methods to implement:

For middleware lifecycle guidance and registration examples, see the Transform Middlewares article in this folder.

MaltegoHubItem

MaltegoHubItem (maltego.server.MaltegoHubItem, defined in maltego.model.server) defines the metadata shown for an integration in the Maltego Hub: display name, description, icon, preview image, and provider contact details. Values can also be supplied via environment variables, since the class is a Pydantic BaseSettings model.

For when to define a hub item and how to register it, see the Hub Items article in this folder.