├── .gitignore ├── 404.html ├── Gemfile ├── README.md ├── _config.yml ├── assets └── images │ ├── README.md │ ├── dfd.png │ ├── logo.png │ ├── sample.png │ └── seq.png ├── index.md ├── info.md ├── leaders.md ├── tab_contributors.md ├── tab_diagrams.md ├── tab_models.md ├── tab_report.md ├── tab_threats.md └── tab_usage.md /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__ 2 | env 3 | .vscode 4 | _site/ 5 | -------------------------------------------------------------------------------- /404.html: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | title: 404 - Not Found 4 | layout: col-generic 5 | 6 | --- 7 | 8 |
9 |

10 |

WHOA THAT PAGE CANNOT BE FOUND

11 |

Try the SEARCH function in the main navigation to find something. If you are looking for chapter information, please see Chapters for the correct chapter. For information about OWASP projects see Projects. For common attacks, vulnerabilities, or information about other community-led contributions see Contributed Content.

12 | 13 |
14 |

If all else fails you can search our historical site.

15 |
16 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | group :jekyll_plugins do 3 | gem "github-pages" 4 | end -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OWASP Foundation pytm Homepage 2 | 3 | This repo is the source for the OWASP pytm project web pages at https://owasp.org/www-project-pytm/ 4 | 5 | For any improvements to these pages make sure to open up an issue or a pull request, and we'll make sure to tend to it! 6 | 7 | Please create issues on this repository **only** for content hosted under this subfolder on the OWASP site. 8 | For issues or suggestions related to pytm itself, please use the core 9 | [github](https://github.com/izar/pytm) repository. 10 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | remote_theme: "owasp/www--site-theme@main" 2 | plugins: 3 | - jekyll-include-cache-0.2.0 -------------------------------------------------------------------------------- /assets/images/README.md: -------------------------------------------------------------------------------- 1 | # placeholder 2 | 3 | Put images you wish to link to in this folder 4 | 5 | link would be in form assets/images/ 6 | -------------------------------------------------------------------------------- /assets/images/dfd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OWASP/www-project-pytm/58f473534ba1720fa1771d09c7106b3f3e05d592/assets/images/dfd.png -------------------------------------------------------------------------------- /assets/images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OWASP/www-project-pytm/58f473534ba1720fa1771d09c7106b3f3e05d592/assets/images/logo.png -------------------------------------------------------------------------------- /assets/images/sample.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OWASP/www-project-pytm/58f473534ba1720fa1771d09c7106b3f3e05d592/assets/images/sample.png -------------------------------------------------------------------------------- /assets/images/seq.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OWASP/www-project-pytm/58f473534ba1720fa1771d09c7106b3f3e05d592/assets/images/seq.png -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: OWASP pytm 3 | layout: col-sidebar 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | level: 3 6 | type: tool 7 | --- 8 | 9 | 17 | 18 | ![pytm logo](assets/images/logo.png){: .image-right } 19 | 20 | pytm is a Pythonic framework for threat modeling. 21 | 22 | Define your system in Python using the elements and properties described in the pytm framework. 23 | Based on your definition, pytm can generate, a Data Flow Diagram (DFD), a Sequence Diagram 24 | and most important of all, threats to your system. 25 | -------------------------------------------------------------------------------- /info.md: -------------------------------------------------------------------------------- 1 | ### Project Classification 2 | 3 | * ![Lab Project](/assets/images/common/owasp_level_labs.svg){:width='45px' } 4 | * Builder 5 | 6 | * Tool 7 | 8 | ### External Resources 9 | 10 | * [GitHub](https://github.com/izar/pytm) 11 | * [PyPI](https://pypi.org/project/pytm/) 12 | 13 | ### Licensing 14 | 15 | [MIT](https://github.com/izar/pytm/blob/master/LICENSE) 16 | -------------------------------------------------------------------------------- /leaders.md: -------------------------------------------------------------------------------- 1 | ### Leaders 2 | 3 | * [Izar Tarandach](mailto:) 4 | -------------------------------------------------------------------------------- /tab_contributors.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contributors 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 7 7 | --- 8 | 9 | # PyTM Main Contributors 10 | 11 | * Was, Jan 12 | * Avhad, Pooja 13 | * Coles, Matthew 14 | * Ozmore, Nick 15 | * Shambhuni, Rohit 16 | * Tarandach, Izar 17 | 18 | Join us! 19 | 20 | -------------------------------------------------------------------------------- /tab_diagrams.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Diagrams 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 4 7 | --- 8 | 9 | Diagrams are output as [Dot](https://graphviz.gitlab.io/) and [PlantUML](https://plantuml.com/). 10 | 11 | When `--dfd` argument is passed to the above `tm.py` file it generates output to stdout, which is fed to Graphviz's dot to generate the Data Flow Diagram: 12 | 13 | ```bash 14 | 15 | tm.py --dfd | dot -Tpng -o sample.png 16 | 17 | ``` 18 | 19 | Generates this diagram: 20 | 21 | ![dfd.png](assets/images/dfd.png) 22 | 23 | 24 | The following command generates a Sequence diagram. 25 | 26 | ```bash 27 | 28 | tm.py --seq | java -Djava.awt.headless=true -jar plantuml.jar -tpng -pipe > seq.png 29 | 30 | ``` 31 | 32 | Generates this diagram: 33 | 34 | ![seq.png](assets/images/seq.png) 35 | -------------------------------------------------------------------------------- /tab_models.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Models 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 3 7 | --- 8 | 9 | The following is a sample `tm.py` file that describes a simple application where a User logs into the application 10 | and posts comments on the app. The app server stores those comments into the database. There is an AWS Lambda 11 | that periodically cleans the Database. 12 | 13 | ```python 14 | 15 | #!/usr/bin/env python3 16 | 17 | from pytm.pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda 18 | 19 | tm = TM("my test tm") 20 | tm.description = "another test tm" 21 | tm.isOrdered = True 22 | 23 | User_Web = Boundary("User/Web") 24 | Web_DB = Boundary("Web/DB") 25 | 26 | user = Actor("User") 27 | user.inBoundary = User_Web 28 | 29 | web = Server("Web Server") 30 | web.OS = "CloudOS" 31 | web.isHardened = True 32 | 33 | db = Datastore("SQL Database (*)") 34 | db.OS = "CentOS" 35 | db.isHardened = False 36 | db.inBoundary = Web_DB 37 | db.isSql = True 38 | db.inScope = False 39 | 40 | my_lambda = Lambda("cleanDBevery6hours") 41 | my_lambda.hasAccessControl = True 42 | my_lambda.inBoundary = Web_DB 43 | 44 | my_lambda_to_db = Dataflow(my_lambda, db, "(λ)Periodically cleans DB") 45 | my_lambda_to_db.protocol = "SQL" 46 | my_lambda_to_db.dstPort = 3306 47 | 48 | user_to_web = Dataflow(user, web, "User enters comments (*)") 49 | user_to_web.protocol = "HTTP" 50 | user_to_web.dstPort = 80 51 | user_to_web.data = 'Comments in HTML or Markdown' 52 | 53 | web_to_user = Dataflow(web, user, "Comments saved (*)") 54 | web_to_user.protocol = "HTTP" 55 | web_to_user.data = 'Ack of saving or error message, in JSON' 56 | 57 | web_to_db = Dataflow(web, db, "Insert query with comments") 58 | web_to_db.protocol = "MySQL" 59 | web_to_db.dstPort = 3306 60 | web_to_db.data = 'MySQL insert statement, all literals' 61 | 62 | db_to_web = Dataflow(db, web, "Comments contents") 63 | db_to_web.protocol = "MySQL" 64 | db_to_web.data = 'Results of insert op' 65 | 66 | tm.process() 67 | 68 | ``` 69 | -------------------------------------------------------------------------------- /tab_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Report 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 5 7 | --- 8 | 9 | The diagrams and findings can be included in the template to create a final report: 10 | 11 | ```bash 12 | 13 | tm.py --report docs/template.md | pandoc -f markdown -t html > report.html 14 | 15 | ``` 16 | The templating format used in the report template is very simple: 17 | 18 | ```text 19 | 20 | # Threat Model Sample 21 | *** 22 | 23 | ## System Description 24 | 25 | {tm.description} 26 | 27 | ## Dataflow Diagram 28 | 29 | ![Level 0 DFD](dfd.png) 30 | 31 | ## Dataflows 32 | 33 | Name|From|To |Data|Protocol|Port 34 | ----|----|---|----|--------|---- 35 | {dataflows:repeat:{{item.name}}|{{item.source.name}}|{{item.sink.name}}|{{item.data}}|{{item.protocol}}|{{item.dstPort}} 36 | } 37 | 38 | ## Findings 39 | 40 | {findings:repeat:* {{item.description}} on element "{{item.target}}" 41 | } 42 | 43 | ``` 44 | 45 | To group findings by elements, use a more advanced, nested loop: 46 | 47 | ```text 48 | ## Findings 49 | 50 | {elements:repeat:{{item.findings:if: 51 | ### {{item.name}} 52 | 53 | {{item.findings:repeat: 54 | **Threat**: {{{{item.id}}}} - {{{{item.description}}}} 55 | 56 | **Severity**: {{{{item.severity}}}} 57 | 58 | **Mitigations**: {{{{item.mitigations}}}} 59 | 60 | **References**: {{{{item.references}}}} 61 | 62 | }}}}} 63 | ``` 64 | 65 | All items inside a loop must be escaped, doubling the braces, so `{item.name}` becomes `{{item.name}}`. 66 | The example above uses two nested loops, so items in the inner loop must be escaped twice, that's why they're using four braces. 67 | -------------------------------------------------------------------------------- /tab_threats.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Threats 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 6 7 | --- 8 | 9 | For the security practitioner, you may supply your own threats file by setting `TM.threatsFile`. It should contain entries like: 10 | 11 | ```json 12 | { 13 | "SID":"INP01", 14 | "target": ["Lambda","Process"], 15 | "description": "Buffer Overflow via Environment Variables", 16 | "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.", 17 | "Likelihood Of Attack": "High", 18 | "severity": "High", 19 | "condition": "target.usesEnvironmentVariables is True and target.sanitizesInput is False and target.checksInputBounds is False", 20 | "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.", 21 | "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.", 22 | "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.", 23 | "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" 24 | } 25 | ``` 26 | 27 | The `target` field lists classes of model elements to match this threat against. 28 | Those can be assets, like: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, 29 | Lambda or Element, which is the base class and matches any. It can also be a Dataflow that connects two assets. 30 | 31 | All other fields (except `condition`) are available for display and can be used in the template 32 | to list findings in the final [report](#div-report). 33 | 34 | > **WARNING** 35 | > 36 | > The `threats.json` file contains strings that run through `eval()`. Make sure the file has correct permissions 37 | > or risk having an attacker change the strings and cause you to run code on their behalf. 38 | 39 | The logic lives in the `condition`, where members of `target` can be logically evaluated. 40 | Returning a true means the rule generates a finding, otherwise, it is not a finding. 41 | Condition may compare attributes of `target` and also call one of these methods: 42 | 43 | * `target.oneOf(class, ...)` where `class` is one or more: Actor, Datastore, Server, Process, SetOfProcesses, ExternalEntity, Lambda or Dataflow, 44 | * `target.crosses(Boundary)`, 45 | * `target.enters(Boundary)`, 46 | * `target.exits(Boundary)`, 47 | * `target.inside(Boundary)`. 48 | 49 | If `target` is a Dataflow, remember you can access `target.source` and/or `target.sink` along with other attributes. 50 | 51 | Conditions on assets can analyze all incoming and outgoing Dataflows by inspecting 52 | the `target.input` and `target.output` attributes. For example, to match a threat only against 53 | servers with incoming traffic, use `any(target.inputs)`. A more advanced example, 54 | matching elements connecting to SQL datastores, would be `any(f.sink.oneOf(Datastore) and f.sink.isSQL for f in target.outputs)`. 55 | 56 | Currently supported threats: 57 | 58 | ```text 59 | INP01 - Buffer Overflow via Environment Variables 60 | INP02 - Overflow Buffers 61 | INP03 - Server Side Include (SSI) Injection 62 | CR01 - Session Sidejacking 63 | INP04 - HTTP Request Splitting 64 | CR02 - Cross Site Tracing 65 | INP05 - Command Line Execution through SQL Injection 66 | INP06 - SQL Injection through SOAP Parameter Tampering 67 | SC01 - JSON Hijacking (aka JavaScript Hijacking) 68 | LB01 - API Manipulation 69 | AA01 - Authentication Abuse/ByPass 70 | DS01 - Excavation 71 | DE01 - Interception 72 | DE02 - Double Encoding 73 | API01 - Exploit Test APIs 74 | AC01 - Privilege Abuse 75 | INP07 - Buffer Manipulation 76 | AC02 - Shared Data Manipulation 77 | DO01 - Flooding 78 | HA01 - Path Traversal 79 | AC03 - Subverting Environment Variable Values 80 | DO02 - Excessive Allocation 81 | DS02 - Try All Common Switches 82 | INP08 - Format String Injection 83 | INP09 - LDAP Injection 84 | INP10 - Parameter Injection 85 | INP11 - Relative Path Traversal 86 | INP12 - Client-side Injection-induced Buffer Overflow 87 | AC04 - XML Schema Poisoning 88 | DO03 - XML Ping of the Death 89 | AC05 - Content Spoofing 90 | INP13 - Command Delimiters 91 | INP14 - Input Data Manipulation 92 | DE03 - Sniffing Attacks 93 | CR03 - Dictionary-based Password Attack 94 | API02 - Exploit Script-Based APIs 95 | HA02 - White Box Reverse Engineering 96 | DS03 - Footprinting 97 | AC06 - Using Malicious Files 98 | HA03 - Web Application Fingerprinting 99 | SC02 - XSS Targeting Non-Script Elements 100 | AC07 - Exploiting Incorrectly Configured Access Control Security Levels 101 | INP15 - IMAP/SMTP Command Injection 102 | HA04 - Reverse Engineering 103 | SC03 - Embedding Scripts within Scripts 104 | INP16 - PHP Remote File Inclusion 105 | AA02 - Principal Spoof 106 | CR04 - Session Credential Falsification through Forging 107 | DO04 - XML Entity Expansion 108 | DS04 - XSS Targeting Error Pages 109 | SC04 - XSS Using Alternate Syntax 110 | CR05 - Encryption Brute Forcing 111 | AC08 - Manipulate Registry Information 112 | DS05 - Lifting Sensitive Data Embedded in Cache 113 | SC05 - Removing Important Client Functionality 114 | INP17 - XSS Using MIME Type Mismatch 115 | AA03 - Exploitation of Trusted Credentials 116 | AC09 - Functionality Misuse 117 | INP18 - Fuzzing and observing application log data/errors for application mapping 118 | CR06 - Communication Channel Manipulation 119 | AC10 - Exploiting Incorrectly Configured SSL 120 | CR07 - XML Routing Detour Attacks 121 | AA04 - Exploiting Trust in Client 122 | CR08 - Client-Server Protocol Manipulation 123 | INP19 - XML External Entities Blowup 124 | INP20 - iFrame Overlay 125 | AC11 - Session Credential Falsification through Manipulation 126 | INP21 - DTD Injection 127 | INP22 - XML Attribute Blowup 128 | INP23 - File Content Injection 129 | DO05 - XML Nested Payloads 130 | AC12 - Privilege Escalation 131 | AC13 - Hijacking a privileged process 132 | AC14 - Catching exception throw/signal from privileged block 133 | INP24 - Filter Failure through Buffer Overflow 134 | INP25 - Resource Injection 135 | INP26 - Code Injection 136 | INP27 - XSS Targeting HTML Attributes 137 | INP28 - XSS Targeting URI Placeholders 138 | INP29 - XSS Using Doubled Characters 139 | INP30 - XSS Using Invalid Characters 140 | INP31 - Command Injection 141 | INP32 - XML Injection 142 | INP33 - Remote Code Inclusion 143 | INP34 - SOAP Array Overflow 144 | INP35 - Leverage Alternate Encoding 145 | DE04 - Audit Log Manipulation 146 | AC15 - Schema Poisoning 147 | INP36 - HTTP Response Smuggling 148 | INP37 - HTTP Request Smuggling 149 | INP38 - DOM-Based XSS 150 | AC16 - Session Credential Falsification through Prediction 151 | INP39 - Reflected XSS 152 | INP40 - Stored XSS 153 | AC17 - Session Hijacking - ServerSide 154 | AC18 - Session Hijacking - ClientSide 155 | INP41 - Argument Injection 156 | AC19 - Reusing Session IDs (aka Session Replay) - ServerSide 157 | AC20 - Reusing Session IDs (aka Session Replay) - ClientSide 158 | AC21 - Cross Site Request Forgery 159 | 160 | 161 | 162 | ``` 163 | -------------------------------------------------------------------------------- /tab_usage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Usage 3 | layout: null 4 | tags: threat-modeling threat modeling dataflow-diagram dataflow diagram python graphviz plantuml 5 | tab: true 6 | order: 2 7 | --- 8 | 9 | Requirements: 10 | 11 | * Linux/MacOS 12 | * Python 3.x 13 | * Graphviz package 14 | * Java (OpenJDK 10 or 11) 15 | * [plantuml.jar](http://sourceforge.net/projects/plantuml/files/plantuml.jar/download) 16 | 17 | ```text 18 | tm.py [-h] [--debug] [--dfd] [--report REPORT] [--exclude EXCLUDE] [--seq] [--list] [--describe DESCRIBE] 19 | 20 | optional arguments: 21 | -h, --help show this help message and exit 22 | --debug print debug messages 23 | --dfd output DFD (default) 24 | --report REPORT output report using the named template file (sample template file is under docs/template.md) 25 | --exclude EXCLUDE specify threat IDs to be ignored 26 | --seq output sequential diagram 27 | --list list all available threats 28 | --describe DESCRIBE describe the properties available for a given element 29 | 30 | ``` 31 | 32 | Currently available elements are: TM, Element, Server, ExternalEntity, Datastore, Actor, Process, SetOfProcesses, Dataflow, Boundary and Lambda. 33 | 34 | The available properties of an element can be listed by using `--describe` followed by the name of an element: 35 | 36 | ```text 37 | 38 | (pytm) ➜ pytm git:(master) ✗ ./tm.py --describe Element 39 | Element class attributes: 40 | OS 41 | definesConnectionTimeout default: False 42 | description 43 | handlesResources default: False 44 | implementsAuthenticationScheme default: False 45 | implementsNonce default: False 46 | inBoundary 47 | inScope Is the element in scope of the threat model, default: True 48 | isAdmin default: False 49 | isHardened default: False 50 | name required 51 | onAWS default: False 52 | 53 | ``` 54 | --------------------------------------------------------------------------------