< Project File Structure | Node Types >
The native data storage format for MagicTree is XML.
MagicTree XML has a root element called "magictree" with one required attribute - "class" with value "MtBranchObject". Thus a minimal MagicTree XML file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<magictree class="MtBranchObject"/>
Root element may have any number of child elements. The syntax of those is described in Node Types
The semantics and the conventions for representing of various real-life objects common in penetration testing is described in Semantic Structure
All elements may have an "id" attribute with numeric value and a "status" attribute with currently supported values of "none", "todo", "ignore" and "interesting". Other allowed values may be added in the future. Both attributes are optional.
If "status" attribute is not present, it is assumed to be "status="none'"
When loading an XML file MagicTree will assign unique numeric ids to all nodes. If "id" attribute is present, MagicTree will try to preserve it, unless it results in duplicated ids. Ids are used by cross-references to link to the target object, by methods to link to queries and by tasks to link to methods, input and output objects. Therefore ids are vital for project file integrity.
If you are generating an XML document that will be consumed by MagicTree we recommend omitting "id" attributes and letting MagicTree do the numbering. Of course, if your document contains cross-references, methods, or tasks, then ids are necessary and have to be unique for each element. If you have to have ids in your document, assigning them sequentially, starting from 0 for "magictree" element itself, is the recommended approach.
When MagicTree loads a MagicTree XML document, the sibling nodes that are equal are always merged together. Sometimes that is not what you want. For example, multiple XSS findings are separate entities and really should not be merged together. To solve this problem we have introduced a special attribute "mergeID". Its value can be an arbitrary string. When two nodes are compared for equality for the purpose of merging, the presense of mergeID is checked. If both have mergeID and the two mergeIDs are different, the two nodes are considered not equal and are not merged together. In all other cases (no mergeID is present, or only one of the two nodes have mergeID) the two nodes are compared using the usual rules. If you are wrting an XSLT and you have nodes that are equal acording to MagicTree node comparison rules, while in fact they represent separate real world entities, add a unique mergeID attribute to each one of them, so that they don't get merged together. We do this in Burp XSLT using Burp's finding serial number for mergeID value.
