/pytm

name: pytm
description: >
  Python-based threat modeling using pytm library for programmatic STRIDE analysis,
  data flow diagram generation, and automated security threat identification. Use when:
  (1) Creating threat models programmatically using Python code, (2) Generating data flow
  diagrams (DFDs) with automatic STRIDE threat identification, (3) Integrating threat
  modeling into CI/CD pipelines and shift-left security practices, (4) Analyzing system
  architecture for security threats across trust boundaries, (5) Producing threat reports
  with STRIDE categories and mitigation recommendations, (6) Maintaining threat models
  as code for version control and automation.
version: 0.1.0
maintainer: SirAppSec
category: threatmodel
tags: [threat-modeling, stride, dfd, security-architecture, pytm, appsec, risk-analysis]
frameworks: [STRIDE, OWASP, MITRE-ATT&CK, NIST]
dependencies:
  python: ">=3.7"
  packages: [pytm, graphviz]
references:
  - https://github.com/izar/pytm
  - https://owasp.org/www-community/Threat_Modeling
  - https://www.microsoft.com/en-us/security/blog/2007/09/11/stride-chart/
  - https://attack.mitre.org/

Threat Modeling with pytm

Overview

pytm is a Python library for programmatic threat modeling based on the STRIDE methodology. It enables security engineers to define system architecture as code, automatically generate data flow diagrams (DFDs), identify security threats across trust boundaries, and produce comprehensive threat reports. This approach integrates threat modeling into CI/CD pipelines, enabling shift-left security and continuous threat analysis.

Quick Start

Create a basic threat model:

#!/usr/bin/env python3
from pytm import TM, Server, Dataflow, Boundary, Actor

# Initialize threat model
tm = TM("Web Application Threat Model")
tm.description = "E-commerce web application"

# Define trust boundaries
internet = Boundary("Internet")
dmz = Boundary("DMZ")
internal = Boundary("Internal Network")

# Define actors and components
user = Actor("Customer")
user.inBoundary = internet

web = Server("Web Server")
web.inBoundary = dmz

db = Server("Database")
db.inBoundary = internal

# Define data flows
user_to_web = Dataflow(user, web, "HTTPS Request")
user_to_web.protocol = "HTTPS"
user_to_web.data = "credentials, payment info"
user_to_web.isEncrypted = True

web_to_db = Dataflow(web, db, "Database Query")
web_to_db.protocol = "SQL/TLS"
web_to_db.data = "user data, transactions"

# Generate threat report and diagram
tm.process()

Install pytm:

pip install pytm
# Also requires graphviz for diagram generation
brew install graphviz  # macOS
# or: apt-get install graphviz  # Linux

Core Workflows

Workflow 1: Create New Threat Model

Progress: [ ] 1. Define system scope and trust boundaries [ ] 2. Identify all actors (users, administrators, external systems) [ ] 3. Map system components (servers, databases, APIs, services) [ ] 4. Define data flows between components with security attributes [ ] 5. Run `tm.process()` to generate threats and DFD [ ] 6. Review STRIDE threats and add mitigations [ ] 7. Generate threat report with `scripts/generate_report.py`

Work through each step systematically. Check off completed items.

Workflow 2: STRIDE Threat Analysis

pytm automatically identifies threats based on STRIDE categories:

• **Spoofing**: Identity impersonation attacks
• **Tampering**: Unauthorized modification of data
• **Repudiation**: Denial of actions without traceability
• **Information Disclosure**: Unauthorized access to sensitive data
• **Denial of Service**: Availability attacks
• **Elevation of Privilege**: Unauthorized access escalation

For each identified threat: 1. Review threat description and affected component 2. Assess likelihood and impact (use `references/risk_matrix.md`) 3. Determine if existing controls mitigate the threat 4. Add mitigation using `threat.mitigation = "description"` 5. Document residual risk and acceptance criteria

Workflow 3: Architecture as Code

Define system architecture programmatically:

from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda

tm = TM("Microservices Architecture")

# Cloud boundaries
internet = Boundary("Internet")
cloud_vpc = Boundary("Cloud VPC")

# API Gateway
api_gateway = Server("API Gateway")
api_gateway.inBoundary = cloud_vpc
api_gateway.implementsAuthentication = True
api_gateway.implementsAuthorization = True

# Microservices
auth_service = Lambda("Auth Service")
auth_service.inBoundary = cloud_vpc

order_service = Lambda("Order Service")
order_service.inBoundary = cloud_vpc

# Data stores
user_db = Datastore("User Database")
user_db.inBoundary = cloud_vpc
user_db.isEncryptedAtRest = True

# Data flows with security properties
client_to_api = Dataflow(Actor("Client"), api_gateway, "API Request")
client_to_api.protocol = "HTTPS"
client_to_api.isEncrypted = True
client_to_api.data = "user credentials, orders"

api_to_auth = Dataflow(api_gateway, auth_service, "Auth Check")
api_to_auth.protocol = "gRPC/TLS"

auth_to_db = Dataflow(auth_service, user_db, "User Lookup")
auth_to_db.protocol = "TLS"

tm.process()

Workflow 4: CI/CD Integration

Automate threat modeling in continuous integration:

# .github/workflows/threat-model.yml
name: Threat Model Analysis
on: [push, pull_request]

jobs:
  threat-model:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install pytm
          sudo apt-get install -y graphviz

      - name: Generate threat model
        run: python threat_model.py

      - name: Upload DFD diagram
        uses: actions/upload-artifact@v3
        with:
          name: threat-model-dfd
          path: '*.png'

      - name: Check for unmitigated threats
        run: python scripts/check_m