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](https://www.gnu.org/software/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

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

web = Server("Web Server")
web.OS = "CloudOS"
web.controls.isHardened = True
web.sourceFiles = ["server/web.cc"]

db = Datastore("SQL Database (*)")
db.OS = "CentOS"
db.controls.isHardened = False
db.inBoundary = Web_DB
db.type = DatastoreType.SQL
db.inScope = False
db.sourceFiles = ["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.controls.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, "(&lambda;)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 を使って、散文からモデルを作成するオプションもあります！

図の生成

図は 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

tm.py --report docs/basic_template.md | pandoc -f markdown -t html > report.html

レポートテンプレートで使用されるテンプレート形式は非常にシンプルです：```text

# Threat Model Sample
***

## System Description

{tm.description}

## Dataflow Diagram

![Level 0 DFD](https://raw.githubusercontent.com/owasp/pytm/HEAD/dfd.png)

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

Findings

{elements🔁{{item.findings:if:

{{item.findings🔁 Threat: {{{{item.id}}}} - {{{{item.description}}}}

Severity: {{{{item.severity}}}}

Mitigations: {{{{item.mitigations}}}}

References: {{{{item.references}}}}

}}}}}

ループ内のすべてのアイテムはエスケープする必要があり、中括弧を二重にします。したがって、`{item.name}` は `{{item.name}}` になります。
上記の例では2つのネストされたループを使用しているため、内側のループのアイテムは2回エスケープする必要があり、そのため4つの中括弧を使用しています。

### オーバーライド

ファインディング（モデルのアセットやデータフローに一致する脅威）の属性をオーバーライドできます。たとえば、カスタムCVSSスコアや応答テキストを設定する場合などです。```python
user_to_web = Dataflow(user, web, "User enters comments (*)", protocol="HTTP", dstPort="80")
user_to_web.overrides = [
    Finding(
        # Overflow Buffers
        threat_id="INP02",
        cvss="9.3",
        response="""**To Mitigate**: run a memory sanitizer to validate the binary""",
        severity="Very High",
    )
]

Finding を追加する場合は、必ず重大度（severity）を追加してください: "Very High", "High", "Medium", "Low", "Very Low"。

脅威データベース

セキュリティ実務者の方は、TM.threatsFile を設定することで独自の脅威ファイルを指定できます。このファイルには、次のようなエントリを含める必要があります:```json { "SID":"INP01", "target": ["Lambda","Process"], "description": "Buffer Overflow via Environment Variables", "details": "This attack pattern involves causing a buffer overflow through manipulation of environment variables. Once the attacker finds that they can modify an environment variable, they may try to overflow associated buffers. This attack leverages implicit trust often placed in environment variables.", "Likelihood Of Attack": "High", "severity": "High", "condition": "target.usesEnvironmentVariables is True and target.controls.sanitizesInput is False and target.controls.checksInputBounds is False", "prerequisites": "The application uses environment variables.An environment variable exposed to the user is vulnerable to a buffer overflow.The vulnerable environment variable uses untrusted data.Tainted data used in the environment variables is not properly validated. For instance boundary checking is not done before copying the input data to a buffer.", "mitigations": "Do not expose environment variable to the user.Do not use untrusted data in your environment variables. Use a language or compiler that performs automatic bounds checking. There are tools such as Sharefuzz [R.10.3] which is an environment variable fuzzer for Unix that support loading a shared library. You can use Sharefuzz to determine if you are exposing an environment variable vulnerable to buffer overflow.", "example": "Attack Example: Buffer Overflow in $HOME A buffer overflow in sccw allows local users to gain root access via the $HOME environmental variable. Attack Example: Buffer Overflow in TERM A buffer overflow in the rlogin program involves its consumption of the TERM environmental variable.", "references": "https://capec.mitre.org/data/definitions/10.html, CVE-1999-0906, CVE-1999-0046, http://cwe.mitre.org/data/definitions/120.html, http://cwe.mitre.org/data/definitions/119.html, http://cwe.mitre.org/data/definitions/680.html" }

`target` フィールドは、この脅威を照合する対象となるモデル要素のクラスをリストします。
これらはアセットにすることができます。例: Actor、Datastore、Server、Process、SetOfProcesses、ExternalEntity、
Lambda、LLM、Agent または Element（基本クラスで任意の要素に一致）です。また、2つのアセットを接続する Dataflow にすることもできます。

他のすべてのフィールド（`condition` を除く）は表示用に利用でき、テンプレートで
最終 [レポート](#report) に検出結果を列挙するために使用できます。

> **警告**
>
> `threats.json` ファイルには `eval()` で実行される文字列が含まれています。ファイルに正しい権限があることを確認してください。
> そうしないと、攻撃者が文字列を変更し、あなたの権限でコードを実行させるリスクがあります。

ロジックは `condition` 内にあり、`target` のメンバーを論理的に評価できます。
true を返すとルールが検出結果を生成し、それ以外の場合は検出結果になりません。
条件は `target` の属性や 'target.control' の制御属性を比較でき、さらに次のいずれかのメソッドを呼び出すこともできます:

* `target.oneOf(class, ...)` ここで `class` は次の1つ以上: Actor、Datastore、Server、Process、SetOfProcesses、ExternalEntity、Lambda、LLM、Agent または Dataflow,
* `target.crosses(Boundary)`,
* `target.enters(Boundary)`,
* `target.exits(Boundary)`,
* `target.inside(Boundary)`.

`target` が Dataflow の場合、他の属性に加えて `target.source` や `target.sink` にアクセスできることを覚えておいてください。

アセットに対する条件は、次の属性を検査することで、すべての着信および発信 Dataflow を分析できます:
`target.input` 属性と `target.output` 属性。たとえば、脅威を着信トラフィックのあるサーバーにのみ照合するには、
`any(target.inputs)` を使用します。より高度な例として、
SQL データストアに接続する要素を照合するには、`any(f.sink.oneOf(Datastore) and f.sink.type == DatastoreType.SQL for f in target.outputs)` を使用します。

## JSON からのインポート

少しの Python コードで、JSON から脅威モデルをインポートすることができます（`tests/input.json` にある例の特別な形式に注意してください）。次の例は、tests にある `input.json` の例をインポートします。次のコードを `tm2.py` として保存してください。```python

#!/usr/bin/env python3
# Example tm2.py contents
# Run: python tm2.py --dfd | dot -Tpng -o sample_json.png

from pytm import (
    TM,
    Actor,
    Boundary,
    Classification,
    Data,
    Dataflow,
    Datastore,
    Lambda,
    Server,
    DatastoreType,
    Assumption,
    load,
)

json_file_string = './tests/input.json'
with open(json_file_string) as input_json:
    TM.reset()
    tm = load(input_json)
    tm.process()

以前と同じ方法で tm2.py を呼び出せます。ここでは --dfd を付けて、出力を Graphviz (dot) にリダイレクトします:```bash

python tm2.py --dfd | dot -Tpng -o sample_json.png

## スライドの作成！

脅威モデルが完成して準備が整うと、いよいよ厄介なプレゼンテーションの段階がやってきます。しかし、今や pytm もそこで役立ちます。(RevealMD)[https://github.com/webpro/reveal-md] の力を借りて、脅威モデルをスライドで表現するテンプレートが用意されています。docs/revealjs.md テンプレートを使用するだけで、完全にカスタマイズ可能で、ブラウザからプレゼンテーションして共有できる、見栄えの良いスライドが作成できます。



https://github.com/izar/pytm/assets/368769/30218241-c7cc-4085-91e9-bbec2843f838



## 現在サポートされている脅威```text
INP01 - Buffer Overflow via Environment Variables
INP02 - Overflow Buffers
INP03 - Server Side Include (SSI) Injection
CR01 - Session Sidejacking
INP04 - HTTP Request Splitting
CR02 - Cross Site Tracing
INP05 - Command Line Execution through SQL Injection
INP06 - SQL Injection through SOAP Parameter Tampering
SC01 - JSON Hijacking (aka JavaScript Hijacking)
LB01 - API Manipulation
AA01 - Authentication Abuse/ByPass
DS01 - Excavation
DE01 - Interception
DE02 - Double Encoding
API01 - Exploit Test APIs
AC01 - Privilege Abuse
INP07 - Buffer Manipulation
AC02 - Shared Data Manipulation
DO01 - Flooding
HA01 - Path Traversal
AC03 - Subverting Environment Variable Values
DO02 - Excessive Allocation
DS02 - Try All Common Switches
INP08 - Format String Injection
INP09 - LDAP Injection
INP10 - Parameter Injection
INP11 - Relative Path Traversal
INP12 - Client-side Injection-induced Buffer Overflow
AC04 - XML Schema Poisoning
DO03 - XML Ping of the Death
AC05 - Content Spoofing
INP13 - Command Delimiters
INP14 - Input Data Manipulation
DE03 - Sniffing Attacks
CR03 - Dictionary-based Password Attack
API02 - Exploit Script-Based APIs
HA02 - White Box Reverse Engineering
DS03 - Footprinting
AC06 - Using Malicious Files
HA03 - Web Application Fingerprinting
SC02 - XSS Targeting Non-Script Elements
AC07 - Exploiting Incorrectly Configured Access Control Security Levels
INP15 - IMAP/SMTP Command Injection
HA04 - Reverse Engineering
SC03 - Embedding Scripts within Scripts
INP16 - PHP Remote File Inclusion
AA02 - Principal Spoof
CR04 - Session Credential Falsification through Forging
DO04 - XML Entity Expansion
DS04 - XSS Targeting Error Pages
SC04 - XSS Using Alternate Syntax
CR05 - Encryption Brute Forcing
AC08 - Manipulate Registry Information
DS05 - Lifting Sensitive Data Embedded in Cache
SC05 - Removing Important Client Functionality
INP17 - XSS Using MIME Type Mismatch
AA03 - Exploitation of Trusted Credentials
AC09 - Functionality Misuse
INP18 - Fuzzing and observing application log data/errors for application mapping
CR06 - Communication Channel Manipulation
AC10 - Exploiting Incorrectly Configured SSL
CR07 - XML Routing Detour Attacks
AA04 - Exploiting Trust in Client
CR08 - Client-Server Protocol Manipulation
INP19 - XML External Entities Blowup
INP20 - iFrame Overlay
AC11 - Session Credential Falsification through Manipulation
INP21 - DTD Injection
INP22 - XML Attribute Blowup
INP23 - File Content Injection
DO05 - XML Nested Payloads
AC12 - Privilege Escalation
AC13 - Hijacking a privileged process
AC14 - Catching exception throw/signal from privileged block
INP24 - Filter Failure through Buffer Overflow
INP25 - Resource Injection
INP26 - Code Injection
INP27 - XSS Targeting HTML Attributes
INP28 - XSS Targeting URI Placeholders
INP29 - XSS Using Doubled Characters
INP30 - XSS Using Invalid Characters
INP31 - Command Injection
INP32 - XML Injection
INP33 - Remote Code Inclusion
INP34 - SOAP Array Overflow
INP35 - Leverage Alternate Encoding
DE04 - Audit Log Manipulation
AC15 - Schema Poisoning
INP36 - HTTP Response Smuggling
INP37 - HTTP Request Smuggling
INP38 - DOM-Based XSS
AC16 - Session Credential Falsification through Prediction
INP39 - Reflected XSS
INP40 - Stored XSS
AC17 - Session Hijacking - ServerSide
AC18 - Session Hijacking - ClientSide
INP41 - Argument Injection
AC19 - Reusing Session IDs (aka Session Replay) - ServerSide
AC20 - Reusing Session IDs (aka Session Replay) - ClientSide
AC21 - Cross Site Request Forgery
DS06 - Data Leak
DR01 - Unprotected Sensitive Data
AC22 - Credentials Aging (deprecated)
AC23 - Credentials Disclosure
AC24 - Use of hardcoded credentials
LLM01 - Direct Prompt Injection
LLM02 - Indirect Prompt Injection via Retrieved Content
LLM03 - Sensitive Data Leakage to Third-Party Provider
LLM04 - Training Data Poisoning
LLM05 - Excessive Agency via Unauthorized Tool Use
LLM06 - Arbitrary Code Execution via LLM Agent
LLM07 - Jailbreaking and Safety Bypass
LLM08 - Sensitive Information Disclosure Through Output
LLM09 - Untrusted Tool Launch Configuration

pytm

人気

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

はじめに

特徴

必要条件

はじめに

do this only once

call this after every change in your model

図の生成

レポートの作成

Findings

{{item.name}}

脅威データベース