Imprint Privacy policy Terms & Conditions Sitemap

XSAM Format

If you want to work with the XSAM file, for example before an import or after an export, this chapter gives a deeper understanding of it. The structure of an XSAM file as well as its functionality will be described in more detail.

General

XSAM files can store the data of a complete model or a single node. For XSAM files containing the data of a whole model, the root element must be mps:RootNodes. XSAM files containing a node will start with the corresponding data of the node. In the image below are parts of two XSAM files. The one on the left hand side shows an XSAM file of a whole model whereas the one on the right hand side shows an XSAM file of a single node:

The prefix “mps” is reserved for the “http://www.itemis.de/mps” namespace. All other elements belong to the “http://www.security-analyst.org/xsam” namespace. This namespace can be different according to the Import Model. The root element may have the attribute mps:modelRef. The attribute value of mps:modelRef is a reference to the model the data belongs to or is supposed to be imported into. If the root element represents a node instead of a model, itemis SECURE looks for an additional attribute mps:id. If mps:id is not set, itemis SECURE will try to resolve the target node based on external IDs . The modelRef as well as the IDs are very important if you want to import an XSAM file into an existing model, or into a node, or if you want to update one of them. This ensures that the data being updated match with each other.

External IDs

All elements in the document may have additional ID attributes, called external IDs. They will be used for identification if mps:id is not set. During import, itemis SECURE will also resolve cross references, based on external IDs. Known external IDs are included in the XSAM export. Cross references with external IDs have the following format:
"ext/{namespace}/{id}", without the curly braces, and {id} must not contain a slash (“/”).
Nodes may also be referenced by their type and name id="name/<concept term>/<node name>, for example id="name/Threat/MitM".

Please note by default, external IDs are not shown in itemis SECURE. To change this, go to File → Settings → Editor → Editor hints, and tick Show external IDs under de.itemis.mps.serialization. If external IDs are shown, you can also edit them manually in itemis SECURE. Use the intention Add External Ids ( Alt+Enter) at any element to add external IDs. This will show a field above that element where you can press Return to enter another namespace/ID combination.

Key Notes

  • Custom code is not part of XSAM, yet. User scripts as well as custom combinators or aggregators files may contain a whole model or a single node. For a whole model, the root element is an mps:RootNodes, possibly with an mps:modelRef attribute to identify the to-be-updated model. If the XSAM file contains only a particular node, the XML root node will be exactly that one.
  • Identify to-be-updated nodes with mps:id="<mps-id>", id="ext/<namespace>/<id>" or id="name/<concept serialization name>/<node name>". To identify a to-be-updated node based on its internal MPS node ID, put it into the mps:id attribute. To identify it via external IDs, choose a namespace and ID, provide them in id="ext/<ns>/<id>", and a repeated import, while updating the model based on the remembered ID ( Alt+Enter, Show external IDs displays the assigned external IDs in MPS). To identify a node via its MPS name, e.g., SG.214, provide the serialization name of its concept and the node name into id="name/<concept serialization name>/<node name>. These alternatives are also possible for cross-references, e.g., you can use target="name/AttackEffort/SPEX" instead of target="mps/<mps-id>".
  • If no existing node was identified, a new node with the given IDs is created. This allows to create elements on import, and update them when repeating the import.
  • To leave a collection unmodified, just leave it out. Containers of XML nodes may be left out to state leave it as it is. To clear a collection, provide the container, but leave it empty.
  • To leave a child collection unmodified, replace it with <mps:ExistingElements/>. If only a particular node of a collection should be updated or added, you may provide only the new data for this one and then add <mps:ExistingElements/> for the remaining data to state don’t remove other existing nodes.

To understand the exact fields and values, we recommend you to model an example and export it to XSAM.

Example

In this example, an Intelligence Database informs on updated attack feasibility ratings based on recent 0-days. This rating updates the required time for a man in the middle attack down to HOURS. It also enforces the description, name, title to have the expected values. Other properties of the attack step are left untouched.

The following example demonstrates how three features allow to formulate small, low-overhead XSAM files.
First, absent collections will not be modified. This is explained in more detail in the key notes.
Second, collections which include <mps:ExistingElements/> will only be updated, but not deleted. This has the advantage, when importing an incomplete XSAM file, that the IDs to be revised are revised and the already existing IDs are retained but not deleted.
Third, name-references can be used to point to elements in the method configuration so that cryptic IDs don’t disturb reading the XSAM document, such as in riskFactor="name/FeasibilityCategory/TIME". 

<?xml version="1.0" encoding="UTF-8"?>
<Securitychunk
 xmlns="http://www.security-analyst.org/xsam" xmlns:mps="http://www.itemis.de/mps" mps:id="1E_VH$V8tTo" mps:modelRef="r:2b50e850-9e01-4842-8a19-0558d10cdd14(xsam@tests)" name="Securitychunk">
   <Elements>
       <!-- in the description: link the words to the security properties AUT and INT -->
       <!-- in the id: provide an identifier to find the updated threat -->
       <Threat description="Exploit client/server communication channel authentication|AUT and integrity|INT "
           id="ysa/r:2b50e850-9e01-4842-8a19-0558d10cdd14(xsam@tests)/1UEFqBLBtFT"
           name="MitM" title="Manipulation and information disclosure">
           <InitialRiskFactors>
               <!-- let's reference these by name to ease building the exporter -->
               <RiskFactorRating riskFactor="name/FeasibilityCategory/TIME" level="name/FeasibilityOption/HOURS" />
           </InitialRiskFactors>

           <!-- unlisted property elements of this threat are not changed -->
           <!-- since we’re not providing any <Todos/> element, possibly present todos are kept intact -->
           <ExistingElements />
       </Threat>

       <!-- existing elements in this chunk will be left untouched -->
       <ExistingElements />
   </Elements>
</Securitychunk>

Platform Web Apps