Annotations

  1. Home
  2. /
  3. Learning
  4. /
  5. Advanced Topics
  6. /
  7. Extensions
  8. /
  9. Annotations

PioneerVisible
ExpertVisible
SimplifiedVisible
ManagementHidden
BusinessHidden
Execution Mode visibility.

The Quality Extension library provides a tool to annotate any object within the Threat Model. You need to install this Extension library separately from the Threats Manager Studio (TMS), from Downloads.

To enable Annotations for an object, you have to select the object itself and open its context menu. Then, you can enable Annotations on it by clicking the Enable Annotations item in the context menu.

How to enable Annotations.

Finally, you have to click the refresh button in the Item Editor, that is the small cycle image in the top right corner. As a result, the Annotations section will be shown.

The Item Editor with the Annotations section.

There are four different types of Annotations:

  • Notes, which is an open text used to add specific information to the object.
  • Topics to be Clarified, which are used to add questions related to the object requiring an answer to complete the analysis. Those Topics allow to track the answers as well.
  • Highlights, which are important considerations related to the object. For example, they may be used to identify the most important issues, and ensure that they are tracked and are discussed when the time comes.
  • Review Notes, which are used by reviewers to annotate the Threat Model.

Notes

Notes are the simplest way to annotate the Threat Model. They are a simple text which is used to specify details about the object. For example, you may use the Notes field of a Flow to specify the type of authentication used by its source and target, or if the channel is encrypted and how.

It is important to note that the Description may also used in that way, but in some cases it may be best to use the Description to specify what the object is all about, while the Notes for everything else. Please consider this as a suggestion, not as a prescription.

The Notes will be printed in Word reports since version 1.5.1.

Topics to be Clarified

Topics to be Clarified allow to keep track of additional information required during the analysis. They can be used to annotate open questions identified during the interviews, or while processing the gathered information, and then to track the answers received.

Topics to be Clarified are a great way to document the information gathering process and to pass the knowledge to others, like reviewers or other Threat Modelers who need to understand the Threat Model. It also allows to keep track of who provided the information, and when.

How to find the Annotations tool.

Through the Annotations tool, which can be found in the Home ribbon, it is possible to list all the Annotations to the Threat Model, including the Topics to be Clarified. The tool allows to focus on the Open Topics Only, which are those which do not have not been fully answered yet. It also allows to filter for the Highlights. Moreover, it allows to Export Open Topics as CSV or Excel files, to allow the solution developers to provide their answers.

The Annotations tool.

The Annotations tools provides a wealth of capabilities related to the Annotations, including the ability to add Notes, if not already present, Topics to be Clarified, and Highlights. It is not able to handle Review Notes, though, which is managed using the Review Notes tool discussed below.

Highlights

The Highlights capability allows to add annotations to keep track of particular important topics. For example, it is frequently used to write down major issues identified during the analysis, to facilitate the discussion.

Highlights are described with a simple text. They can be seen in the Item Editor, clicking on the containing object. They can also be reviewed in the Annotations tool, already discussed above.

Review Notes

The Review Notes contain Annotation included by Reviewers. They are simple texts associated to objects part of the Threat Model.

Again, Review Notes can be added using the Item Editor, and can be read in the Item Editor itself, by clicking on the containing object. They can also be reviewed in the Review Notes tool, which can be found in the Review ribbon.

The Review Notes tool.

This tool allows to select the Review Notes, edit or removing them, exporting them as an Excel file.

The Review Notes tool allows also to remove all the existing Review Notes, by using the Clear All Review Notes button in the Review Notes ribbon. This is particularly useful to remove all comments before finalizing the Threat Model and delivering it to third parties.

Additional capabilities

The Quality Extension Library provides additional features, besides those described here. For more information, please refer to: