Viewlets


Overview

A viewlet is a small piece of Javascript code that will determine how a graph will be rendered. It never used to be documented as it was an experimental feature – as such it’s really only developer friendly and not easily exposed to end users. Maltego ships with a couple of pre-configured viewlets that can be selected from the left sidebar of a graph under the View heading:

standard_viewlets.png

In effect viewlets splits the view of the graph from the information that’s contained in the graph. 

A viewlet has the ability to set two aspects of nodes:

  • The colour of a ball.
  • The size of a ball.

A viewlet has to have the following:

  • A name.
  • A binding (to either the ball size or the ball colour).

The ball colour is specified as a hash ‘#’ and RRGGBB in hexadecimal. For instance #FF0000 will be solid red and #00FF00 will be solid green.
The ball size is number between 50 and 500. Should the number be bigger or smaller than this range the size will be clipped at the limits.

Adding a Viewlet

Let’s look at creating a new viewlet. You can open the View Manager in the Maltego client by clicking the View tab, clicking the manage view drop-down and then clicking the Manage View button:

open_view_manager.png

Next we’ll click on "New Viewlet"

create_new_viewlet.png

Give it a name and you’ll now see the viewlet appear in the list, ready to be edited. Click on the [+] button to add a binding for this viewlet:



We can now select which binding we want – the ball size or the entity (ball) colour.



For now, let’s assume we want to select the ball size. We want all the balls to have the same size – the maximum size (500). So we just have to return a constant – 500. We can test the viewlet by clicking on the ‘Test’ button:



To see what this looks like on the graph we click on OK. We can now decide how our viewlet should look like inside Maltego. We can choose that it’s always displayed in the toolbar (like the preset viewlets) or just in the drop-down menu… or both. This behaviour is configured by checking or unchecking the checkboxes:



We’ve decided to make the viewlet only visible in the drop-down menu and not in the toolbar. If used in the toolbar it is useful to give the viewlet a specific icon so that it is easy found. When we click on okay to save the viewlet configuration section the current viewlet is applied and available in the dropdown:



This viewlet is not very useful. Let’s look at a few more useful examples. When any of the transforms that uses search engines returns entities it also assigns as weight to the entity. We can use the following viewlet to shade the color of the returned entities according to their weight:

var maxColor = 200;
var minColor = 0;
var maxWeight = 100;
var minWeight = 50;
var color = maxColor * (maxWeight-weight) /(maxWeight-minWeight) ;
var rg = color.toString(16);
"#"+rg+rg+"ff";

To edit our current viewlet we click on the three dots […] next to the name:



Remember to change the binding at the top to ‘Entity Colour’ – as this is what we’ll be returning in this section! Using this viewlet we get:



We can also decide to make the ball size a function of the weight of the node. In that case we change the binding back to the ball size. We know that the weight of a node is always between 1-100 and so we can simply change the script to be:

weight*5

The resultant graph looks as follows:



By now you can probably figure out the ‘weight’ is a variable that’s available to the developer of viewlets. There are many other functions and variables available – these are listed in the viewlet editor itself:



Examples of viewlets

Colour by gender (assuming that your entities contains a property called ‘gender’ – binding is colour)

if (getPropertyValue("gender") == "female") {
    "#B40000";
}
else if (getPropertyValue("gender") == "male") {
    "#008040";
}

Printing property names (useful for debugging)

var names="";
for(i=0;i<propertyKeys.length;i++) {
    names+=propertyKeys[i];
    names+=", ";
}
names.substr(0, names.length-2);

Accessing the Rest of the Graph – Advanced Viewlets

The [entity] type has the following methods:

  • getWeight()
  • getValue()
  • getPropertyValue(name)
  • getType()
  • getBookmark()
  • getNotes()

And the following members:

  • incoming()
  • outgoing()
  • links()

The [link] type has the following methods:

  • getValue()
  • getPropertyValue(name)

It has these members:

  • source()
  • target()

These methods and members can be used to access other parts of the graph. Consider the following viewlet that sizes balls according to the grandparent’s weight (if the type is a person). Binding is size:

if (isType("maltego.Person")) {
    var cumulativeWeight = 0;
    for(i=0;i<entity.incoming().length;i++) {    
        var parent = entity.incoming()[i].source();
        for(j=0;j<parent.incoming().length;j++) {
            var grandparent = parent.incoming()[j].source();
            cumulativeWeight+=grandparent.getWeight();
        }
    }
    cumulativeWeight+weight;
}
else {
    50;
}

There are a couple of things to keep in mind when using viewlets. The viewlet code runs in the UI thread – so when you have infinite loops, circular references or really complex calculations your UI will slow down, or even crash Maltego. Also – viewlets can be very dangerous – it does not run in a Javascript sandbox and malicious viewlets can do harm to host. It is therefore recommended that you visually inspect the viewlet code before running it.

Viewlets can be distributed with configuration export and import:

Continue to the Machines (transform macros) page.



© Copyright 2017, Paterva PTY Limited