Clone notice. This repository is an independently maintained clone of OWASP Threat Dragon, maintained by Paschoal Diniz. It is not a GitHub fork of the upstream project. It's an applied AppSec portfolio project: the description below of Threat Dragon itself is the upstream OWASP project's work, credited throughout this README. The addition made specifically in this clone is the AI Threat Report feature covered in the security note further down. General Threat Dragon documentation, releases, and community links in this README point at the upstream OWASP project; issues, PRs, and questions about this clone's own changes belong in this repository's issue tracker.
OWASP Threat Dragon is a free, open-source, cross-platform threat modeling application. It is used to draw threat modeling diagrams and to list threats for elements in the diagram. Mike Goodwin created Threat Dragon as an open source community project that provides an intuitive and accessible way to model threats.
Threat Dragon is designed to be accessible for various types of teams, with an emphasis on flexibility and simplicity. The Project has OWASP Production status and follows the values and principles of the threat modeling manifesto.
This program is free software: you can redistribute it and/or modify it under the terms of the Apache 2.0 License.
⚠️ Security note — AI Threat Report (optional feature). Threat Dragon can optionally send a diagram (its rendered image and its structured model) to an external LLM provider to generate an advisory threat report. A threat model is a map of an application's weaknesses and keeps much of that value to an attacker even when anonymized. Only enable this if you understand and accept that exposure:
- Prefer a local / self-hosted LLM on your own network so diagram data never leaves your perimeter. For hosted providers, require a no-training data policy and a data-processing agreement, and check data residency (LGPD/GDPR).
- Ensure valid end-to-end HTTPS/TLS so the image and model are encrypted in transit. A missing or misconfigured certificate exposes this data to interception.
- In corporate environments, make this a security-team decision. An operator who enables the feature without understanding the exposure — or who misconfigures TLS — can leak sensitive software-architecture information to third parties.
Access the latest version of Threat Dragon on the demo website and refer to the documentation pages.
Also well worth watching the video provided by the OWASP Spotlight series.
The github release area contains Threat Dragon from version 1.3 to the latest versions 2.x. Previous releases are from Mike Goodwin's original repository.
There is a good overview of threat modeling and risk assessment from OWASP, and this expands on what the Threat Dragon project aims for:
- ease of use and accessible
- designing a data flow diagram
- suggesting threats
- entering mitigations and counter measures
Mike Goodwin is the founder and creator of this project, and this repository has been migrated from Mike Goodwin's original which has the issues and pull requests from October 2015 up to June 2020.
Threat Dragon is primarily a web application. The web application can store threat model files on the local filesystem; in addition access can be configured for :
- GitHub
- Bitbucket
- GitLab
- Github Enterprise
The desktop versions of Threat Dragon stores the threat model files on the local filesystem and do not access external repositories. You can download installers for Windows, MacOS and Linux.
End user help is available for both the latest version 2.x and the previous version 1.x.
Threat Dragon was originally written using AngularJS version 1.x, but this version of Angular reached end of life. This means that versions 1.x of Threat Dragon are no longer actively maintained and versions 2.x have been re-written to use Vue.js.
For more information on building/running version 1.x, please see the legacy-v1.x branch.
Install git and node.js which includes the node package manager npm
Clone this repository using: git clone https://github.com/kbcasurf/threat-dragon-ai.git
(or the upstream OWASP repository if you want the original project without the
AI Threat Report feature)
This downloads the code into a threat-dragon-ai directory and the application code is in two sub-folders,
one for the back-end application (td.server) and one for the front-end (td.vue).
Install from the top directory of the project using : npm install
The web application variant of Threat Dragon requires some environment variables; follow the documentation on how to set these variables.
If access to external repositories is required, such as Bitbucket / GitHub / GitLab, then you need to go to your repository account and register the application. There are step by step guides on how to do this for Bitbucket, GitHub and GitLab.
When running on Windows, and during development, the front-end and server back-end
can be started separately in "watch" mode using commands : npm run dev:server and npm run dev:vue.
Alternatively, if running on Linux or MacOS, start both the back-end server and the front-end application
from the top directory using : npm start.
With both front and back end running, access with a browser at http://localhost:8080/
If using npm start, stop both the back-end server and the front-end application
from the top directory with command npm stop. Otherwise break out of both the server and vue front-end.
This clone publishes a docker image containing the AI Threat Report feature to
the GitHub Container Registry on every push to main, tagged latest:
docker pull ghcr.io/kbcasurf/threat-dragon-ai:latest- For MacOS and Linux:
docker run -it --rm -p 8080:3000 -v $(pwd)/.env:/app/.env ghcr.io/kbcasurf/threat-dragon-ai:latest- For Windows:
docker run -it --rm -p 8080:3000 -v %CD%/.env:/app/.env ghcr.io/kbcasurf/threat-dragon-ai:latest
Assuming that you are using http port 8080 and accessing Threat Dragon on http://localhost:8080/.
If you want the official upstream images instead (without the AI Threat Report feature), see the upstream OWASP project.
docker-compose.yml at the top of the repo runs the same GHCR image behind a
Caddy reverse proxy on ports 80/443. Configure your environment using
dotenv, then from the top directory of the project:
docker compose up -d
This pulls ghcr.io/kbcasurf/threat-dragon-ai:latest and terminates TLS via
Caddy using the Caddyfile in this directory.
To run Threat Dragon in a docker container that has been built locally, first configure your environment using dotenv and run from the top directory of the project:
docker build -t owasp-threat-dragon:dev .docker run -it --rm -p 8080:3000 -v $(pwd)/.env:/app/.env owasp-threat-dragon:dev- or if using Windows:
docker run -it --rm -p 8080:3000 -v %CD%/.env:/app/.env owasp-threat-dragon:dev
Using http port 8080 and accessing Threat Dragon on http://localhost:8080/.
td.server/src/app.js sets app.set('trust proxy', true), which tells Express to
trust the entire X-Forwarded-* header chain unconditionally. If you deploy Threat
Dragon behind your own reverse proxy (nginx, Traefik, Caddy, an ALB/load balancer,
etc.), this setting means the app trusts X-Forwarded-For from anyone — including a
client that sets the header itself — which lets a malicious client spoof its
apparent IP and bypass the app's IP-based rate limiting. express-rate-limit
itself flags this configuration as unsafe (ERR_ERL_PERMISSIVE_TRUST_PROXY).
Before deploying behind a reverse proxy, a system administrator should change this
line to match the actual network topology — for example app.set('trust proxy', 1)
to trust exactly one hop (the proxy directly in front of the app), or a specific
IP/CIDR value identifying the proxy, rather than the permissive true. See the
Express trust proxy documentation and the
express-rate-limit guidance on this error for how to pick the
right value for your setup.
Pull requests, feature requests, bug reports and feedback of any kind are very welcome, please refer to the page for contributors.
There are some developer notes to help get started with this project. We are trying to keep the test coverage relatively high so include tests in your pull requests.
For questions, bugs, or feedback about this clone specifically — including the AI Threat Report feature — please open an issue in this repository.
For the upstream Threat Dragon project, the easiest way to get in contact with the community is by emailing the OWASP google group. The OWASP Slack channel #project-threat-dragon is a good source of information, although you may need to subscribe first.
You can follow the Threat Dragon on Bluesky.
If you find a vulnerability introduced by this clone (the AI Threat Report feature, the local Caddy/TLS tooling, or anything else changed here), please open a security advisory on this repository rather than the upstream project's.
For vulnerabilities in the upstream Threat Dragon codebase, please let the OWASP project know ASAP so it can be fixed as a priority — see the upstream security policy.
This clone is maintained by Paschoal Diniz.
Upstream OWASP Threat Dragon is led by:
Threat Dragon: making threat modeling less threatening