threatcl

Threat Modeling with HCL

What happened to hcltm?

hcltm has been renamed to threatcl. Welcome!

Overview

[!TIP] Want to read the new documentation? Head over to threatcl.dev

There are many different ways in which a threat model can be documented. From a simple text file, to more in-depth word documents, to fully instrumented threat models in a centralised solution. Two of the most valuable attributes of a threat model are being able to clearly document the threats, and to be able to drive valuable change.

threatcl aims to provide a DevOps-first approach to documenting a system threat model by focusing on the following goals:

• Simple text-file format
• Simple cli-driven user experience
• Integration into version control systems (VCS)

This repository is the home of the threatcl cli software. The threatcl spec is based on HCL2, HashiCorp's Configuration Language, which aims to be "pleasant to read and write for humans, and a JSON-based variant that is easier for machines to generate and parse". The threatcl spec lives at github.com/threatcl/spec. Combining the threatcl cli software and the threatcl spec allows practitioners to define a system threat model in HCL, for example:

threatmodel "Tower of London" {
  description = "A historic castle"
  author = "@xntrik"

  attributes {
    new_initiative = "true"
    internet_facing = "true"
    initiative_size = "Small"
  }

  information_asset "crown jewels" {
    description = "including the imperial state crown"
    information_classification = "Confidential"
  }

  usecase {
    description = "The Queen can fetch the crown"
  }

  third_party_dependency "community watch" {
    description = "The community watch helps guard the premise"
    uptime_dependency = "degraded"
  }

  threat "Crown theft" {
    description = "Someone who isn't the Queen steals the crown"
    impacts = ["Confidentiality"]

    control "Guards" {
      description = "Trained guards patrol tower"
      risk_reduction = 75
    }
  }

  data_flow_diagram_v2 "dfd name" {
    // ... see below for more information
  }

}

See Data Flow Diagram for more information on how to construct data flow diagrams that may be converted to PNGs automatically.

To see an example of how to reference pre-defined control libraries for the OWASP Proactive Controls and AWS Security Checklist see examples/tm3.hcl. We also have the MITRE ATT&CK Controls here.

You can also include an external threatmodel into your own, to reference and use all its information. You can see examples/including-example/corp-app.hcl as an example.

To see a full description of the spec, see here or run:

threatcl generate boilerplate

threatcl will also process JSON files, but the only caveat is that import modules and variables won't work. You can see examples/tm1.json as an example.

Why HCL?

HCL is the primary configuration language used in the products by HashiCorp, in-particularly, Terraform - their open-source Infrastructure-as-Code software. I worked at HashiCorp for a while and the language really grew on me, plus, if DevOps and Software engineers are using the language, then simplifying how they document threat models aligns with threatcl's goals.

You can use threatcl with JSON, but you lose some of the features. For more, see the examples/ folder.

Why not just document them in MD?

I liked the idea of using a format that could be programmatically interacted with.

Kudos and References

One of the features of threatcl is the automatic generation of data flow diagrams from HCL files. This leverages the go-dfd package by Marqeta and Blake Hitchcock. Definitely check out their blog post on Threat models at the speed of DevOps.

Additionally I'd like to extend thanks to Jamie Finnigan and Talha Tariq at HashiCorp for allowing me to continue working on this open-source tool even after I'd finished up with HashiCorp.

Also thanks to the IriusRisk folks for the OpenThreatModel specification.

threatcl cli

Installation

Download the latest version from releases and move the threatcl binary into your PATH.

Install with Homebrew

Install threatcl with Homebrew — the formula lives in homebrew-core:

brew install threatcl

Run with Docker

docker run --rm -it ghcr.io/threatcl/threatcl:latest

Verifying releases (build provenance)

Every tagged release ships SLSA build provenance — Sigstore-signed, keyless attestations generated by the GitHub Actions release pipeline (GitHub OIDC → Fulcio, no signing keys). You can verify that a binary or the container image was genuinely built from this repo's release workflow using the GitHub CLI (gh attestation verify — no extra tooling or trusted keys to manage).

Verify a downloaded archive (or the SHA256SUMS file):

gh attestation verify threatcl_<version>_<os>_<arch>.tar.gz --repo threatcl/threatcl

Verify the container image (the tag is resolved to its digest automatically):

gh attestation verify oci://ghcr.io/threatcl/threatcl:<version> --repo threatcl/threatcl

To pin to the exact image you run, resolve the digest yourself and verify (and pull) by digest:

digest=$(docker buildx imagetools inspect ghcr.io/threatcl/threatcl:<version> --format '{{ .Manifest.Digest }}')
gh attestation verify oci://ghcr.io/threatcl/threatcl@${digest} --repo threatcl/threatcl

See docs/SLSA.md for the full supply-chain posture.

Run with GitHub Actions

threatcl can be integrated directly into your GitHub repos with https://github.com/threatcl/threatcl-action. This is one of the ideal methods to manage your threat models, and helps meet the goal of integrating into your version control systems.

Building from Source

1. Clone this repository.
2. Change into the directory, threatcl
3. make bootstrap
4. make build

For further help on contributing to threatcl please see the CHANGELOG.md.

Usage

For help on any subcommands use the -h flag.

$ threatcl
Usage: threatcl [--version] [--help] <command> [<args>]