izar/pytmUn framework pitónico para el modelado de amenazas
El modelado de amenazas tradicional a menudo llega tarde a la fiesta, o a veces no llega en absoluto. Además, crear flujos de datos e informes manuales puede ser extremadamente lento. El objetivo de pytm es desplazar el modelado de amenazas hacia la izquierda, haciéndolo más automatizado y centrado en el desarrollador.
Basado en su entrada y definición del diseño arquitectónico, pytm puede generar automáticamente los siguientes elementos:
El archivo tm.py es un modelo de ejemplo. Puede ejecutarlo para generar el informe y los archivos de imagen del diagrama a los que hace referencia:```
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
También hay un ejemplo `Makefile` que envuelve todo esto en objetivos que pueden ser fácilmente compartidos para múltiples modelos. Si tienes [GNU make](https://www.gnu.org/software/make/) instalado (disponible por defecto en distribuciones Linux pero no en OSX), simplemente ejecuta:```
make MODEL=the_name_of_your_model_minus_.py
Debe tener plantuml.jar en el mismo directorio que su modelo, o establecer PLANTUML_PATH. Para evitar instalar todas las dependencias, como pandoc o Java, el script se puede ejecutar dentro de un contenedor:```
export USE_DOCKER=true make image
make
### Primeros pasos - Variante Devbox
Para simplificar el uso de `pytm`, las dependencias del host pueden aislarse completamente usando [`Devbox`](https://github.com/jetify-com/devbox). Esto suele ser una alternativa de menor sobrecarga y más conveniente que el enfoque de contenedor OCI.
- Instala Devbox en Linux/MacOS: `curl -fsSL https://get.jetify.com/devbox | bash`
- Instala Devbox en [Windows/WSL](https://www.jetify.com/docs/devbox/installing-devbox/index#installing-wsl2)
- Actualiza a la última versión de devbox: `devbox version update`
- Establece tu token de acceso de GitHub en el archivo `~/.config/nix/nix.conf`: `access-tokens = github.com=YOUR_TOKEN_HERE`
- Crea un nuevo entorno de shell aislado que incluya todas las herramientas y paquetes especificados en el archivo `devbox.json` del proyecto: `devbox shell`
- Muestra la ruta completa al ejecutable de Python que se usará cuando simplemente escribas `python` en tu terminal usando el comando `which python`. La salida debe ser la siguiente ruta: `.devbox/nix/profile/default/bin/python`
- Prueba ejecutando el siguiente comando, que debería generar un DFD como un archivo PNG llamado `sample.png`: `./tm.py --dfd | dot -Tpng -o sample.png`
- Sal del entorno de shell de Devbox: `exit`
## Uso
Todos los argumentos disponibles:```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
El argumento stale_days intenta determinar qué tan separados en días están el script del modelo (que estás escribiendo) del código que implementa el sistema modelado. Idealmente, deberían estar bastante cerca en la mayoría de los casos de un sistema en desarrollo activo. Puedes ejecutar esto periódicamente para medir el pulso de tu proyecto y la 'frescura' de tu modelo de amenazas.
Los elementos actualmente disponibles son: TM, Element, Server, ExternalEntity, Datastore, Actor, Process, SetOfProcesses, Dataflow, Boundary, Lambda, LLM y Agent.
Las propiedades disponibles de un elemento se pueden listar usando --describe seguido del nombre de un elemento:```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
El argumento *colormap*, usado junto con *dfd*, genera un DFD codificado por colores donde los elementos se pintan de rojo, amarillo o verde según su nivel de riesgo (identificado mediante la ejecución de las reglas).
## Uso - Variante Devbox
- `devbox shell`
- `pytm` uso como de costumbre
- `exit`
## Creación de un Modelo de Amenazas
El siguiente es un archivo `tm.py` de ejemplo que describe una aplicación simple donde un Usuario inicia sesión en la aplicación y publica comentarios en ella. El servidor de la aplicación almacena esos comentarios en la base de datos. Hay una función AWS Lambda que limpia periódicamente la base de datos.```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()
También tienes la opción de usar pytmGPT para crear tus modelos a partir de prosa!
Cuando se pasa el argumento --dfd al archivo tm.py anterior, genera salida en stdout, que se alimenta a dot de Graphviz para generar el Diagrama de Flujo de Datos:```bash
tm.py --dfd | dot -Tpng -o sample.png
Genera este diagrama:
dfd.png
Agregar atributos ".levels = [1,2]" a un elemento hará que este (y sus Dataflows asociados si ambos extremos del flujo están en el mismo nivel DFD) se rendericen (o no) dependiendo del argumento de comando "--levels 1 2".
El siguiente comando genera un diagrama de Secuencia.```bash
tm.py --seq | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > seq.png
Genera este diagrama:
seq.png
Los diagramas y hallazgos pueden incluirse en la plantilla para crear un informe final:```bash
tm.py --report docs/basic_template.md | pandoc -f markdown -t html > report.html
El formato de plantilla utilizado en la plantilla de informe es muy simple:```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}}"
}
Para agrupar hallazgos por elementos, usa un bucle anidado más avanzado:```text
{elements🔁{{item.findings:if:
{{item.findings🔁 Threat: {{{{item.id}}}} - {{{{item.description}}}}
Severity: {{{{item.severity}}}}
Mitigations: {{{{item.mitigations}}}}
References: {{{{item.references}}}}
}}}}}
Todos los elementos dentro de un bucle deben escaparse, duplicando las llaves, así que `{item.name}` se convierte en `{{item.name}}`.
El ejemplo anterior usa dos bucles anidados, por lo que los elementos del bucle interno deben escaparse dos veces, por eso usan cuatro llaves.
### Anulaciones
Puede anular atributos de hallazgos (amenazas que coinciden con los activos del modelo y/o flujos de datos), por ejemplo, para establecer una puntuación CVSS personalizada y/o texto de respuesta:```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",
)
]
Si está agregando un Hallazgo, asegúrese de agregar una severidad: "Muy Alta", "Alta", "Media", "Baja", "Muy Baja".
Para el profesional de seguridad, puede proporcionar su propio archivo de amenazas configurando TM.threatsFile. Debe contener entradas como:```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"
}
El campo `target` enumera las clases de elementos del modelo contra los que se emparejará esta amenaza. Estas pueden ser activos, como: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, Lambda, LLM, Agent o Element, que es la clase base y coincide con cualquiera. También puede ser un Dataflow que conecte dos activos.
Todos los demás campos (excepto `condition`) están disponibles para su visualización y pueden usarse en la plantilla para listar hallazgos en el [informe](#report) final.
> **WARNING**
>
> El archivo `threats.json` contiene cadenas que se ejecutan mediante `eval()`. Asegúrate de que el archivo tenga los permisos correctos o corres el riesgo de que un atacante modifique las cadenas y te haga ejecutar código en su nombre.
La lógica reside en la `condition`, donde los miembros de `target` pueden ser evaluados lógicamente. Devolver un verdadero significa que la regla genera un hallazgo; de lo contrario, no es un hallazgo. La condición puede comparar atributos de `target` y/o atributos de control de 'target.control' y también llamar a uno de estos métodos:
* `target.oneOf(class, ...)` donde `class` es uno o más: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, Lambda, LLM, Agent o Dataflow,
* `target.crosses(Boundary)`,
* `target.enters(Boundary)`,
* `target.exits(Boundary)`,
* `target.inside(Boundary)`.
Si `target` es un Dataflow, recuerda que puedes acceder a `target.source` y/o `target.sink` junto con otros atributos.
Las condiciones sobre los activos pueden analizar todos los Dataflows entrantes y salientes inspeccionando los atributos `target.input` y `target.output`. Por ejemplo, para emparejar una amenaza solo contra servidores con tráfico entrante, usa `any(target.inputs)`. Un ejemplo más avanzado, emparejando elementos que se conectan a almacenes de datos SQL, sería `any(f.sink.oneOf(Datastore) and f.sink.isSQL for f in target.outputs)`.
## Importing from JSON
Con un poco de código Python es posible importar un modelo de amenazas desde JSON (nota el formato especial en el exmaple que se encuentra en `tests/input.json`). El siguiente ejemplo importa el ejemplo `input.json` encontrado en las pruebas. Guarda el siguiente código como `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()
Podemos llamar a tm2.py de la misma manera que antes, aquí con --dfd y luego redirigir la salida a Graphviz (dot):```bash
python tm2.py --dfd | dot -Tpng -o sample_json.png
## ¡Creando diapositivas!
Una vez que el modelo de amenazas está listo y preparado, llega la temida etapa de presentación, ¡y ahora pytm también puede ayudarte allí, con una plantilla que expresa tu modelo de amenazas en diapositivas, usando el poder de (RevealMD)[https://github.com/webpro/reveal-md]! Simplemente usa la plantilla docs/revealjs.md y obtendrás diapositivas bonitas, totalmente configurables, que puedes presentar y compartir desde tu navegador.
https://github.com/izar/pytm/assets/368769/30218241-c7cc-4085-91e9-bbec2843f838
## Amenazas actualmente compatibles```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