iTDS Module


Using the iTDS

Transform Host Server

Now that you have your iTDS setup and understand how the architecture sits together you probably want to add your first custom transform. For this you need to set up a server to host your transform code that can also access the data that you want to integrate into Maltego. There are a few standard iTDS transform libraries available for writing iTDS transform in different programming languages however the most supported and recommended one to use is the TRX Python library.

TRX Python library page explains how to set up a server to host Python transforms that use the TRX framework.

Once your transform host server has been setup you can continue to the iTDS Module section below.

iTDS Module

You are now ready navigate to the iTDS module interface where you can add a transform.

The image above shows the link to the iTDS module from the server's start page. The image below shows the home page for the iTDS module.

TDSFrontpage.png

From the iTDS module interface you can manage the following for your iTDS:

  • Transforms - Manage custom Maltego transforms as well as their settings and properties.
  • Seeds - Manage the seeds on the iTDS, specifically their names, URLs and which transforms and configurations they hold.
  • Transform Settings - Manage the transform settings available to the various transforms.
  • OAuth Settings - Manage the OAuth settings available to various transforms.
  • Entity Management - Manage custom entities available to transforms.
  • Paired Configurations - Manage the transform configurations sent to Maltego clients when a seed is installed. Paired configurations can include custom entities, transform sets, machines and managed services.
  • Backups - Perform a backup to restore these transforms and settings for your iTDS.

Your First Transform

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. We will first look at building a really simple iTDS transform.

Requirements:

  1. You have your iTDS setup and running.
  2. You have your transform host server setup.

Copy the following script to your Transform Host's Webserver:

 

header("content-type:text/xml");
echo "<MaltegoMessage>
<MaltegoTransformResponseMessage>
<Entities>
        <Entity Type="maltego.Phrase">
                <Value>Hello World</Value>
                <Weight>100</Weight>
        </Entity>
</Entities>
<UIMessages>
</UIMessages>
</MaltegoTransformResponseMessage>
</MaltegoMessage>";
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):

 

exampleOutput.png

 

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

Setting up a Seed on the iTDS

A seed is really just a URL that points to a group of transforms. It’s this URL that Maltego will use to load all of the transforms contained in the seed into its internal configuration. Thus, the first step we want to do is create a new seed (container). Once we’ve done that we’ll create a new transform and put the transform inside that seed.

Click on ‘Seeds’. You’ll see a list of seeds (if you have any). Click on the ‘Add Seed’ button’. You need to give a seed name, a seed URL and select which transforms you want to add into the 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!

AddSeedScreen.png

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: https://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':

addTransform.png

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

successfullyAdded.png

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:

copyseed.png

Setup in the Maltego Client

Next we go to the Maltego client. Seeds are added to your Maltego client from the Transform Hub by clicking on the first item which is a plus (+) button as shown below:

After clicking the plus (+) button, the Add Transform Seed window will open. Here you can add your seed URL as well as other details about the transform seed. Such as the hub item's name and its display name.

After entering your transform seed URL and the other fields for the seed you can click "OK" and then "Install". The transform from this seed will then be installed to your Maltego client and you should see a summary page describing what was installed.

click_install.png

The following steps are what happens when the Maltego client installs transforms from a seed url in the transform hub:

  1. seed is added to the Maltego client that points to an XML file like the one listed above.
  2. The Maltego client then browses to each of the TransformApplication URL and appends the text "?Command=_TRANSFORMS" which tells that server to list all the transforms available for that seed
  3. Each of these Transforms are then registered within the client for that particular seed. This includes the display name (listed in the context menu) as well as transform name which is used when running a transform. Transforms can also have additional settings such as transform settings and OAuth configurations.

Once installed you will be able to run the transform included in this seed when you open a new Maltego graph. It will be found under the hub item name in the context menu.

If you want to share this transform with anyone you can simply give them the URL and guide them through the installation process in the same way as which you did. And – if you change the code on the server the change will transparently happen on all clients (as the transform runs on the server). You can now add more transforms to the seed. Maltego periodically checks for new transforms in the seeds – which mean you never need to touch the client side anymore. Joy!

Adding the Sample DNS2IP Transform

If you are using the TRX framework on your transform host, you will find that a sample transform is included in the framework called DNS2IP. The transform script is found in the DNSTRANSFORM.py file. This section will add this transform on your iTDS interface. This can be done by clicking 'Add Transform' under the 'Transform' section just as you did in the previous example.

The table below shows the fields that can be filled in on the transform page to add the DNS2IP transform to your iTDS:

Change the fields as follows:  

Transform name:

DNS2IP

Transform URL:

http://<Your_DevServer_Here>:9001/DNS2IP
Input Entity: maltego.DNSName (from the dropdown)
Disclaimer: Leave empty unless you feel like putting something there
Description: My first sample transform (or get creative)
Debug: Checked

Transform settings:

Leave as is – we’ll get to this later
Seeds: Click on ‘ExampleSeed’ to highlight.

Click 'Add Transform' and if everything worked you should see Successfully Inserted DNS2IP':

 

Now the DNS2IP transform will be added to your transform seed 'ExampleSeed' that was added in the previous section. You will just need to re-install the transform hub item in your Maltego client to ensure that the Maltego client is aware of the new transform that was added to your seed.

The next sub sections explains the step-by-step process of what happens when the DNS2IP is run in your Maltego client.

Under the hood - when running a iTDS Transform

Let’s see what really happens here when the transform is run. These are the steps:

  1. After you installed the hub item from your iTDS server, Maltego knows that there’s an additional transform called DNS2IP available on the entity type Maltego.DNSName.

  2. When you right click on a DNS Name it makes this transform visible

  3. It sends the transform request to the iTDS server

  4. The iTDS server knows that the transform really lives on http://<Your_DevServer_Here>:9001/DNS2IP

  5. The iTDS makes a connection to port 9001 on the dev server and sends some XML in a POST

  6. The Apache WSGI configuration on the dev server sends all requests on port 9001 to a file located in /var/www/TRX/TRX.wsgi

  7. TRX.wsgi sees that it’s destined for /DNS2IP and routes it to the right piece of code

  8. The Maltego Python library interprets the XML to something that’s easy to work with in Python and passes it along

  9. A DNS lookup is done

  10. The reply is wrapped back into XML by the library and the data flows back the way it came in.

Seems like a mouthful. The actual transform code is quite simple and looks like this:

def trx_DNS2IP(m):
  TRX = MaltegoTransform() DNSName=None 
  try:
      DNSName = socket.gethostbyname(m.Value) 
      TRX.addEntity("maltego.IPv4Address",DNSName) 
  except socket.error as msg:
      TRX.addUIMessage("Problem:"+str(msg),UIM_PARTIAL)
      return TRX.returnOutput()

Hardly rocket science.

For detailed documentation on the use of the TRX Transform library have a look at its page. More detailed transform examples are also covered in the page and the iTDS Transform Examples.

Continue to the Additional Functionality page.



© Copyright 2017, Paterva PTY Limited