返回更新列表
新发布Jul 14, 2026

threatcl v0.6.1

使用HCL记录您的威胁模型

分享

threatcl

使用 HCL 进行威胁建模

hcltm 发生了什么？

hcltm 已更名为 threatcl。欢迎！

概述

[!TIP] 想阅读新的文档？请访问 threatcl.dev

威胁模型可以通过多种方式进行记录。从简单的文本文件，到更深入的 Word 文档，再到完全仪表化的集中式解决方案中的威胁模型。威胁模型的两个最有价值的属性是能够清晰记录威胁，并能够推动有价值的变更。

threatcl 旨在通过关注以下目标，提供一种 DevOps 优先的方法来记录系统威胁模型：

  • 简单的文本文件格式
  • 简单的 CLI 驱动用户体验
  • 集成到版本控制系统（VCS）中

此仓库是 threatcl CLI 软件的所在地。threatcl 规范 基于 HCL2，即 HashiCorp 配置语言，其目标是“对于人类而言易于阅读和编写，以及一种基于 JSON 的变体，更便于机器生成和解析”。threatcl 规范位于 github.com/threatcl/spec。结合 threatcl CLI 软件和 threatcl 规范，实践者可以用 HCL 定义系统威胁模型，例如：```hcl 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 }

}

有关如何构建可自动转换为 PNG 的数据流图的更多信息，请参阅[数据流图](#data-flow-diagram)。

要了解如何引用 [OWASP 主动控制](https://owasp.org/www-project-proactive-controls/) 和 [AWS 安全清单](https://d1.awsstatic.com/whitepapers/Security/AWS_Security_Checklist.pdf) 的预定义控制库的示例，请参阅 [examples/tm3.hcl](https://github.com/threatcl/threatcl/blob/main/examples/tm3.hcl)。我们也提供了 [MITRE ATT&CK 控制](https://attack.mitre.org/mitigations/enterprise/) [此处](https://github.com/threatcl/threatcl/blob/main/examples/MITRE_ATTACK_controls.hcl)。

您还可以将外部威胁模型包含到您自己的模型中，以引用和使用其所有信息。您可以查看 [examples/including-example/corp-app.hcl](https://github.com/threatcl/threatcl/blob/main/examples/including-example/corp-app.hcl) 作为示例。

要查看规范的完整描述，请参阅[此处](https://github.com/threatcl/threatcl/blob/main/spec.hcl)或运行：```bash
threatcl generate boilerplate

threatcl 也会处理 JSON 文件，但唯一的限制是导入模块和变量将无法工作。你可以参考 examples/tm1.json 作为示例。

为什么使用 HCL？

HCL 是 HashiCorp 产品中使用的主要配置语言，特别是 Terraform——他们的开源基础设施即代码软件。我曾在 HashiCorp 工作过一段时间，这种语言逐渐让我喜欢上了它，此外，如果 DevOps 和软件工程师正在使用这种语言，那么简化他们记录威胁模型的方式与 threatcl 的目标是一致的。

你可以将 threatcl 与 JSON 一起使用，但会失去一些功能。更多信息请参见 examples/ 文件夹。

为什么不直接用 Markdown 记录？

我喜欢使用一种可以以编程方式交互的格式的想法。

致谢与参考

threatcl 的功能之一是自动从 HCL 文件生成数据流图。这利用了 Marqeta 和 Blake Hitchcock 的 go-dfd 包。一定要看看他们关于威胁模型迈向 DevOps 的速度的博客文章。

此外，我要感谢 HashiCorp 的 Jamie Finnigan 和 Talha Tariq，允许我在离开 HashiCorp 后继续开发这个开源工具。

还要感谢 IriusRisk 团队提供的 OpenThreatModel 规范。

threatcl 命令行工具

安装

从 releases 下载最新版本，并将 threatcl 二进制文件移动到你的 PATH 中。

通过 Homebrew 安装

使用 Homebrew 安装 threatcl——该公式位于 homebrew-core 中：```bash brew install threatcl

## 使用 Docker 运行```bash
docker run --rm -it ghcr.io/threatcl/threatcl:latest

验证发布版本（构建来源证明）

每个标记的发布版本都附带 SLSA 构建来源证明 — Sigstore 签名、无密钥证明，由 GitHub Actions 发布流水线生成（GitHub OIDC → Fulcio，无需签名密钥）。您可以使用 GitHub CLI（gh attestation verify — 无需额外工具或管理的受信任密钥）验证二进制文件或容器镜像确实是从此仓库的发布工作流构建的。

验证下载的归档文件（或 SHA256SUMS 文件）：```bash gh attestation verify threatcl_.tar.gz --repo threatcl/threatcl

验证容器镜像（标签会自动解析为其摘要）：```bash
gh attestation verify oci://ghcr.io/threatcl/threatcl:<version> --repo threatcl/threatcl

要固定到你所运行的确切镜像，请自行解析摘要，并通过摘要进行验证（和拉取）：```bash digest=$(docker buildx imagetools inspect ghcr.io/threatcl/threatcl: --format '{{ .Manifest.Digest }}') gh attestation verify oci://ghcr.io/threatcl/threatcl@${digest} --repo threatcl/threatcl

See [docs/SLSA.md](https://github.com/threatcl/threatcl/blob/main/docs/SLSA.md) 了解完整的供应链安全状况。

## 通过 GitHub Actions 运行

`threatcl` 可以直接集成到您的 GitHub 仓库中，使用 https://github.com/threatcl/threatcl-action。这是管理威胁模型的理想方法之一，并有助于实现集成到版本控制系统的目标。

## 从源码构建

1. 克隆此仓库。
2. 进入目录 `threatcl`
3. `make bootstrap`
4. `make build`

有关对 `threatcl` 贡献的更多帮助，请参阅 [CHANGELOG.md](https://github.com/threatcl/threatcl/blob/main/CHANGELOG.md)。

## 使用方法

有关任何子命令的帮助，请使用 `-h` 标志。```bash
$ threatcl
Usage: threatcl [--version] [--help] <command> [<args>]

Available commands are:
    cloud        Interact with ThreatCL Cloud services
    dashboard    Generate markdown files from existing HCL threatmodel file(s)
    dfd          Generate Data Flow Diagram PNG or DOT files from existing HCL threatmodel file(s)
    export       Export threat models into other formats
    generate     Generate an HCL Threat Model
    list         List Threatmodels found in HCL file(s)
    mcp          Model Context Protocol (MCP) server for threatcl
    mermaid      Output raw mermaid source from 'mermaid' blocks in existing HCL threatmodel file(s)
    query        Execute GraphQL queries against threat model data
    server       Start a GraphQL API server for threat models
    terraform    Parse output from 'terraform show -json'
    validate     Validate existing HCL Threatmodel file(s)
    view         View existing HCL Threatmodel file(s)

（可选）配置文件

大多数 threatcl 命令都带有 -config 标志，允许你指定一个 config.hcl 文件。该文件中的 HCL 可用于覆盖 threatcl 的部分默认属性。以下是可覆盖的属性列表：

  • 威胁类型规模 - 默认值为“未定义”、“小型”、“中型”、“大型”
  • 默认威胁类型规模 - 默认值为“未定义”
  • 信息分类 - 默认值为“受限”、“机密”、“公开”
  • 默认信息分类 - 默认值为“机密”
  • 影响类型 - 默认值为“机密性”、“完整性”、“可用性”
  • STRIDE 元素 - 默认值为“欺骗”、“篡改”、“信息泄露”、“拒绝服务”、“权限提升”
  • 运行时间依赖分类 - 默认值为“无”、“降级”、“硬依赖”、“运营依赖”
  • 默认运行时间依赖分类 - 默认值为“无”

例如：```hcl initiative_sizes = ["S", "M", "L"] default_initiative_size = "M" info_classifications = ["1", "2"] default_info_classification = "1" impact_types = ["big", "small"] strides = ["S", "T"] uptime_dep_classifications = ["N", "D"] default_uptime_dep_classification = "N"

如果您修改这些属性，则需要记住为其他操作提供配置文件，因为这可能会影响验证或仪表盘创建。

## 云命令

访问 https://threatcl.dev/cloud/overview/ 了解更多关于 `cloud` 子命令的信息。

## 列表与查看

`threatcl list` 和 `threatcl view` 命令可用于列出和查看来自 `threatcl` 规范 HCL 文件的数据。```bash
$ threatcl list examples/*
#  File              Threatmodel      Author
1  examples/tm1.hcl  Tower of London  @xntrik
2  examples/tm1.hcl  Fort Knox        @xntrik
3  examples/tm2.hcl  Modelly model    @xntrik

Validate

threatcl validate 命令用于验证 threatcl 规范 HCL 文件。```bash $ threatcl validate examples/* Validated 3 threatmodels in 3 files

### Invariants

`threatcl validate` 还可以强制实施组织级的不变性——即机器可检查的规则，例如“公共端点不应未经身份验证”或“所有面向互联网的功能必须记录审计日志”——针对每个经过验证的威胁模型：```bash
$ threatcl validate -invariants=invariants.hcl ./models/
Validated 4 threatmodels in 3 files
Invariant violation [error] 'threats_have_implemented_controls': threat 'Credential theft' in threatmodel 'Payments' (models/payments.hcl): Every threat must have at least one implemented control
Checked 3 invariants against 4 threatmodels: 1 errors, 0 warnings, 1 exemptions

不变条件存在于它们自己的 HCL 文件中，针对特定集合（威胁、控制、DFD 进程、数据流……），并以原生 HCL 表达式的形式表达其条件。它们支持 error/warning 严重级别以及带有理由的每模型豁免。参见 docs/invariants.md。

Export

阅读更多

分类

DevSecOps实用工具与框架威胁情报学习与教育