Installing and Setting Up the SDK

This guide outlines the steps to set up and run a Maltego Transforms project. It is centered on the project generated by maltego-transforms start, because that generated project is the main public example surface referenced throughout the rest of this documentation set.

1. Environment Setup

Create and activate a Python virtual environment to isolate dependencies.

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

2. Installation

Install the maltego-transforms package from PyPI.

# Install the latest version
pip install maltego-transforms

# Or install a specific version (we always encourage using the latest
# and pinning your versions during deployment)
pip install maltego-transforms==x.y.z

You can also install the standard entities package, which includes Casefile entities:

pip install maltego-transforms-std-entities

3. Project Initialization

Initialize a new project (e.g., named example).

maltego-transforms start example

To include project-local agent skills for SDK authoring, TRX migration, direct server discovery, docs lookup, and testing:

maltego-transforms start example --with-skills

This writes skills to .agents/skills and adds local bootstrap files so agents started in the generated project can find .agents/skills/maltego-transform-skill-index/SKILL.md first. To install the same skills into a provider-agnostic global skills directory instead, use --skills-scope global; the default scope for --with-skills is local. See the Using AI Agent Skills with the SDK article for the recommended agent workflow.

Template Project Tour

The generated project is meant to run immediately and to act as a reference implementation while you onboard:

• project.py imports the transform modules, defines MaltegoServerSettings, and starts the server.
• transforms/quickstart_example.py shows the basic transform and custom entity patterns.
• transforms/entity_features_example.py demonstrates overlays, display fields, notes, link styling, and related entity metadata.
• transforms/pagination_example.py shows paginated API access and HTML helpers.
• transforms/input_constraints_example.py, transforms/logging_example.py, transforms/prompts_example.py, and transforms/error_handling_example.py cover the corresponding runtime features.
• transforms/middleware_example.py shows how to decouple authorization, auditing, and logging from transform business logic using TransformMiddleware, and where that sits relative to authentication --see Transform Middlewares.
• project.py starts with HTTP for a local server check. Configure your own certificate before connecting the project to a Maltego client.

First edits to make

After generating the project, the first things you will usually change are:

• server_name, ns, and author in project.py
• which example modules stay imported in project.py
• the placeholder/example transforms inside transforms/
• the HTTP settings and locally generated certificate before adding the server to Maltego Graph Desktop or Maltego Graph Browser

4. Configure HTTPS for a Maltego Client

The generated project starts over HTTP by design. Before adding the server to Maltego Graph Desktop or Maltego Graph Browser, configure HTTPS and trust the certificate. The default HTTP seed is useful only for local server checks; it is not the first client setup path.

For local development, you can generate a self-signed certificate using OpenSSL.

Step 1: Create a configuration file (cert.cnf)

[req]
default_bits = 2048
prompt = no
distinguished_name = dn

[dn]
C = DE
ST = Bavaria
L = Munich
O = MyCompany
OU = Development
CN = localhost

[req_ext]
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
IP.1 = 127.0.0.1

Step 2: Generate the certificate and key

mkdir -p .local

openssl req -x509 -newkey rsa:4096 \
    -keyout .local/server.key \
    -out .local/server.crt \
    -days 365 \
    -nodes \
    -config cert.cnf \
    -extensions req_ext

This creates:

• .local/server.key - Private key (keep this secret)
• .local/server.crt - Certificate (shared with clients)

Explanation of options:

• -x509: Generate a self-signed certificate
• -nodes: Skip password protection for the private key
• -days 365: Valid for 1 year
• -newkey rsa:4096: Create a new 4096-bit RSA key

Step 3: Configure your server to use the certificate

from maltego.server import MaltegoServerSettings, ServerHTTPSettings, run_server

server_settings = MaltegoServerSettings(
    server_name="My Transform Server",
    ns="mycompany",
    author="dev@mycompany.com",
    http_settings=ServerHTTPSettings(
        http_addr="127.0.0.1",
        http_port=3000,
        protocol="https",
        cert_key=".local/server.key",
        cert_file=".local/server.crt",
    ),
)

if __name__ == "__main__":
    run_server(settings=server_settings)

Note: The certificate's Common Name (CN) and Subject Alternative Names (SANs) must match the hostname you connect to. For local development, localhost and 127.0.0.1 are configured in the example above.

For production deployments, use certificates from a trusted Certificate Authority (CA) like Let's Encrypt. See the Server Configuration article for more SSL configuration options.

5. Run the Project

Navigate into the project directory, install dependencies, and run the project server.

cd example

# Install project dependencies
pip install -r requirements.txt

# Run the project
python3 project.py

After configuring HTTPS, the transform server is available at https://127.0.0.1:3000/seed. Trust the certificate in the relevant client before adding this seed URL. If you have not yet configured HTTPS, use http://127.0.0.1:3000/seed only to confirm that the local server starts.