Threatmodel block

Each threatcl hcl file has to include one more unique threatmodel blocks.

threatmodel attributes

Attribute	Type	Req’d	Description
NAME	label string		Specifies the name of the threat model
author	string		Specifies the author of the threat model
description	string		Describes the threat model
link	string		An href to other documentation
diagram_link	string		An href to a diagram. (see diagram_link)
created_at	integer		Creation UNIX timestamp
updated_at	integer		Updated UNIX timestamp
attributes	block		See attributes
additional_attributes	block		See additional_attributes
usecase	block		See usecase
exclusion	block		See exclusion
third_party_dependency	block		See third_party_dependency
information_asset	block		See information_asset
threat	block		See threat
including	string		See including
imports	array [string]		See imports

diagram_link

If it ends in .jpg or .png then it will be embedded in the resultant dashboard. If this isn’t set, but there is a data flow diagram, this will be automatically generated and included when running threatcl dashboard

attributes

The attributes block is optional, but recommended. It includes the following attributes.

Attribute	Type	Required	Description
new_initiative	boolean		Whether this is a new project
internet_facing	boolean		Whether this system is exposed to the Internet
initiative_size	string		Undefined, Small, Medium, Large

additional_attributes

Your threatmodel may include multiple additional_attributes blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		The name of the attribute
value	string		The value of the attribute

usecase

Your threatmodel may include multiple usecase blocks. These don’t have labels or identifiers. It includes the following attribute.

Attribute	Type	Required	Description
description	string		A description of the system’s use case

exclusion

Your threatmodel may include multiple exclusion blocks. These don’t have labels or identifiers. It includes the following attribute.

Attribute	Type	Required	Description
description	string		Define of out-of-scope exclusions of the threatmodel

third_party_dependency

Your threatmodel may include multiple third_party_dependency blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		The name of the 3rd party dep
description	string		A description of the 3rd party dep
uptime_dependency	string		none, degraded, hard, operational
saas	boolean		Is this a SaaS dep?
paying_customer	boolean		Are we paying for it?
open_source	boolean		Is this OSS?
infrastructure	boolean		Is this Infra?
uptime_notes	string		Notes about what happens if unavailable

information_asset

Your threatmodel may include multiple information_asset blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		The name of the asset
description	string		Describe the asset
information_classification	string		Public, Confidential, Restricted
source	string		Where was block sourced from i.e. terraform

threat

Your threatmodel may include multiple threat blocks. These don’t have labels or identifiers. It includes the following attributes.

Attribute	Type	Required	Description
description	string		Describe the threat
impacts	array [string]		Confidentiality, Integrity, Availability
stride	array [string]		Spoofing, Tampering, Repudiation, Info Disclosure, Denial of Service, Elevation of Privilege
information_asset_refs	array [string]		Refer to information_asset blocks by their label
expanded_control	block		See expanded_control
control_imports	array [string]		Allows you to import full expanded control blocks. See imports

expanded_control

Your threat blocks may include multiple expanded_control blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		The name of the control
description	string		Describe the control
implemented	boolean		Is it implemented?
implementation_notes	string		Describe the implementation
risk_reducation	integer		How much this control reduces risk
attribute	block		See attribute

attribute

Your expanded_control blocks may include multiple attribute blocks, with unique labels. It includes the following attribute.

Attribute	Type	Required	Description
NAME	label string		The name of the attribute
value	string		The value of the attribute

data_flow_diagram_v2

Your threatmodel may include multiple data_flow_diagram_v2 blocks, with unique labels. It includes the following attributes.

Unlike other blocks, when you define a process, data_store, or external_element they must have a globally unique label, for that particular dfd. For example, you can’t have a process and data_store called “foo”.

Attribute	Type	Required	Description
NAME	label string		dfd name
process	block		See process
data_store	block		See data_store
external_element	block		See external_element
trust_zone	block		See trust_zone
flow	block		See flow

process

Your data_flow_diagram_v2 block may include multiple process blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		process name
trust_zone	string		defines a trust boundary / zone

data_store

Your data_flow_diagram_v2 block may include multiple data_store blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		data store name
trust_zone	string		defines a trust boundary / zone
information_asset	string		refers back to a previous information_asset block ref

external_element

Your data_flow_diagram_v2 block may include multiple external_element blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		external element name
trust_zone	string		defines a trust boundary / zone

trust_zone

Your data_flow_diagram_v2 block may include multiple trust_zone blocks, with unique labels. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		trust zone name
process	block		see process
data_store	block		see data_store
external_element	block		see external_element

flow

Your data_flow_diagram_v2 block may include multiple flow blocks. A flow must have a label, but it doesn’t have to be unique. But, the from and to attributes must be unique. It includes the following attributes.

Attribute	Type	Required	Description
NAME	label string		flow title
from	string		refer to a process, external_element or data_store
to	string		refer to a process, external_element or data_store

including

Each threatmodel may optionally include an including attribute string that refers to a single other threatcl hcl file.

In this file must be a single, valid threatmodel block.

This included threatmodel will form the base of this new threatmodel. Any duplicate fields in the parent threat model will overwrite those from the included.

See External HCL Files for more information on how to refer to external files.

imports

Each threatmodel may optionally include an imports attribute with an array of string values that refer to other hcl files.

These files are used to centrally define various attributes that you can then refer to in your threatmodel. Currently we only support the definition of “control”, and “expanded_control” components.

An example import file may look like:

controls.hcl

component "control" "control_name" {
  description = "A control that can be used in multiple places"
}

component "expanded_control" "authentication_control" {
  description = "Multi-factor authentication required"
  implemented = true
  implementation_notes = "Using TOTP for all admin accounts"
  risk_reduction = 80

  attribute "category" {
    value = "Authentication"
  }

  attribute "framework" {
    value = "NIST"
  }
}

To use these imports, you reference to the string value like this:

threatmodel.hcl

threatmodel "tm" {
  author = "@xntrik"
  description = "A threat model"

  imports = ["controls.hcl"]

  threat {
    description = "Something bad"

    expanded_control "control" {
      description = import.control.control_name.description
    }
  }
}

You can also use string interpolation as well, so for instance:

  description = "Some text that and ${import.control.control_name.description}"

Technically you can use these import values similar to Variables

The expanded_control components are imported slightly differently, in this instance, you use the control_imports string array inside a threat block. For example, to import the authentication_control from above:

threat {
  description = "Authentication is bypassed"

  control_imports = ["import.expanded_control.authentication_control"]
}

When this is Viewed, or Exported, that threat will include that external Expanded Control block

threat {
    description            = "Authentication is bypassed"

    expanded_control "authentication_control" {
      implemented          = true
      description          = "Multi-factor authentication required"
      implementation_notes = "Using TOTP for all admin accounts"
      risk_reduction       = 80

      attribute "category" {
        value = "Authentication"
      }
      attribute "framework" {
        value = "NIST"
      }
    }
  }

See External HCL Files for more information on how to refer to external files.