Building your own transforms

Don't panic.

The idea of writing transforms for Maltego may seem daunting but really its a simple process and once you have written your first transform it becomes an incredibly simple process.

Initially you will need to decide whether you would like to use TDS or Local tansforms, you can view the differences on our "Differences between local and TDS transforms" page. Essentially it should come down to the type of transform you are building. The pros of the TDS transforms almost always outweigh the local transforms unless there is a particular reason that you need code executed on the local machine. This could be something such as needing the local connection to query something internal or analysing files stored locally on the machine. Using TDS transforms however means its a lot easier to share and modify transforms as well as not needing any of the headache of having to setup the particular environment on every machine that you wish to have use the transforms.

We will first look at building a really simple TDS transform. You can view some more extensive TDS transform snippets at the TDS code snippets page.

Your first TDS Transform

Requirements

TDS Login - quickly and easily register on the Public TDS.
Internet facing webserver - This will be the machine that does the actual work.

Setup your environment

You will need to pick a language to develop your transform in, something that you are fairly comfortable with, we would definitely recommend PHP or Python as these already have libraries available for them. For this quick tutorial you can use either PHP or Python without any use of the libraries.

For the PHP section we will assume you are using a LAMP stack and have a basic understanding of PHP. For the Python section we recommend that you read the guide and install the TRX libraries and understand how the code flow works for that library.

Copy the following script to your webserver

<?php
header("content-type:text/xml");
echo "


        
                Hello World
                100
        




";

from Maltego import *
def trx_helloWorld(m):
	# construct a return vessel
	TRX = MaltegoTransform()
	# Add entity
	Ent = TRX.addEntity('maltego.Phrase', "Hello World")
	# return the XML to the TDS server
	return TRX.returnOutput()


Save the file as something on your server that is accessible on the Internet. You can test this by browsing to the script where you should see the following (please note for the Python you may need to also specify the port of the listener and will only get back a blank page):


If you can see that then your server side is all setup, now we just need to configure the TDS!

Setup the TDS

Concepts
The TDS setup is rather simple, there are a few key concepts to go over briefly before doing this step:

  • Seeds - Seeds should be thought of as the index to a book or even a bit.ly link, they are used by Maltego to tell the application where to find the transforms available. The interface of the TDS allows you to configure these seeds and customise which transforms are contained in which seeds. The seeds are then what is fed into Maltego so that the tool can discover (It is referred to as the discovery process within Maltego).

  • Transforms - Transforms within the TDS interface are pointers that tell the TDS where a particular script lives (on the Internet) and this script is then called when a Transform is executed.

Setup
This guide will not cover all of the options for creating a transform but merely enough to get you started on creating your first transform. Initially you will need to register on the public TDS server. After you have registered and logged in you will be greeted with an interface that looks like the following:



The first step is to create a seed for our sample transform. You can do this by selecting the 'Seeds' option on the frontpage and then clicking the 'Add Seed' button at the bottom left of the page. From here you will see a form that allows you to configure your seed.

For this basic transform setup we will just configure a Seed Name and Seed URL:
  • Seed Name - This is the human readable name that will describe which transforms are contained within a seed. We can use something like 'ExampleSeed'
  • Seed URL - This is the URL that will be fed into Maltego to configure the client. This should be something unique (you can use the default or set your own), note that this should not be easily guessed as then someone else could potentially discover your transforms!



The second section that you need to configure is the transform itself. You can get to this screen by selecting "Transforms" from the home screen and then selecting "Add Transform" at the bottom left of the screen. For our transform we will simply be configuring the Transform Name,Transform UI Display,Transform URL,Input Entity and seeds:
  • Transform Name - This is the core name of the transform, something that programmatically describes it, something like 'ExampleTransformHelloWorld'.
  • Transform UI Display - This is what is displayed to the end user/analyst within Maltego, you might use something like 'Hello World Example Transform'.
  • Transform URL - The location of the transform, this is what we first used when configuring our transform eg like http://www.domain.com/SampleTransform/helloworld.php.
  • Input Entity - This is the entity that this transform will be run on, we recommend you use something simple from the core such as Maltego.Domain.
  • Seeds - The seed(s) that this transform belongs to, for this example we will use only the first seed we created 'ExampleSeed'.

Your output should thus look like the following before clicking Add Transform:



After clicking add you should see a message indicating the transform was successfully added:



The last step is to copy the Seed URL that we will use in the next section. To get to this screen again you can simply navigate to the home screen and click on the 'seeds' link. From this screen you can either click the 'Copy to Clipboard...' button or manually copy the link in the 'URL' column of the table:



Setup Maltego

This is the final step for creating our transform. First you will need to open Maltego (obviously!). Once it is open from the 'Manage' tab at the top of the screen you can select the dropdown under 'Discover Transforms' and select 'Discover Transforms (Advanced)':



You will now be greeted with the wizard where Maltego will ask you for the Name and URL:
  • Name - The Name used during the discovery process for you to give a human readable name for your Seed.
  • URL - The Seed URL that was copied within the last step of the previous section

    

From here you can simply click next, next, finished as described by the following pictures:

              

Well done! You have successfully added your first TDS transform!

From here you can simply drag in the entity you initially selected when adding the transform on the TDS (in our example it is a Domain). You will then see the option when right clicking and selecting all transforms and then clicking on the name you gave to the transform (in our example it is 'Hello World Example Transform'). The two pictures below also describe this process: