従来の脅威モデリングは、しばしば遅れて登場するか、まったく行われないことがあります。さらに、手動でデータフローやレポートを作成するのは非常に時間がかかります。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`
- プロジェクトの `devbox.json` ファイルに指定されたすべてのツールとパッケージを含む、新しい独立したシェル環境を作成: `devbox shell`
- ターミナルで単に `python` と入力したときに使用される Python 実行ファイルのフルパスを `which python` コマンドを使用して表示します。出力は次のパスになるはずです: `.devbox/nix/profile/default/bin/python`
- 次のコマンドを実行してテストします。これにより、`sample.png` という名前の PNG ファイルとして DFD が生成されます: `./tm.py --dfd | dot -Tpng -o sample.png`
- Devbox シェル環境を終了: `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を出力します。
## Usage - Devbox Variant
- `devbox shell`
- `pytm` usage as usual
- `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()
You also have the option of using pytmGPT to create your models from prose!
図は Dot および PlantUML として出力されます。
上記の tm.py ファイルに --dfd 引数を渡すと、標準出力に結果が生成され、それが 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