Threat Model template

threatware is a tool to help people create threat models, but it needs to understand the format of a threat model in order to help. To enable threatware to help threat models should be created from a threat model template which has a format that threatware can parse. threatware parses threat models using a scheme file that describes the format of the threat model. threatware provides an scheme for a threat model template that is tried and tested and been used in different organisations. This section describes how to populate the provided threat model template (and this threat model template can be used without threatware, but threatware makes it simple to verify the template is populated correctly, and to manage the lifecycle of a threat model).

threatware actually provides 2 versions of the same threat model template:

  • Google Doc

  • Confluence Page (unfortunately there is no free way to make a Confluence page available publicly. You can download the Google Doc as a Word doc and then import the Word doc to a Confluence Page. Some formatting will need to be applied though e.g. table widths, table header rows, etc.)

Tip

The best way to learn how to populate the threat model template is to look at examples first, and read the documentation second.

For an example threat model, of threatware, see Example

The following sections describe how to populate information in the above templates, regarding the context of the system being threat modelled.

Details Table

The Details table contains management metadata about the Threat Model.

Threat Model ID

This can be any value that you want to use to identify the threat model. If you are using threatware to help manage threat models then this value must be generated by a call to manage.create. The prupose of this value is to serve as a unique identifier for this threat model, that never changes (thus allowing the threat model Document Name to change).

Threat Model Document Name

The name of the document. This should just be the same as the name of the Confluence page or of the Google Doc.

Current Version

The current version number of the document in <major>.<minor> format e.g. 1.0, 1.1, 2.0 etc. This value should be incremented with every change of the threat model from it’s approved version, but numerous changes should be aggregated under a single increment (basically until the threat model is approved again).

Approved Version (not mandatory)

The approved version of the threat model. This must only be set by someone authorised to approve threat models. It must correspond to a row in the ()[##Version History Table] where the version has been approved (i.e. there is a row in the ()[##Version History Table] where the Version corresponds to this value, and the Approver Name and Approver Date have been populated by a threat model approver).

Version History Table

The Version History Table contains rows corresponding to different versions of the threat model. The columns capture metadata, change log and approvals about a given version.

Version

The version of the threat model this row provides information about, in <major>.<minor> format e.g. 1.0, 1.1, 2.0 etc. There should always be a row corresponding to the Current Version and Approved Version (if one exists, and it’s different to the Current Version).

Author Name

The name, or names, of the authors of the threat model.

Author Role

The job role, or roles, of the author(s).

Date

The date the author created this version of the threat model. threatware will attempt to automatically determine the date format, but this is not always possible to get right.

Change Log

A short description of the changes made to this version of the threat model. This can be appended to as more changes get made to that specific version. If the version is the very first version then often Initial version is used.

Status

This can be one of:

  • Draft

  • Approved

  • Obsolete

This must only be set by a threat model approver, except when a new version has been added, in which case the author must set it to Draft.

Approver Name

The name of the threat model approver that approved this version of the threat model. This must only be set by a threat model approver, and authors should leave it blank. A version of a threat model is only considered approved if this field is populated (along with Approver Date). If this value is populated then Approver Date must also be populated.

Approver Date

The date that the threat model approver approved this version of the threat model. This must only be set by a threat model approver, and authors should leave it blank. A version of a threat model is only considered approved if this field is populated (along with Approver Name).

Scope Table

The Scope Table gathers identifiers related to the system being threat modelled. By gathering this information in threat models, it should enable threat models to be discovered if only an identifier for a system is known e.g. a service name, a repo, a team etc.

Note

The Scope Table should be one of the first tables to consider customising to your businesses needs, as each business will have their own way of identifing systems (e.g. service, name, service IDs, service accounts, OAuth2 Client IDs, etc.), and you may have your own preferences on what information you want to be able to search for, or group, threat models by (e.g. cloud account name/ID, datacentre, region, highest data sensitivity processed, etc.).

Org

The organisation that the Team belongs to. Different businesses use different terminology e.g. Business Unit, Tribe, etc.

Team

The name of the team that owns the in-scope components of the system being threat modelled.

Repos

The source code repository locations of the systems in-scope for this threat model. More than 1 value can be listed, but entries shoudl be , or \n separated.

3rd Parties

The 3rd parties that are in-scope for this threat model. More than 1 value can be listed, but entries shoudl be , or \n separated.

A 3rd Party is practically defined as a system not developed by the Team, but that the Team “owns” in the sense that they are responsible for it. An example would be a SaaS service that the system being threat modelled depends on and was provisioned by the Team. Typically this would NOT include common internal services, or common infrastructure services (whether in the cloud or on-prem) - for instance this field is not meant to capture every AWS/GCP/Azure service used by the system being threat modelled. It would be very common for a 3rd Party to be mentioned here if the Team has some kind of operational security responsibility for it, as captured in Operational Security Table.

Description

The Description section should be a short (i.e. 1-3 paragraphs) explaining the purpose and use cases of the system being threat modelled. Ideally this text should be copied directly from any existing engineering documentation describing the system being threat modelled (it should not just be a link to it (although a link can be provided), as the threat model should be relatively self-contained for basic information).

This section should also include a diagram of the system being threat modelled. Ideally this diagram should be copied directly from any existing engineering documentation (and again, not a link to it). The components in this diagram should correspond to the components captured in the Components Details Table (in reality it is unlikely to be one-to-one, but it should contain the “main” components).

References

This section should be an unordered list (and only an unordered list otherwise threatware will fail to parse it) of any links to relevant documents, images, processes, definitions, etc. related to the system beign threat modelled. threatware will only capture hyperlink text and hyperlink URLs.