传统的威胁建模往往姗姗来迟，有时甚至根本不会进行。此外，手动创建数据流和报告极其耗时。pytm 的目标是将威胁建模前置，使其更加自动化并以开发人员为中心。
基于您对架构设计的输入和定义，pytm 可以自动生成以下内容：
tm.py 是一个示例模型。您可以运行它以生成其引用的报告和图表图像文件：```
mkdir -p tm
./tm.py --report docs/basic_template.md | pandoc -f markdown -t html > tm/report.html
./tm.py --dfd | dot -Tpng -o tm/dfd.png
./tm.py --seq | java -Djava.awt.headless=true -jar $PLANTUML_PATH -tpng -pipe > tm/seq.png
还有一个示例 `Makefile`，它将所有这些内容封装成目标，可以轻松地共享给多个模型。如果你已安装 [GNU make](https://www.gnu.org/software/make/)（Linux 发行版默认安装，但 OSX 未预装），只需运行：```
make MODEL=the_name_of_your_model_minus_.py
你应该将 plantuml.jar 放在与你的模型相同的目录中，或者设置 PLANTUML_PATH。
为了避免安装所有依赖项（如 pandoc 或 Java），该脚本可以在容器内运行：```
export USE_DOCKER=true make image
make
### 入门指南 - Devbox 变体
为了简化 `pytm` 的使用，可以将主机依赖项完全隔离在
[`Devbox`](https://github.com/jetify-com/devbox) 环境中。这通常是
比 OCI 容器方法更低开销且更方便的替代方案。
- 在 Linux/MacOS 上安装 Devbox：`curl -fsSL https://get.jetify.com/devbox | bash`
- 在 [Windows/WSL](https://www.jetify.com/docs/devbox/installing-devbox/index#installing-wsl2) 上安装 Devbox
- 更新到最新版本的 devbox：`devbox version update`
- 在 `~/.config/nix/nix.conf` 文件中设置你的 GitHub 访问令牌：`access-tokens = github.com=YOUR_TOKEN_HERE`
- 创建一个新的、隔离的 shell 环境，其中包含项目 `devbox.json` 文件中指定的所有工具和包：`devbox shell`
- 使用 `which python` 命令显示在终端中直接输入 `python` 时将使用的 Python 可执行文件的完整路径。输出应为以下路径：`.devbox/nix/profile/default/bin/python`
- 通过运行以下命令进行测试，该命令将生成一个名为 `sample.png` 的 DFD 图片文件：`./tm.py --dfd | dot -Tpng -o sample.png`
- 退出 Devbox shell 环境：`exit`
## 使用方法
所有可用参数：```text
usage: tm.py [-h] [--debug] [--dfd] [--report REPORT]
[--exclude EXCLUDE] [--seq] [--list] [--describe DESCRIBE]
[--list-elements] [--json JSON] [--levels LEVELS [LEVELS ...]]
[--stale_days STALE_DAYS]
optional arguments:
-h, --help show this help message and exit
--debug print debug messages
--dfd output DFD
--report REPORT output report using the named template file (sample
template file is under docs/template.md)
--exclude EXCLUDE specify threat IDs to be ignored
--seq output sequential diagram
--list list all available threats
--colormap color the risk in the diagram
--describe DESCRIBE describe the properties available for a given element
--list-elements list all elements which can be part of a threat model
--json JSON output a JSON file
--levels LEVELS [LEVELS ...]
Select levels to be drawn in the threat model (int
separated by comma).
--stale_days STALE_DAYS
checks if the delta between the TM script and the code
described by it is bigger than the specified value in
days
stale_days 参数试图确定你正在编写的模型脚本与实现被建模系统的代码之间相隔的天数。理想情况下，在大多数活跃开发的系统中，两者应相当接近。你可以定期运行此参数来衡量项目的脉搏以及威胁模型的“新鲜度”。目前可用的元素包括：TM、Element、Server、ExternalEntity、Datastore、Actor、Process、SetOfProcesses、Dataflow、Boundary、Lambda、LLM 和 Agent。可以使用 --describe 后面跟上元素名称来列出元素的可用属性：```text
(pytm) ➜ pytm git:(master) ✗ ./tm.py --describe Element Element class attributes: OS definesConnectionTimeout default: False description handlesResources default: False implementsAuthenticationScheme default: False implementsNonce default: False inBoundary inScope Is the element in scope of the threat model, default: True isAdmin default: False isHardened default: False name required onAWS default: False
*colormap* 参数与 *dfd* 结合使用时，会输出一个颜色编码的数据流图（DFD），其中元素根据其风险等级（通过运行规则识别）被涂成红色、黄色或绿色。
## 使用方法 - Devbox 变体
- `devbox shell`
- `pytm` 使用方式与平常相同
- `exit`
## 创建威胁模型
以下是一个示例 `tm.py` 文件，描述了一个简单的应用程序：用户登录应用程序并在应用上发布评论。应用服务器将这些评论存储到数据库中。还有一个 AWS Lambda 函数定期清理数据库。```python
#!/usr/bin/env python3
from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda, LLM, Data, Classification
tm = TM("my test tm")
tm.description = "another test tm"
tm.isOrdered = True
User_Web = Boundary("User/Web")
Web_DB = Boundary("Web/DB")
user = Actor("User")
user.inBoundary = User_Web
web = Server("Web Server")
web.OS = "CloudOS"
web.isHardened = True
web.sourceCode = "server/web.cc"
db = Datastore("SQL Database (*)")
db.OS = "CentOS"
db.isHardened = False
db.inBoundary = Web_DB
db.isSql = True
db.inScope = False
db.sourceCode = "model/schema.sql"
comments = Data(
name="Comments",
description="Comments in HTML or Markdown",
classification=Classification.PUBLIC,
isPII=False,
isCredentials=False,
# credentialsLife=Lifetime.LONG,
isStored=True,
isSourceEncryptedAtRest=False,
isDestEncryptedAtRest=True
)
results = Data(
name="results",
description="Results of insert op",
classification=Classification.SENSITIVE,
isPII=False,
isCredentials=False,
# credentialsLife=Lifetime.LONG,
isStored=True,
isSourceEncryptedAtRest=False,
isDestEncryptedAtRest=True
)
my_lambda = Lambda("cleanDBevery6hours")
my_lambda.hasAccessControl = True
my_lambda.inBoundary = Web_DB
llm_api = LLM("AI Writing Assistant")
llm_api.isThirdParty = True
llm_api.processesPersonalData = True
llm_api.hasContentFiltering = False
llm_api.hasSystemPrompt = True
llm_api.processesUntrustedInput = True
my_lambda_to_db = Dataflow(my_lambda, db, "(λ)Periodically cleans DB")
my_lambda_to_db.protocol = "SQL"
my_lambda_to_db.dstPort = 3306
user_to_web = Dataflow(user, web, "User enters comments (*)")
user_to_web.protocol = "HTTP"
user_to_web.dstPort = 80
user_to_web.data = comments
web_to_user = Dataflow(web, user, "Comments saved (*)")
web_to_user.protocol = "HTTP"
web_to_db = Dataflow(web, db, "Insert query with comments")
web_to_db.protocol = "MySQL"
web_to_db.dstPort = 3306
db_to_web = Dataflow(db, web, "Comments contents")
db_to_web.protocol = "MySQL"
db_to_web.data = results
web_to_llm = Dataflow(web, llm_api, "Chat completion request")
web_to_llm.protocol = "HTTPS"
web_to_llm.dstPort = 443
tm.process()
您也可以选择使用 pytmGPT 从文本创建模型！
当将 --dfd 参数传递给上述 tm.py 文件时，它会生成输出到 stdout，然后由 Graphviz 的 dot 处理以生成数据流图：```bash
tm.py --dfd | dot -Tpng -o sample.png
生成此图：
dfd.png
为元素添加“.levels = [1,2]”属性将使其（以及其关联的数据流，如果两个流端点位于同一DFD级别）根据命令行参数“--levels 1 2”来渲染（或不渲染）。
以下命令生成一个序列图。```bash
tm.py --seq | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > seq.png
生成此图：
seq.png
可将图表和发现结果包含在模板中，以生成最终报告：```bash
tm.py --report docs/basic_template.md | pandoc -f markdown -t html > report.html
报告中使用的模板格式非常简单：```text
# Threat Model Sample
***
## System Description
{tm.description}
## Dataflow Diagram
## Dataflows
Name|From|To |Data|Protocol|Port
----|----|---|----|--------|----
{dataflows:repeat:{{item.name}}|{{item.source.name}}|{{item.sink.name}}|{{item.data}}|{{item.protocol}}|{{item.dstPort}}
}
## Findings
{findings:repeat:* {{item.description}} on element "{{item.target}}"
}
要按元素对发现进行分组，请使用更高级的嵌套循环：```text