# 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](https://docs.google.com/document/d/1DBskRZBKpolIchljkVowFsvB-xRlSVf8sPguOnxsnhU/edit) - 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 [](./examples.md) ::: 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`](../actions/manage.md#managecreate). 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 `.` 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 `.` 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 [](./operations.md#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.md#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.