pytm: 脅威モデリングのためのPythonicフレームワーク

はじめに

従来の脅威モデリングは、しばしば後手に回りがちで、時には全く行われないこともあります。さらに、手動でのデータフローやレポートの作成は非常に時間がかかる場合があります。pytmの目標は、脅威モデリングを左にシフトし、より自動化され開発者中心のものにすることです。

機能

入力とアーキテクチャ設計の定義に基づいて、pytmは以下の項目を自動的に生成できます：

• データフロー図（DFD）
• シーケンス図
• システムに関連する脅威

要件

• Linux/MacOS
• Python 3.11+
• Graphvizパッケージ
• Java（OpenJDK 10または11）
• plantuml.jar

はじめに

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 がインストールされている場合（Linuxディストリビューションではデフォルトで利用可能ですが、OSXでは利用できません）、単純に次を実行します：

make MODEL=the_name_of_your_model_minus_.py

plantuml.jar をモデルと同じディレクトリに配置するか、PLANTUML_PATH を設定する必要があります。

pandoc や Java などの依存関係をすべてインストールするのを避けるために、スクリプトはコンテナ内で実行できます:

# do this only once
export USE_DOCKER=true
make image

# call this after every change in your model
make

はじめに - Devbox バリアント

pytm の使用を簡素化するために、ホスト依存関係は Devbox を使用して完全に分離できます。これは通常、OCI コンテナアプローチよりもオーバーヘッドが少なく、便利な代替手段です。

• Linux/MacOS に Devbox をインストール: curl -fsSL https://get.jetify.com/devbox | bash
• Windows/WSL に 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

はじめに - AI バリアント

「でも、この『コードを書く』という話はもう終わったと思ってたのに!」 - これは、AI アシスタントと話しすぎている私たちのためのものです: https://github.com/izar/tm_skills をチェックして、コーディングアシスタントに OWASP pytm を追加する方法をいくつか見てみてください (pytm の動作するインストールは依然として必要です!)。

使用方法

利用可能なすべての引数:

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/basic_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、Dataflow、Boundary、Lambda、LLM、Agent。

要素で利用可能なプロパティは、--describe に続けて要素名を指定することで一覧表示できます:

$ ./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: <lambda>
  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: <lambda>

colormap 引数は、dfd と併用することで、ルールの実行によって特定されたリスクレベルに応じて要素が赤、黄、緑に塗り分けられたカラーコード付き DFD を出力します。

使用方法 - Devbox バリアント

• devbox shell
• pytm を通常どおり使用
• exit

脅威モデルの作成

以下は、ユーザーがアプリケーションにログインし、アプリにコメントを投稿するシンプルなアプリケーションを記述した tm.py ファイルのサンプルです。アプリサーバーはそれらのコメントをデータベースに保存します。データベースを定期的にクリーンアップする AWS Lambda があります。

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