Note that this repository has been migrated from Mike Goodwin's original , which has the issues and pull requests from October 2015 up to June 2020.

OWASP Threat Dragon

Threat Dragon is a free, open-source, cross-platform threat modelling application including system diagramming and a threat rule engine to auto-generate threats/mitigations. It is an OWASP Incubator Project and follows the values and principles of the threat modeling manifesto. The roadmap for the project is a simple UX, a powerful rule engine and integration with other development lifecycle tools.

The application comes in two variants:

1. A web application (this repo): For the web application, models files are stored in GitHub (other storage will become available). We are currently maintaining a working protoype in sync with the main code branch.

2. A desktop application: This is based on Electron. There are installers available for both Windows and Mac OSX, as well as rpm and debian packages for Linux. Note that for the desktop variant the models are stored on the local filesystem rather than a remote repository.

End user help is available for both variants.

Installing

Threat Dragon is a Single Page Application (SPA) using Angular on the client and node.js on the server. To build and run locally follow these steps:

Install git and node.js - which includes the node package manager npm. To get the code, navigate to where you want your code to be located and do

• git clone --recursive https://github.com/owasp/threat-dragon.git

This downloads the code into a directory called threat-dragon and contains the application code in two sub-folders, one for the back-end application (td.server) and one for the front-end (td.site).

To install, run: npm install from the root of the project. A postinstall script is run that will install dependencies in both the server and site directories as well.

Running npm run start from the root directory of the repository will start the front-end and the server.

Docker

To run Threat Dragon in a docker container, configure your environment using dotenv as described in setup-env.md and run the following from the root of the project:

• docker build -t owasp-threat-dragon:dev .
• docker run -it --rm -p 3000:3000 -v $(pwd)/.env:/app/.env owasp-threat-dragon:dev

Environment variables

Threat Dragon uses GitHub to store threat models, so you need to go to your GitHub account and register it as a GitHub application. Once you have done that you need to set the Client ID and Client Secret as environment variables (GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET).

You also need to set a session signing key environment variable (SESSION_SIGNING_KEY). Setting up these environment variables has caused some confusion in the past, so there is a step-by-step guide to this.

Running the application

Once your environment variables are set up, start the node web server:

npm start

If you then browse to http://localhost:3000 you should see the running application.

Building

The basic build script is:

npm run build

See package.json for other build tasks.

Running the unit tests

The unit tests are written using Mocha and Karma, coverage is provided by Istanbul via nyc. A few different npm tasks are available, and these are split between the front-end and back-end directories.

For front-end (root of the project):

• pretest: runs jshint without the unit tests
• test-client-phantomjs, test-client-firefox, test-client-chrome, test-client-ie: runs client side tests using the specified browser
• test: runs jshint, client side tests on Firefox and PhantomJS (this is what runs on Travis CI)
• test-local: runs jshint, client side tests on all browsers (useful as a pre-push git hook)
• citest: continously runs client side tests in PhantomJS with --single-run false (useful while coding)

For the back-end (from the td.server directory):

• pretest: runs jshint without the unit tests
• test: runs the server side tests

Utilities

Threat Dragon has a growing collection of utilities and scripts which can be used to convert file formats, interface to bug tracking, and so on. If you would like to contribute scripts to the Threat Dragon community then this would be most welcome, see the contributing guide.

Contributing

Pull requests, feature requests, bug reports and feedback of any kind are very welcome, please refer to the page for contributors.

We are trying to keep the test coverage relatively high, so please try to update tests in any PRs and make PRs on the development branch. There are some developer notes to help get started with this project.

Vulnerability disclosure

If you find a vulnerability in this project please let us know ASAP and we will fix it as a priority. For secure disclosure, please see the security policy.

Project leaders

• Mike Goodwin ([email protected])
• Jon Gadsden ([email protected])
• Leo Reading ([email protected])