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

有关如何构建可自动转换为 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/HEAD/examples/tm3.hcl)。我们也提供了 [MITRE ATT&CK 控制](https://attack.mitre.org/mitigations/enterprise/) [此处](https://github.com/threatcl/threatcl/blob/HEAD/examples/MITRE_ATTACK_controls.hcl)。

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

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

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

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

See [docs/SLSA.md](https://github.com/threatcl/threatcl/blob/HEAD/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/HEAD/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)

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

## 云命令

访问 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

### 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

## 生成

`threatcl generate` 命令用于输出一个通用的 `boilerplate` `threatcl` spec HCL 文件，或者交互式地向用户提问，然后输出一个 `threatcl` spec HCL 文件。

### 交互式生成

请参考以下示例：```bash
threatcl generate interactive

这将打开你的编辑器，并创建一个基础的 HCL 威胁模型。如果你想在创建后验证模型，请使用 `-validate` 标志。

## MCP

`threatcl mcp` 命令暴露一个本地 [MCP](https://modelcontextprotocol.io/introduction) 服务器，以便你可以通过 MCP 主机与 threatcl hcl 文件进行交互，例如 AI/LLM 应用程序，如 [Claude Desktop](https://claude.ai/download)、[Cursor](https://www.cursor.com/)，或任何其他支持 MCP 的应用程序。

该命令接受一个可选的参数 `-dir=<path>`，允许额外的 MCP 工具与该路径内的文件进行交互。没有此设置时，MCP 工具可以与字符串交互，但将依赖 MCP 主机内的其他机制与底层文件系统进行交互。

可以说，这个功能目前还处于相当初级的测试阶段。

## LSP (语言服务器)

`threatcl lsp` 命令通过 stdio 运行一个 [语言服务器协议](https://microsoft.github.io/language-server-protocol/) 服务器，为支持 LSP 的编辑器提供 threatcl HCL 威胁模型的实时诊断、补全、悬停、文档符号和格式化功能。

它由编辑器的 LSP 客户端启动，而不是手动运行。由于 threatcl 文件与 Terraform 和其他 HCL 方言共享 `.hcl` 扩展名，匹配 `*.tm.hcl`（或将客户端限定在你的威胁模型工作区内）可以避免与 Terraform 语言服务器冲突。

参见 [docs/lsp.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/lsp.md) 了解编辑器配置（Neovim、Helix、VS Code、Zed）以及当前限制。

## Server (GraphQL API)

`threatcl server` 命令启动一个 GraphQL API 服务器，通过 HTTP 暴露你的威胁模型，以供程序化查询和集成。

### 基本用法```bash
# Start the server
$ threatcl server -dir ./examples

# With file watching for auto-reload
$ threatcl server -dir ./examples -watch

# Custom port
$ threatcl server -dir ./examples -port 3000

### 文档

关于完整的 API 文档、模式参考、高级查询和集成示例，请参阅：
- **完整 API 文档**：[docs/graphql-api.md](https://github.com/threatcl/threatcl/blob/HEAD/docs/graphql-api.md)
- **查询示例**：[examples/graphql-queries.md](https://github.com/threatcl/threatcl/blob/HEAD/examples/graphql-queries.md)

## 查询 (GraphQL CLI)

`threatcl query` 命令直接从命令行执行 GraphQL 查询，无需启动服务器。这非常适合自动化、CI/CD 流水线和 shell 脚本。

### 基本用法```bash
# Get statistics
$ threatcl query -dir ./examples -query '{ stats { totalThreats } }'

# Query from file
$ threatcl query -dir ./examples -file queries/get-stats.graphql

# Use in scripts
$ THREATS=$(threatcl query -dir ./examples \
    -query '{ stats { totalThreats } }' \
    -output compact | jq -r '.data.stats.totalThreats')
$ echo "Found $THREATS threats"

### CI/CD 示例```bash
#!/bin/bash
# Check if all controls are implemented before deployment

UNIMPLEMENTED=$(threatcl query -dir ./threatmodels \
  -query '{ stats { totalControls implementedControls } }' \
  -output compact | jq -r '.data.stats.totalControls - .data.stats.implementedControls')

if [ "$UNIMPLEMENTED" -gt 0 ]; then
  echo "ERROR: $UNIMPLEMENTED controls are not yet implemented"
  exit 1
fi

echo "All controls implemented, proceeding with deployment"

### 自定义 Markdown 模板

`threatcl dashboard` 命令还可以使用可选标志来指定自定义模板（遵循 Go 语言的 [text/template](https://pkg.go.dev/text/template)）。

要指定仪表盘模板文件，请使用 `-dashboard-template` 标志。示例请参阅 [dashboard-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/dashboard-template.tpl)。

要指定威胁模型模板文件，请使用 `-threatmodel-template` 标志。示例请参阅 [threatmodel-template.tpl](https://github.com/threatcl/threatcl/blob/HEAD/examples/threatmodel-template.tpl)。

### 仪表盘索引文件的自定义文件名

`threatcl dashboard` 命令还可以使用一个可选标志来指定生成的“索引”仪表盘文件的文件名。默认情况下，此文件名为 `dashboard.md`。使用 `-dashboard-filename` 标志（不带扩展名）可更改此文件名。

## 数据流图

根据 [规范](https://github.com/threatcl/threatcl/blob/HEAD/spec.hcl)，一个 `threatmodel` 可能包含 `data_flow_diagram_v2` 块。一个简单 DFD 的示例可在 [这里](https://github.com/threatcl/threatcl/blob/HEAD/examples/tm2.hcl) 找到。旧的单次使用块 `data_flow_diagram` 将在某个时候被弃用，因此最好使用 `data_flow_diagram_v2` 命名块，这样你可以拥有多个关联的 DFD。

`threatcl dfd` 命令接受 `threatcl` 规范的 HCL 文件，并生成多个 png 文件，将它们放入所选文件夹中。

如果 HCL 文件不包含带有 `data_flow_diagram` 或 `data_flow_diagram_v2` 块的 `threatmodel` 块，则不会输出任何内容。

该命令本身与仪表盘命令非常相似。```bash
$ threatcl dfd -overwrite -outdir testout examples/*
Successfully created 'testout/tm2-modellymodel.png'

这使得可以轻松地通过管道传递给渲染器，例如 [mermaid-cli](https://github.com/mermaid-js/mermaid-cli)：```bash
$ threatcl mermaid model.hcl | mmdc -o diagram.svg -i -

## Terraform

`threatcl terraform` 命令能够从 `terraform show -json` [文档在此](https://www.terraform.io/docs/cli/commands/show.html) 输出的计划文件或活跃状态文件中提取数据资源，并将这些资源转换为草稿形式的 `information_asset` 块，以便包含在 `threatcl` 文件中。

如果你位于包含现有状态的文件夹中，可以执行以下命令：```bash
terraform show -json | threatcl terraform -stdin

你也可以通过运行以下命令，查看尚未通过 Terraform 应用的计划文件中的类似输出：```bash
terraform show -json <plan-file> | threatcl terraform -stdin

使用 `-add-to-existing` 标志时，如果源文件中有多个威胁模型，还可以通过指定 `-tm-name=<string>` 来选择特定的威胁模型。此外，你还可以通过 `-default-classification=Confidential` 标志应用默认分类。

这些命令也可以直接将文件作为输入，在这种情况下，省略 `-stdin` 标志。

`threatcl` 所识别的 Terraform 资源已硬编码在 [pkg/terraform/terraform.go](https://github.com/threatcl/threatcl/blob/HEAD/pkg/terraform/terraform.go) 中。如果你希望 `threatcl terraform` 命令输出其他不在该文件中的 `information_asset` 资源，可以通过 `-tf-collection=<json file>` 标志提供你自己的 JSON 版本。