Threatcl Cloud HCL Extensions

Threatcl Cloud extends the standard threatcl HCL specification with additional blocks that connect your local threat model files to your Cloud workspace. This guide covers these Cloud-specific extensions.

Prerequisites

This guide assumes you're familiar with the standard threatcl HCL syntax. The extensions described here are optional ‐ standard threatcl files work fine without them ‐ but they unlock Cloud features like syncing and versioning from the CLI.

The backend Block

The backend block tells the threatcl CLI how to connect your local HCL file to a specific threat model in Threatcl Cloud. It sits at the top level of your file, alongside spec_version and threatmodel .

backend "threatcl-cloud" {
  organization = "short-org-link"
  threatmodel  = "short-tm-link"
}

Attributes:

organization ‐ The short link identifier for your Threatcl Cloud organization. You can find this in your workspace.
threatmodel ‐ The short link identifier for the specific threat model. You can find this on your threat model's detail page.

Tip: You can also use the threatcl CLI to look up these values (sometimes referred to as "slugs"):

$ threatcl cloud whoami        # shows your organization slug
$ threatcl cloud threatmodels  # lists threat model slugs

How It Works

When you include a backend "threatcl-cloud" block in your HCL file, the threatcl CLI can use it to:

Push versions ‐ Upload new versions of your threat model directly from the command line
Validate remotely ‐ Check your file against Cloud's validation rules

Tip: The backend block is ignored by standard threatcl operations like threatcl validate and threatcl generate . It only activates when using Cloud-specific CLI commands.

Library References [Team plan & above]

Another Threatcl Cloud extension is the ability to refer to and include Library references from your cloud org. This uses ref attributes in either a threat or control block.

You will learn more about the Libraries in the next section. Here's an example:

spec_version = "0.2.4"
backend "threatcl-cloud" {
  organization = "your-org"
  threatmodel = "your-model"
}

threatmodel "app" {
  description = "A special app"
  author = "you"

  threat "sqli" {
    ref = "T-SQLI"
  }

  threat "DDoS" {
    description = "Distributed Denial of Service"

    control "cdn" {
      ref = "C-CDN"
    }
  }
}

Things to Note:

The existing blocks don't need description attributes, as these will default to the library item's values. However, you can specify them locally to override the referenced values.
The referenced IDs should exist within your Control or Threat Library
The referenced items should also be 'Published', not in Draft

Tip: The validate command will warn you of these, but will allow you to push :

$ threatcl cloud validate model.hcl
✓ Local Threat model file (org-id: 01a8b411-decf-47ae-b804-0f959cc16f21, model-id: my-app) matches a cloud threat model, but doesn't match the latest version
Consider running 'threatcl cloud push' to update the local file to the latest version.
⚠ Warning: non-PUBLISHED control refs: [C-CDN (DRAFT)]
✓ 1 threat ref(s) validated (PUBLISHED)

Complete Example

Here's a full threat model file with the Cloud backend configured:

spec_version = "0.2.4"

backend "threatcl-cloud" {
  organization = "my-org"
  threatmodel  = "my-web-app"
}

threatmodel "My Web Application" {
  description = "Customer-facing web application"
  author      = "@security-team"

  attributes {
    new_initiative  = "false"
    internet_facing = "true"
    initiative_size = "Medium"
  }

  information_asset "user_data" {
    description                = "User account information"
    information_classification = "Confidential"
  }

  threat "Unauthorized Access" {
    description = "Attacker gains access to user accounts"
    impacts     = ["Confidentiality"]
    stride      = ["Spoofing", "Elevation of Privilege"]

    information_asset_refs = ["user_data"]

    control "mfa" {
      description    = "Multi-factor authentication"
      implemented    = true
      risk_reduction = 85
    }

    control "logging" {
      ref = "C-LOGGING"
    }
  }

  threat "sqli" {
    ref = "T-SQLI"
  }
}

To start working with the threatcl cloud commands, move into the next steps on CLI Integration. This will walk through authenticating to your Threatcl Cloud Org, and other commands.

Next Steps

CLI Integration