owasp/pytmEin pythonisches Framework für die Bedrohungsmodellierung
Traditionelle Bedrohungsmodellierung kommt zu oft zu spät zur Party, oder manchmal gar nicht. Darüber hinaus kann das manuelle Erstellen von Datenflüssen und Berichten äußerst zeitaufwändig sein. Das Ziel von pytm ist es, die Bedrohungsmodellierung nach links zu verschieben, sie automatisierter und entwicklerzentrierter zu gestalten.
Basierend auf Ihren Eingaben und der Definition des architektonischen Designs kann pytm automatisch die folgenden Elemente generieren:
Die Datei tm.py ist ein Beispielmodell. Sie können es ausführen, um den Bericht und die im Modell referenzierten Diagrammbilddateien zu generieren:```
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
Es gibt auch eine Beispiel-`Makefile`, die all dies in Ziele (Targets) verpackt, die leicht für mehrere Modelle gemeinsam genutzt werden können. Wenn Sie [GNU make](https://www.gnu.org/software/make/) installiert haben (standardmäßig auf Linux-Distributionen verfügbar, aber nicht auf OSX), führen Sie einfach aus:```
make MODEL=the_name_of_your_model_minus_.py
Sie sollten entweder plantuml.jar im selben Verzeichnis wie Ihr Modell haben, oder PLANTUML_PATH setzen. Um die Installation aller Abhängigkeiten wie pandoc oder Java zu vermeiden, kann das Skript in einem Container ausgeführt werden:```
export USE_DOCKER=true make image
make
### Erste Schritte - Devbox-Variante
Um die Nutzung von `pytm` zu vereinfachen, können Host-Abhängigkeiten vollständig isoliert werden, indem [`Devbox`](https://github.com/jetify-com/devbox) verwendet wird. Dies ist in der Regel eine weniger aufwändige und bequemere Alternative zum OCI-Container-Ansatz.
- Installieren Sie Devbox auf Linux/MacOS: `curl -fsSL https://get.jetify.com/devbox | bash`
- Installieren Sie Devbox auf [Windows/WSL](https://www.jetify.com/docs/devbox/installing-devbox/index#installing-wsl2)
- Aktualisieren Sie auf die neueste Version von devbox: `devbox version update`
- Legen Sie Ihren GitHub-Zugriffstoken in der Datei `~/.config/nix/nix.conf` fest: `access-tokens = github.com=YOUR_TOKEN_HERE`
- Erstellen Sie eine neue, isolierte Shell-Umgebung, die alle im `devbox.json`-Projekt angegebenen Tools und Pakete enthält: `devbox shell`
- Zeigen Sie den vollständigen Pfad zur Python-ausführbaren Datei an, die verwendet wird, wenn Sie einfach `python` in Ihr Terminal eingeben, indem Sie den Befehl `which python` verwenden. Die Ausgabe sollte der folgende Pfad sein: `.devbox/nix/profile/default/bin/python`
- Testen Sie, indem Sie den folgenden Befehl ausführen, der ein DFD als PNG-Datei mit dem Namen `sample.png` generieren sollte: `./tm.py --dfd | dot -Tpng -o sample.png`
- Beenden Sie die Devbox-Shell-Umgebung: `exit`
## Verwendung
Alle verfügbaren Argumente:```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
Das Argument stale_days versucht zu bestimmen, wie weit in Tagen das Modellskript (das Sie schreiben) von dem Code entfernt ist, der das modellierte System implementiert. Idealerweise sollten sie in den meisten Fällen eines aktiv entwickelten Systems ziemlich nah beieinander liegen. Sie können dies regelmäßig ausführen, um den Puls Ihres Projekts und die 'Frische' Ihres Bedrohungsmodells zu messen.
Derzeit verfügbare Elemente sind: TM, Element, Server, ExternalEntity, Datastore, Actor, Process, SetOfProcesses, Dataflow, Boundary, Lambda, LLM und Agent.
Die verfügbaren Eigenschaften eines Elements können durch Verwendung von --describe gefolgt vom Namen eines Elements aufgelistet werden:```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:
Das *colormap*-Argument, das zusammen mit *dfd* verwendet wird, gibt ein farbcodiertes DFD aus, bei dem die Elemente je nach Risikostufe (ermittelt durch die Ausführung der Regeln) rot, gelb oder grün eingefärbt sind.
## Nutzung - Devbox-Variante
- `devbox shell`
- `pytm` Nutzung wie gewohnt
- `exit`
## Erstellen eines Bedrohungsmodells
Im Folgenden finden Sie eine Beispiel-`tm.py`-Datei, die eine einfache Anwendung beschreibt, bei der ein Benutzer sich in die Anwendung einloggt und Kommentare in der App postet. Der Anwendungsserver speichert diese Kommentare in der Datenbank. Es gibt eine AWS Lambda, die regelmäßig die Datenbank bereinigt.```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, "(λ)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()
Sie haben auch die Möglichkeit, pytmGPT zu verwenden, um Ihre Modelle aus Prosa zu erstellen!
Wenn das Argument --dfd an die obige Datei tm.py übergeben wird, erzeugt sie eine Ausgabe auf stdout, die an Graphviz' dot weitergeleitet wird, um das Datenflussdiagramm zu generieren:```bash
tm.py --dfd | dot -Tpng -o sample.png
Erzeugt dieses Diagramm:
dfd.png
Das Hinzufügen von Attributen ".levels = [1,2]" zu einem Element führt dazu, dass es (und die zugehörigen Dataflows, wenn beide Flussenden in derselben DFD-Ebene sind) je nach Befehlsargument "--levels 1 2" gerendert wird (oder nicht).
Der folgende Befehl erzeugt ein Sequenzdiagramm.```bash
tm.py --seq | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > seq.png
Erzeugt dieses Diagramm:
seq.png
Die Diagramme und Ergebnisse können in die Vorlage eingefügt werden, um einen endgültigen Bericht zu erstellen:```bash
tm.py --report docs/basic_template.md | pandoc -f markdown -t html > report.html
Das Templating-Format, das in der Berichtsvorlage verwendet wird, ist sehr einfach:```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}}"
}
Um Ergebnisse nach Elementen zu gruppieren, verwenden Sie eine erweiterte, verschachtelte Schleife:```text
{elements🔁{{item.findings:if:
{{item.findings🔁 Threat: {{{{item.id}}}} - {{{{item.description}}}}
Severity: {{{{item.severity}}}}
Mitigations: {{{{item.mitigations}}}}
References: {{{{item.references}}}}
}}}}}
Alle Elemente innerhalb einer Schleife müssen escaped werden, indem die geschweiften Klammern verdoppelt werden, also wird `{item.name}` zu `{{item.name}}`.
Das obige Beispiel verwendet zwei verschachtelte Schleifen, daher müssen Elemente in der inneren Schleife zweimal escaped werden, weshalb sie vier geschweifte Klammern verwenden.
### Overrides
Sie können Attribute von Ergebnissen (Bedrohungen, die mit den Modell-Assets und/oder Datenflüssen übereinstimmen) überschreiben, um beispielsweise einen benutzerdefinierten CVSS-Score und/oder Antworttext festzulegen:```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",
)
]
Wenn Sie einen Fund hinzufügen, stellen Sie sicher, dass Sie eine Schweregradstufe hinzufügen: "Very High", "High", "Medium", "Low", "Very Low".
Für den Sicherheitspraktiker können Sie Ihre eigene Bedrohungsdatei bereitstellen, indem Sie TM.threatsFile setzen. Sie sollte Einträge wie folgt enthalten:```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"
}
Das Feld `target` listet Klassen von Modellelementen auf, gegen die diese Bedrohung abgeglichen wird. Dies können Assets sein, wie: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, Lambda, LLM, Agent oder Element, die die Basisklasse ist und auf alles zutrifft. Es kann auch ein Dataflow sein, der zwei Assets verbindet.
Alle anderen Felder (außer `condition`) stehen für die Anzeige zur Verfügung und können in der Vorlage verwendet werden, um Funde im endgültigen [Bericht](#report) aufzulisten.
> **WARNUNG**
>
> Die Datei `threats.json` enthält Zeichenketten, die durch `eval()` ausgeführt werden. Stellen Sie sicher, dass die Datei die richtigen Berechtigungen hat, oder riskieren Sie, dass ein Angreifer die Zeichenketten ändert und Sie dazu bringt, Code in seinem Namen auszuführen.
Die Logik lebt in der `condition`, wo Mitglieder von `target` logisch ausgewertet werden können. Ein Rückgabewert von true bedeutet, dass die Regel einen Fund generiert, andernfalls handelt es sich nicht um einen Fund. Die Condition kann Attribute von `target` und/oder Kontrollattribute von 'target.control' vergleichen und auch eine dieser Methoden aufrufen:
* `target.oneOf(class, ...)` wobei `class` eine oder mehrere ist: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, Lambda, LLM, Agent oder Dataflow,
* `target.crosses(Boundary)`,
* `target.enters(Boundary)`,
* `target.exits(Boundary)`,
* `target.inside(Boundary)`.
Wenn `target` ein Dataflow ist, denken Sie daran, dass Sie auf `target.source` und/oder `target.sink` sowie andere Attribute zugreifen können.
Bedingungen auf Assets können alle eingehenden und ausgehenden Dataflows analysieren, indem sie die Attribute `target.input` und `target.output` inspizieren. Um beispielsweise eine Bedrohung nur gegen Server mit eingehendem Datenverkehr abzugleichen, verwenden Sie `any(target.inputs)`. Ein fortgeschritteneres Beispiel, um Elemente zu erkennen, die mit SQL-Datenspeichern verbunden sind, wäre `any(f.sink.oneOf(Datastore) and f.sink.type == DatastoreType.SQL for f in target.outputs)`.
## Importieren aus JSON
Mit ein wenig Python-Code ist es möglich, ein Bedrohungsmodell aus JSON zu importieren (beachten Sie das spezielle Format im Beispiel in `tests/input.json`). Das folgende Beispiel importiert das in den Tests gefundene Beispiel `input.json`. Speichern Sie den folgenden Code als `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()
Wir können tm2.py auf die gleiche Weise wie zuvor aufrufen, hier mit --dfd und dann die Ausgabe an Graphviz (dot) umleiten:```bash
python tm2.py --dfd | dot -Tpng -o sample_json.png
## Folien erstellen!
Sobald ein Bedrohungsmodell fertig und bereit ist, kommt die gefürchtete Präsentationsphase – und jetzt kann pytm Ihnen auch dabei helfen, mit einer Vorlage, die Ihr Bedrohungsmodell in Folien ausdrückt, und zwar mit der Kraft von (RevealMD)[https://github.com/webpro/reveal-md]! Verwenden Sie einfach die Vorlage docs/revealjs.md und Sie erhalten hübsche, vollständig konfigurierbare Folien, die Sie in Ihrem Browser präsentieren und teilen können.
https://github.com/izar/pytm/assets/368769/30218241-c7cc-4085-91e9-bbec2843f838
## Derzeit unterstützte Bedrohungen```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