従来の脅威モデリングは、あまりにも遅れて実施されることが多く、まったく実施されないこともあります。さらに、手作業でデータフローやレポートを作成するのは非常に時間がかかります。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
### Getting Started - 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] [--colormap] [--describe DESCRIBE]
[--list-elements] [--json JSON] [--levels LEVELS [LEVELS ...]]
[--stale_days STALE_DAYS]
options:
-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
$ ./tm.py --describe Server
Server class attributes:
OS Operating system
default: ''
assumptions Assumptions about the element. These optionally allow to exclude threats with the given SIDs
default factory: list
controls Security controls for this element
default factory: Controls
data pytm.Data object(s) in incoming data flows
default factory: DataSet
description Description of the element
default: ''
findings Threats that apply to this element
default factory: list
handlesResources Does this asset handle resources?
default: False
inBoundary Trust boundary this element exists in
default: None
inScope Is the element in scope of the threat model
default: True
inputs incoming Dataflows
default factory: list
is_drawn default: False
levels List of levels (0, 1, 2, ...) to be drawn in the model
default factory:
maxClassification Maximum data classification this element can handle
default: <Classification.UNKNOWN: 0>
minTLSVersion Minimum TLS version required
default: <TLSVersion.NONE: 0>
name Name of the element
required
onAWS Is this asset on AWS?
default: False
outputs outgoing Dataflows
default factory: list
overrides Overrides to findings, allowing to set a custom response, CVSS score or override other attributes
default factory: list
port Default TCP port for incoming data flows
default: -1
protocol Default network protocol for incoming data flows
default: ''
severity Severity level of threats affecting this element
default: 0
sourceFiles Location of the source code that describes this element relative to the directory of the model script
default factory: list
usesCache Does this server use cache?
default: False
usesEnvironmentVariables Does this asset use environment variables?
default: False
usesSessionTokens Does this server use session tokens?
default: False
usesVPN Does this server use VPN?
default: False
usesXMLParser Does this server use XML parser?
default: False
uuid default factory:
The *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, DatastoreType
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