Maltego Transforms SDK Overview

Modified on Tue, 14 Jul at 12:22 PM

This article is a routing page for the Maltego Transforms SDK (Python
package ``maltego-transforms``). If you are looking for the older Maltego
TRX library, iTDS, or classic TDS/Transform Server setup guides, see
*Transform Libraries* and the articles in *Legacy Code* in this same
category instead. This SDK is not the TRX/classic protocol stack. For
current Graph Browser and Graph Desktop compatibility, see the *Client
Support and Limitations* article in this SDK documentation section.

What is the Maltego Transforms SDK?

maltego-transforms is Maltego's current Python SDK for building Maltego transform servers. It replaces maltego-trx as the recommended framework for new integrations. It provides typed entity classes, a transform server runtime, authentication, pagination, and Maltego Hub publishing support out of the box.

The quickest way to learn the SDK is to generate a project and use the shipped starter files as a working reference:

pip install maltego-transforms
maltego-transforms start my_project
cd my_project
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python project.py

When the server starts, add the seed URL shown by the server to Maltego. The public-safe generated project runs over HTTP by default and serves http://127.0.0.1:3000/seed. Older local templates may use development HTTPS certificates and serve https://127.0.0.1:3000/seed instead.

Current SDK version: 1.0.0.

Who this is for

Developers building a new Maltego transform server in Python.
Teams migrating an existing Maltego TRX (maltego-trx) transform server to the current SDK.
Anyone integrating a third-party data source with Maltego via custom Transforms, Entities, or Hub items.

This is not:

TRX/classic protocol reference documentation — see TRX Transform Library Guide and Transform Libraries in this category.
iTDS/Transform Distribution Server administration documentation — see What is a Transform Distribution Server (TDS)? and Writing Transforms in this category.
End-user Maltego Desktop/Graph documentation — see Maltego Desktop Application Requirements and Maltego Graph Browser categories.

Start here if you want to...

...install the SDK and create a new project -- see Installing and Setting Up the SDK.
...write your first transform -- see Writing Your First Transform (Quickstart).
...decide between standard and custom entities -- see Standard Entities Overview and Composed Entities.
...map an external API's JSON response onto Maltego entities -- see Pydantic Mapping Patterns.
...configure the transform server (host, port, HTTPS, CORS) -- see Server Configuration.
...fix a browser certificate error when setting up a transform server -- see HTTPS, Certificates, and Browser Trust.
...put the transform server behind a reverse proxy, gateway, or load balancer -- see Deploying Behind a Reverse Proxy.
...add authentication (API key, OAuth, bearer token) to a transform -- see Authentication and OAuth Authentication.
...handle paginated API results -- see Pagination.
...publish an integration to the Maltego Hub -- see Hub Items and Transform Sets.
...make a configured SDK data source available in Maltego Graph Browser -- see Maltego Transforms SDK product setup.
...migrate an existing Maltego TRX project to this SDK -- see Moving from TRX to the current SDK.
...look up a specific class or method (MaltegoGraph, MaltegoEntity, MaltegoContext, etc.) -- see SDK API Reference.

Page map

Article	One-line description
Installing and Setting Up the SDK	Install the SDK, generate a starter project, run the dev server.
Using AI Agent Skills with the SDK	Install/use the SDK's provider-agnostic AI agent skills.
Writing Your First Transform (Quickstart)	`@register_transform`, typed input entities, returning a graph.
Standard Entities Overview	Available standard entity classes and import patterns.
Composed Entities	Composing entities from multiple standard entities.
Pydantic Mapping Patterns	Mapping Pydantic models to Maltego entities and back.
Entity Features (Overlays, Links, Notes)	Entity properties, overlays, links, display configuration.
Transform Settings	Defining and reading transform settings.
Server Configuration	Host/port/HTTPS/CORS config, discovery endpoints, health checks.
HTTPS, Certificates, and Browser Trust	Certificate trust checklist for browser-based transform setup.
Deploying Behind a Reverse Proxy	Proxy/gateway config, TLS modes, and the request processing chain.
Transform Middlewares	Request/response hooks, custom middleware, where they sit in the request chain relative to authentication.
Logging	Structured logging configuration for transforms.
Error Handling	Exceptions and UI error messages in transforms.
Interactive Prompts	Prompt templates for mid-execution user input.
Input Constraints	Validating entity input before a transform runs.
Hub Items	Metadata, icons, and pricing for Maltego Hub distribution.
Authentication	API key, OAuth, and bearer token auth patterns.
OAuth Authentication	Implementing OAuth authentication in transforms.
Pagination	Cursor-based and offset-based pagination patterns.
Transform Sets	Grouping transforms for Maltego Hub distribution.
Maltego Transforms SDK product setup	Making a configured SDK data source available in Maltego Graph Browser.
Machines (SDK)	Defining and using Maltego machines with the SDK.
Execution Runner	Async execution, concurrency, and transform lifecycle.
Integration Client (HTTP Calls)	Async HTTP client for transforms: retries, auth injection.
SDK API Reference	Class/method reference: MaltegoGraph, MaltegoEntity, MaltegoContext, MaltegoLink, TransformSetting, TransformMiddleware, MaltegoHubItem.
SDK Examples	Worked examples: entity lookups, enrichment, multi-entity output.
Moving from TRX to the current SDK	Migrating from maltego-trx: class patterns, request/response idioms.

Important caveats

These are docs for the current maltego-transforms SDK only. They do not cover the TRX/classic protocol, iTDS, or Transform Distribution Server (TDS) administration -- see TRX Transform Library Guide, What is a Transform Distribution Server (TDS)?, and Writing Transforms in this category for that material.
Legacy TRX/iTDS content in this Freshdesk category (Maltego TRX, Canari3, and other third-party libraries) remains valid for existing deployments and is not being deprecated by this SDK's arrival.
Standard entities are provided by a separate companion package, maltego-transforms-std-entities, installed independently; it is not bundled automatically with maltego-transforms.
Authentication, server host/port, and discovery-endpoint behavior are configured per project via MaltegoServerSettings and related settings objects -- see Server Configuration and Authentication. There is no implicit/default auth; unauthenticated transform servers are the default and must be explicitly secured if required.
To let Maltego Graph Browser discover and run transforms directly against a local transform server, CORS must be configured -- see the CORS section of Server Configuration.