MagicTree Documentation: Node Types

< MagicTree XML Format | Table of Contents | Semantic Structure >

MagicTree supports different sorts of nodes that can be used to represent various kinds of objects and data.

Branch Nodes

Two Branch nodes

A branch node contains one string value, for example "magictree". The value of the branch node is represented as tag name in XML, so there are certain limitations on what characters the branch node value can contain. For example, they cannot contain spaces. Branch nodes are generally used in MagicTree to create tree structure. For example, the MagicTree root node and the nodes for test data, repository and tasks are all branch nodes. Branch nodes are not very usefull for storing actuall data due to the limitations on their values.

Branch nodes are represented by MrBranchObject class.

In XML a branch node with value "nodevalue" is represented as follows:

<nodevalue id="999" status="none" class="MtBranchObject" />

When branch nodes are compared for equality during merge only the node values are compared. Two branch nodes are equal if their values are equal.

Branch nodes, when represented in XML, should not have any text. If a branch node is read from XML representation any text is ignored by MagicTree.

During merge no special processing is done for branch nodes.

Simple Nodes

Simple nodes are the most commonly used for storing actual data. A simple node representa a name-value pair. Simple nodes are used, for example, to represent hosts, ports, services, etc.

The host is represented by a Simple node (with type "host" and name "127.0.0.1")

Simple nodes are represented by MtSimpleObject class.

In XML a simple node is represented as follows:

<host id="999" status="none">127.0.0.1</host>

Simple nodes represented in XML may have "class" attribute with value set to "MtSimpleObject". If an XML element does not have a "class" attribute, it is treated as simple node.

When simple nodes are loaded from XML the text data is trimmed (the whitespace in the beginning and the end of the text is removed).

When simple nodes are compared for equality during merge, the types and the names of the nodes are compared. Two simple ndoes are equal if they have the same type and the same name. Names are trimmed of whitespace.

During merge no special processing is done for simple nodes.

Text Nodes

Text nodes are useful for representing longer textual data that does not fit nicely in simple nodes. A text node has a title and a text. Currently text nodes do not support formatted text. Both the title and the text can contain arbitrary characters.

A text node in the tree on the left and its text content in the tab on the right

Text nodes are represented by MtTextObject class.

In XML a text node is represented as follows:

<text id="999" status="none" class="MtTextNode" title="Executive Summary">This report is about something.</text>

Text nodes always have "text" as their XML tag. The "title" attribute is used to store the title.

When compared for equality during merge, only titles are compared, not the text. If the two text objects have the same title, but different text, the merged object has the text of the object in the merging tree.

At the moment, when two text nodes are merged, the text of the node in the second tree is copied to the resulting object. In the future, we will probably implement some representation that shows the original text and any modifications in the merged node.

Data Nodes

Data nodes are used for storing arbitrary (possibly large) data. Two specialized kinds of data nodes - Image nodes and XML Data nodes are used for storing and displaying images and XML data respectively.

Data nodes look like this in the tree:

Data node

Currently MagicTree GUI does not provide a way to attach a file to data node.

Data nodes are represented by MtDataObject class.

In XML a data node is represented as follows:

<data id="999" status="none" class="MtDataObject" filename="packetdump.bin">Packet dump</data>

The actual data is stored outside of the XML file in a subdirectory inside the project file (see Project File Structure)

During merge data objects are compared for equality based on their titles and data. If two data objects have equal titles and bit-by-bit equal data files, they are considered equal.

No special procesing is performed for text nodes during merge.

XML Data Nodes

XML Data nodes are similar to generic data nodes, except that the attached file contains XML data in a format understood by MagicTree. XML Data nodes are most commonly used to store the output of tasks that generate XML. The XML data stored in an XML Data node may be merged into the tree.

XML data nodes are represented by MtXmlDataObject class.

Image Nodes

Image nodes are similar to generic Data nodes except that the attahed file contains an image. Images from Image nodes may be easily included in generated reports. Image nodes are intended for storing screenshots and other image data that is somehow relevant to the current project.

A image node in the tree on the left and its content in the tab on the right

Cross-References

Cross-references are a special kind of node. Cross-reference node points to another node in the tree. Cross-references are useful for linking one branch of the tree with some other branch. For example, you may want to list affected hosts under some finding node in the "report" branch. Instead of creating a new node for each affected host under the "finding" node, you can create cross-references and and point them to the host nodes under the "testdata" branch.

Cross-reference pointing to a host node

Cross-references can not have child nodes.

To link a cross-reference to a node, right click on the cross-reference node, select "Link to object" from the context menu and then select the object you want to link the cross-reference to. To follow a cross-reference Ctrl+click it.

Cross-references are represented by MtXrefObject class.

In XML data a cross-reference is represented as follows:

<xref id="7" status="none" class="MtXrefObject" href="#2"/>

The "xref" attribute contains the id of the node that the cross-reference links to.

During merge, cross-references are compared for equality based on the objects they point to. For two cross-references to be equal, the objects they point to have to be equal and all ancestors of the nodes they point to up to the tree root have to be equal. The reason behind it is that a cross-reference pointing to port 80 of host 127.0.0.1 is not the same a cross-reference pointing to port 80 of host 192.168.1.1. Therefore to establish the equality, we have to compare all ancestor nodes as well.

When two cross-references are merged the resulting cross-reference will point to the target in the first tree (if the target hasa already been merged). If the target has not yet been merged, the cross-reference will point to the node in the second tree. When the target node is merged, the cross-reference pointing to it is updated to point to the merged node in the first tree.

Overview Nodes

Overview nodes are mainly designed for handling findings and recommendations. Usually in a penetration test report you will have a section listing all important findings of the test and the recommendations on how to fix them. With MagicTree you can create nodes for individual findings and link them to affected hosts. The tree structure can look like this:

A tree containing a finding represented by Overview node

An Overview node has a name and a value, similar to a Simple node. The main difference is how it is displayed. The detailed view panel on the right shows an overview of all Text nodes under the selected Overview node.

Overview nodes are represented by MtOverviewObject.

In XML Overview nodes are represented as follows:

<finding id="999" status="none">Oh the world must be coming to an end</host>

During merge, the Overview nodes are compared for equality similar to the Simple nodes - both the name and the value are compared.

No special processing is performed while merging Overview nodes.

Special Kinds of Nodes

MagicTree creates tree nodes for queries, methods and tasks. They are created automatically as necessary when a task is executed. These nodes can not be created manually and normally there is no need to do that. Queries and methods are stored in the "repo" branch. Tasks are stored in the "tasks" branch:

Queries, Methods and Tasks

Query Nodes

During merge queries are compared for equality based on field names, expressions and flags. The queries that have exactly the same fields are considered equal.

No special processing is performed for query nodes during merge.

Method Nodes

During merge methods are compared for equality similar to cross-references. A method is actually a cross-reference to query it uses (and MtMethodObject is a subclass of MtXrefObject). In addition to that the commands of the two methods are compared for literal equality.

No special processing is performed for method nodes during merge, except updating the cross-reference same as for the cross-reference nodes.

Task Nodes

Task objects are assigned UUIDs at the moment of creation and compared for equality based on the UUID. This (nearly) guarantees that two tasks started by different people (even if the command line and all other attributes are the same) are not equal to each other.

Since only UUIDs are compared for equality, during merge two equal tasks can have different data. This can happen if, for example, a copy of the project file was made when a task was scheduled or still running. When the project file is opened on the computer where the task was originally started, the task will be picked up by the MagicTree process monitor and the task will eventually complete. When the project file is opened on a different computer or by different user, the process monitor will fail to pick up the task and it will have an error state. When the two project files are subsequently merged, MagicTree takes care to preserve the data from the task node that is most likely to contain relevant data. To accomplish this, when merging two equal task nodes, MagicTree will retain the data from the task with highest state that is not an error state. The task states have the following order (from lowest to highest):

NEW (not an error) - the task is submitted for execution, the task controller may be busy starting it
START EXCEPTION (error) - the task controller has failed to start the task
STARTED(not an error) - the task is running, the task controller may be monitoring it
MONITOR EXCEPTION (error) - the task controller has failed to monitor the progress of the task
EXITED (not an error) - the task has exited, the task controller is probably busy picking up its results
PICKUP EXCEPTION (error) - the task controller has failed to pick up the results of the task
FINISHED (not an error) - the task has finished its execution and its results are available