Local Transforms

Local transforms are pieces of code that run on the same machine which the client application is. These are very useful for integrating in machine specific tasks (such as running an application that's locally on the machine- like nmap OR a task that is dependent on a setup on the machine such as accessing data over a VPN). These transforms can be written in any language (yes, *any* language) and merely rely on output to be sent via STDOUT (think a command line application).
 

How Local Transforms Work

Local transforms are called from the command line and interacted with via STDIN and STDOUT. When you right click on an entity and execute a transform it sends through the following to the executable (your transform):

  • Entity Value (what is displayed on the graph) -- this is the first argument.
  • Entity Fields (the fields contained in the entity), these are separated by #'s and each field is separated - name and value by an '=' sign.

For example, if you had a person entity of 'Andrew MacPherson' (as displayed on the graph), it would have the fields:
 

Display Name (in details) Variable Name Value
Full Name person.fullname Andrew MacPherson
First Names person.firstnames Andrew
Surname person.lastname MacPherson

(These fields can all be found by clicking on Manage entities under the Manage tab, finding the entity in question and click on the (...) next to its name and navigating to the Additional Properties tab)

Execution


The execution of a transform on the above entity would be as follows (if I was running a python script called 'personTransform.py' in /home/andrew/localTransforms):

andrew@devBox3: /home/andrew/localTransforms/# /usr/bin/python personTransform.py "Andrew MacPherson" person.fullname=Andrew MacPherson#person.firstnames=Andrew#person.lastname=MacPherson

At a minimum a transform needs to simply return valid XML via STDOUT, something like:

<maltegomessage>
<maltegotransformresponsemessage>
	<entities>
		<entity type="maltego.Phrase">
			<value>Hello Transform World</value>
		</entity>
	</entities>
</maltegotransformresponsemessage>
</maltegomessage>

In the above you can see that we are returning just a single entity which is a Phrase and has a value of 'Hello Transform World'. If I had specified it to run on a domain and executed it I would have got the following within the client:

hello_transform.PNG
 

Local transforms are really *that* simple, just return valid XML and you can do anything with them from running external applications to integrating with APIs.

Local Transform Registration

Adding a new local transform should be a relatively painless process and you shouldn't need to leave the Maltego client for the duration of the process. This  describes how local transforms are added in the Maltego client.

Overview

One of the con's of local transforms is that they are not very easy to distribute. However there are a number of different ways to handle the distribution. 

Exporting Configuration

If you are exporting local transforms between boxes that can be configured in the same manner for local transforms (paths and environments) then the simplest way to distribute local transforms is to export your configuration. You can read about exporting your client configuration on our Maltego user guide. From the export wizard you can simply select only the 'Local Transforms' which will export the local transform configuration. Next you can copy the required files for the transforms to the same paths on the second machine and the transforms should work. 
 

Manually Adding

If you are moving between different operating systems you can either import as above and then in the transform manager manually change each of the transforms settings or you can manually recreate each of the transforms.

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

In this section we will write a local transform, this is something that will run locally on the same machine that Maltego runs on. We recommend that you take a look at  to see what the differences are between these and TDS transforms.

Your first Local Transform

Requirements:

  • Programming Environment - This can be any locally executable program or scripting language, for these examples we will be using PHP and Python
  • Maltego Client - You should already have downloaded this and have it installed.

Setup your environment

You will need to pick a language to develop your transform in, something that you are fairly comfortable with, we recommend PHP or Python as we have examples for these languages. For this quick tutorial I will use a simple PHP/Python script without any use of the libraries.

The next section will assume you are already comfortable running Python and PHP code from a console.

Copy the following script to a local directory:

PHP:

echo '<maltegomessage>
<maltegotransformresponsemessage>
<entities>
<entity type="maltego.Phrase">
<value>Hello World</value>
<weight>100</weight>
</entity>
</entities>
<uimessages>
</uimessages>
</maltegotransformresponsemessage>
</maltegomessage>
';

Python:

#!/usr/bin/python
print """<maltegomessage>
<maltegotransformresponsemessage>
<entities>
<entity type="maltego.Phrase">
<value>Hello World</value>
<weight>100</weight>
</entity>
</entities>
<uimessages>
</uimessages>
</maltegotransformresponsemessage>
</maltegomessage>
"""

After saving these files you should be able to execute them from a shell / console / terminal in a similar way to the following:

 

 

Setup in the Maltego Client

Now that you have your first super basic local transform script saved, you will need to add it to your Maltego client. Instructions on doing so can be found in the Maltego User Guide.

Where Next?

To continue learning about building your own Local transforms, click the links below to find more transform code examples for both PHP and for Python.


© Copyright 2017, Paterva PTY Limited