deardaniel/secdata-raw huggingface dataset:
OWASP Threat Modeling: environment

---
layout: page
title: Development environment
nav_order: 1
path: /development/environment
group: Development
---

## Development environment

Environment variables are used to configure the Threat Dragon web application.
The desktop version of Threat Dragon does not need these variables.

Refer to the various [environment variables]({{ '/configure/configure.html' | relative_url }})
that are available to configure the web application.

A minimal set of environment variables, that will provide local file access, is:

* NODE_ENV
* ENCRYPTION_KEYS
* ENCRYPTION_JWT_SIGNING_KEY
* ENCRYPTION_JWT_REFRESH_SIGNING_KEY
* SERVER_API_PROTOCOL

### Generating keys

A random 16 byte (32 character, 256 bit) hexadecimal string should be used for encryption,
which needs to be randomly generated and kept secret.
With openssl installed use this command to generate a new 256 bit key: `openssl rand -hex 16`

This command can also be used to generate JWT signing keys.

The Express server documentation on [express-session](https://github.com/expressjs/session#readme)
has advice on managing and rotating encryption keys.

### Webapp environment variables

Export all of the your variables from the terminal where you will start Threat dragon.  

### MacOS / Linux

`export GITHUB_CLIENT_ID=deadbeef[PII_REDACTED]ab`

`export ...`

### Windows

`set GITHUB_CLIENT_ID=deadbeef[PII_REDACTED]ab`

`set ...`

### Config via DotEnv

Environment variables are configured via [dotenv](https://github.com/motdotla/dotenv#readme).
By default, Threat Dragon attempts to read key/value pairs from a `.env` file at the root of this repository.
This can be configured by exporting a file path in your terminal.
For example, on MacOS/Linux: `export ENV_FILE=/home/myawesomeuser/mydir/somefile.env`

To get started, copy `example.env` to `.env` at the root of the project and update the variables as appropriate.

Note: Do not use the `export` or `set` keywords inside your `.env` file, as this will not work from within a docker context.
The `dotenv` package will automatically export the variables for you.

Here is an example of a minimal DotEnv file, note that keys would need to be generated for it :

```sh
NODE_ENV=development
ENCRYPTION_KEYS='[{"isPrimary": true, "id": 0, "value": "[PII_REDACTED]abcdef[PII_REDACTED]abcdef"}]'
ENCRYPTION_JWT_SIGNING_KEY=deadbeef[PII_REDACTED]6778899aabbcc
ENCRYPTION_JWT_REFRESH_SIGNING_KEY=[PII_REDACTED][PII_REDACTED]aabbccddeeff
SERVER_API_PROTOCOL='http'
```

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: contributing

---
layout: page
title: Contributing
nav_order: 2
path: /development/contributing
group: Development
---

## Contributing

Pull requests, feature requests, bug reports and feedback of any kind are very welcome, please refer to the page for
[contributors](https://github.com/OWASP/threat-dragon/blob/main/contributing.md).

We are trying to keep the test coverage relatively high, so please try to update tests in any PRs.
There are some [developer notes]({{ '/development/development.html' | relative_url }})
to help you get started with this project.

The Threat Dragon main branch only accepts signed commits, otherwise the contribution will be rejected.
Signed commits help to filter out malicious activity,
see the Github documentation on [commit signature verification][signed-commits].

### Quick start

Clone and install the Threat Dragon repo:

```sh
git clone git@github.com:OWASP/threat-dragon.git
cd threat-dragon
npm install
```

After making any changes be sure to test them:

```sh
npm start
npm test
npm run test:vue
```

### 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](https://github.com/OWASP/threat-dragon/blob/main/security.md).

----

Threat Dragon: _making threat modeling less threatening_

[signed-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification
OWASP Threat Modeling: unit

---
layout: page
title: Unit testing
nav_order: 1
path: /testing/unit
group: Testing
---

## Unit testing

The complete suite of unit tests can be run locally using command `npm test` from the top directory.

### Jest frontend testing

Unit testing for the vue application `td.vue` is done using [jest](https://jestjs.io/),
and lives in the `td.vue/tests/unit` directory.

If you'd prefer to work in a more TDD fashion, you can have the tests run continuously by
navigating to the `td.vue` directory and running `npm run test:unit -- --watch`

### Mocha backend testing

Unit testing for the server application `td.server` is done using [Mocha](https://mochajs.org/),
with a little help from our friends [Sinon.JS][sinon] and [chai][chai].
To run the tests locally navigate to the `td.server` directory and run `npm run test:unit` or `npm test`.

## Code Coverage

Run unit tests with `npm test` for either the front-end and back-end application to obtain the code coverage report.
There will be an HTML report generated as well that you can view to
dig deeper into what sections may be missing coverage.

We hope to keep the code coverage as high as possible.  If you need help writing or updating tests, please just ask!

----

Threat Dragon: _making threat modeling less threatening_

[chai]: https://www.chaijs.com/
[sinon]: https://sinonjs.org/
OWASP Threat Modeling: actions

---
layout: page
title: Pipeline actions
nav_order: 3
path: /testing/actions
group: Testing
---

## Pipeline actions

[GitHub Actions](https://docs.github.com/en/actions/reference) are used to test, build and deploy Threat Dragon.
These actions live in the `.github/workflows` directory.

## PR Pipeline

The CI Action is Threat Dragon's continuous integration pipeline.
This pipeline is run on all branches and serves as a quality check.
When a pull request is opened, each step of this pipeline is added as a check to the pull request.
This gives the author and reviewers an opportunity to understand the state of the code.

Because this action uses a docker image that is pushed to a remote repository for testing,
there is a concurrency group that prevents concurrent runs of the same action.

## BrowserStack End to End Tests

[BrowserStack][browserstack] offers its services [for free to open-source projects][browserstack-os],
and has graciously provided Threat Dragon with their services.
BrowserStack provides automated, cross-browser testing for web and mobile applications.

Because cross browser testing has diminishing returns,
it is only run against the latest deployed version (from main) once per day.

## Housekeeping

The house-keeping workflow runs a nightly workflow, and will:

* delete stale actions
* check links across the documentation
* run Trivy container scans to identify unpatched vulnerabilities in the docker image
* run the [CodeQL](https://securitylab.github.com/tools/codeql/) is a static analysis scanner provided by GitHub

## CI Pipeline

The deploy action is run on any "push" to the main branch (this includes merged pull requests),
and serves as Threat Dragon's continuous delivery pipeline.

* Build:
    This workflow builds and pushes the Docker image with the `latest` tag.
    The `latest` tag is not consider stable, and may be broken at times.
    While we do our best to maintain a fully functioning main branch, mistakes will happen.
    Additionally, the full end to end test suite is only run once per day, so errors may not be immediately available.
* Deploy: The latest image is deployed to [https://www.threatdragon.com/](https://www.threatdragon.com/).
* Smokes: Smoke tests are run against the deployed image to ensure the deployment succeeded.
* Rollback: If the smokes fail, the deployment is rolled back.

## Release Pipeline

This action is performed when a tag is created with a v2.x.x format.
It will perform all tests and then build and publish the install images and the Docker image.

----

Threat Dragon: _making threat modeling less threatening_

[browserstack]: https://www.browserstack.com/
[browserstack-os]: https://www.browserstack.com/open-source
OWASP Threat Modeling: testing

---
layout: page
title: Testing
nav_order: 0
path: /testing
group: Testing
---

## Testing

### Automated testing

There are various test scripts in place to help with testing both front and back ends:

* [End to end testing]({{ '/testing/e2e.html' | relative_url }})
* [Unit testing]({{ '/testing/unit.html' | relative_url }})

In addition there are pipeline / workflow tests that are applied on pull requests, commits to the main branch and others.
For these refer to the [Pipeline actions]({{ '/testing/actions.html' | relative_url }}).

### Manual testing

During development it can be convenient to manually check functionality of the
front and back ends which is not yet part of the unit or end-to-end tests.

#### Backend server

The web application express server can be run locally using command `npm run start:server` from the top level directory.
The server will need access to environment variables as shown in
[environment setup]({{ '/configure/configure.html' | relative_url }}).

When running locally it may be that HTTPS certificates are not present,
so consider using these environment variables that use HTTP:

```sh
NODE_ENV=development
LOG_LEVEL=debug
SERVER_API_PROTOCOL=http
```

A browser can be used to access the server, or other command line tools such as curl:

```sh
curl -v http://localhost:3000/api/threatmodel/organisation  \
     -H "Accept: application/json"
```

#### Desktop server

The desktop application uses electron as the back-end server.
Use command `npm run start:desktop` to run the application in development mode,
it will rebuild and launch when source files are changed.

#### Frontend application

The front end application can be tested in most browsers along with the browser supplied developer tools.
If the application is being tested in the desktop environment then electron uses
chrome as the renderer, with chrome developer tools being available.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: credits

---
layout: page
title: Credits
nav_order: 1
path: /about/credits
group: About
---

## Credits

[Mike Goodwin](mailto:mike.goodwin@owasp.org) is the originator, founder and leader of OWASP Threat Dragon.
The [first commit](https://github.com/mike-goodwin/owasp-threat-dragon/commit/942bdff78191ef0eae40f7610b[PII_REDACTED]d8b8)
to the original Threat Dragon repository was made on ninth October 2015, so that is Threat Dragon's birthday.

Some years later we found that using JointJS for the diagramming library was not proving sustainable,
so [Leo Reading](mailto:leo.reading@owasp.org) migrated the project to Vue/Express using the drawing library antv/x6.

### Cupcake

![Cupcake image]({{ '/assets/images/cupcake-128x128.png' | relative_url }}){: .float-right}

Our logo is called Cupcake, and provides a friendly face when entering the world of threat modeling.
We think that Cupcake makes threat modeling less threatening.

We are very grateful to the talented artist
[DЯΣΛMƧVΣЯƧΣ](https://linktr.ee/dreamsverse) who created the artwork for Cupcake.
DЯΣΛMƧVΣЯƧΣ has allowed use of the
[original artwork](https://www.deviantart.com/thelonelyqueen/art/HW-Lil-Baby-Dragon-Lineart-300502156)
on condition that it used only for 'not for profit' purposes - perfect for our open source project.
Cupcake has a birthday as well: DЯΣΛMƧVΣЯƧΣ uploaded the original artwork on seventh May 2012.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: web

---
layout: page
title: Install web application
nav_order: 2
path: /install/web
group: Install
---

## Web application installation

[Threat Dragon](https://owasp.org/www-project-threat-dragon/) comes in two variants,
a desktop application and a web application.

The web application can be run locally or from a server.
Consider who will be able to access the web application and also the security of the platform;
the web application can be used to access various repositories which may need to be protected.

### Install

Threat Dragon is a node.js single page application using Vue on the client and Express on the server.
To build and run locally follow these steps:

Install [node.js][node], which includes the node package manager `npm`, and also install [git][git].

Obtain the code from the latest [releases area][releases] in the form of either
a `.zip` file or a `.tar.gz` file.

Extract the source tree for Threat Dragon from the archive file and
install the application dependencies using npm (or pnpm if that is installed) :

`npm install`

### Environment variables

The Threat Dragon web application requires some environment variables to be in place.
According to what variables are defined, access is provided to repository types:

- GitHub
- Bitbucket
- GitLab
- Github Enterprise

and also the client's local file system.

See the [environment]({{ '/configure/configure.html' | relative_url }}) page
for details on configuring your environment variables.

### Running the application

Once your environment variables are set up, if running on Linux or MacOS start the node web server with :

`npm start`

When running on Windows the front-end and back-end are started separately using commands:
`npm run dev:server` and `npm run dev:vue`.

Browse to `http://localhost:8080` to ensure that the Threat Dragon application
is available within the browser as a single page application.

### Building latest web application

As an alternative to using a released version of the the Threat Dragon web application,
`git` can be used to clone the latest version of the source code

```sh
git init
git clone https://github.com/owasp/threat-dragon.git
cd threat-dragon
```

The source tree contains two main sub-folders:
one for the main application (`td.site`) and one for the server (`td.server`).
Install dependencies, configure and run the web application as above.

----

Threat Dragon: _making threat modeling less threatening_

[git]: https://git-scm.com/downloads/
[node]: https://nodejs.org/en/download
[releases]: https://github.com/OWASP/threat-dragon/releases/latest/
OWASP Threat Modeling: installation

---
layout: page
title: Installation
nav_order: 0
path: /install
group: Install
---

## Installation

[Threat Dragon](https://owasp.org/www-project-threat-dragon/) comes in two variants,
a desktop application and a web application.

### Web application

The web application can be run locally or from a server, and is downloaded from the [Threat Dragon repo][releases].
There is some configuration necessary, so see the
[install instructions]({{ '/install/web.html' | relative_url }}) for configuring the application.

The web application is also provided in a Docker image, and this is provided by [dockerhub][docker].
Follow the Docker [instructions]({{ '/install/docker.html' | relative_url }})
to download, configure and run a Docker container.

### Desktop application

Various installers can be downloaded from the Threat Dragon [releases area][releases]:

* Windows (64 bit) executable / installer
* MacOS installers (.dmg) for X86 and Apple silicon
* Linux AppImage used for most Linux distributions and hardware platforms
* Linux Snap image is available from the [official snapcraft distribution][snap]
* Package `.rpm` for Red Hat Linux, AIX, CentOS, Fedora
* Package `.deb` for debian based Linux such as Ubuntu, Trisqel and Debian itself

See the desktop [install instructions]({{ '/install/desktop.html' | relative_url }}).

----

Threat Dragon: _making threat modeling less threatening_

[docker]: https://hub.docker.com/r/owasp/threat-dragon/tags
[releases]: https://github.com/OWASP/threat-dragon/releases
[snap]: https://snapcraft.io/threat-dragon
OWASP Threat Modeling: desktop

---
layout: page
title: Install desktop application
nav_order: 1
path: /install/desktop
group: Install
---

## Desktop install

[Threat Dragon](https://owasp.org/www-project-threat-dragon/) comes in two variants,
a desktop application and a web application.

To install the desktop application, use the installers available for download from the [OWASP GitHub area][releases]:

* Windows (64 bit) executable / NSIS installer
* MacOS installers (.dmg) for X86 and Apple silicon
* Linux AppImage used for most Linux distributions and hardware platforms
* Linux Snap image is available from the [official snapcraft distribution][snap]
* Package `.rpm` for Red Hat Linux, AIX, CentOS, Fedora
* Package `.deb` for debian based Linux such as Ubuntu, Trisqel and Debian itself

### Linux installer and AppImage

Packages for both Debian and Fedora Linux on AMD64 and X86-64bit platforms
can be downloaded from the [releases area][releases].
Platform independent application installers Snap and AppImage are also provided.

### MacOS installer

Download the `.dmg` MacOS installer from the [releases area][releases].
Open the download and drag 'OWASP Threat  Dragon' to the application directory.
When the install has finished, run Threat  Dragon from launchpad or from Finder / Applications.

### Windows installer

Download the Windows `.exe` installer from the [releases area][releases].
Run the installer and invoke the application from the shortcut.

### Desktop application build instructions

As an alternative to using a released version of the the Threat Dragon desktop application,
`npm` can be used to install and run Threat Dragon locally:

```sh
git clone https://github.com/owasp/threat-dragon
cd threat-dragon
npm install
```

This allows access to the latest code updates between releases,

To run the Threat Dragon desktop application in development mode:

`npm run start:desktop`

To build an installer:

`npm run build:desktop`

----

Threat Dragon: _making threat modeling less threatening_

[releases]: https://github.com/OWASP/threat-dragon/releases/latest/
[snap]: https://snapcraft.io/threat-dragon
OWASP Threat Modeling: sast

---
layout: page
title: SAST
nav_order: 2
path: /trust/sast
group: Trust
---


## Static Application Security Testing (SAST)

SAST is the process of examining code at rest to identify potential vulnerabilities and misconfigurations.
This is provided by [CodeQL](https://securitylab.github.com/tools/codeql/) and is run as part of every pull request.
Pull requests with CodeQL failures will not be accepted unless the alert is proven to be a false/positive.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: dependencies

---
layout: page
title: Dependency management
nav_order: 1
path: /trust/dependencies
group: Trust
---

## Dependency management

The following controls are in place to assist with dependency management of the web application:

- Trivy scanning per commit for SCA and OS dependency management within docker
- Trivy scanning daily on the latest build in the default branch
- Dependabot alerts
- `npm` for dependency resolution and auditing

### Fixing a vulnerable dependency

If your build fails due to a trivy alert, try to find the part of the application that has the vulnerable component.
In the root directory of that component (where the `package.json` lives), run `npm audit`.
This will advise on dependencies with known vulnerabilities and whether they can be fixed.
You can then run `npm audit fix` which updates the `package-lock.json` file.
To obtain the updated package run `npm install`.

This should be done at the package level and the root level when possible to protect developers
as well as production environments.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: container

---
layout: page
title: Container scanning
nav_order: 4
path: /trust/container
group: Trust
---

## Container scanning

[Trivy](https://github.com/aquasecurity/trivy) identifies known vulnerable packages inside the container,
and scans the built container as part of each commit and pull-request.
It is also run as a nightly cron job against the default branch.

The GitHub action will fail if Trivy identifies _any_ vulnerabilities; this is strict by design.
If vulnerabilities are discovered then the maintainers are alerted via GitHub's security tab.

A `.trivyignore` file is maintained at the root of this repo that allows CVEs to be ignored.
A comment with a justification should be added above any ignored CVE.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: trust

---
layout: page
title: Trust
nav_order: 0
path: /trust
group: Trust
---

## Trust

The Threat Dragon development team build security into the application and the supply chain.
Some examples of this are:

* the code repository enforces signed commits which helps filter out malicious activity
* the supply chain actions are identified using a full-length SHA
* the desktop installer releases are signed and notarized where possible

### Continual testing

The automated security scans of Threat Dragon are run on every commit:

* [Dependency management]({{ '/trust/dependencies.html' | relative_url }})
* [SAST]({{ '/trust/sast.html' | relative_url }})
* [DAST]({{ '/trust/dast.html' | relative_url }})
* [Container scanning]({{ '/trust/container.html' | relative_url }})

### Incident Response

Report security vulnerabilities found within Threat Dragon by following the process in
the [Security Policy](https://github.com/OWASP/threat-dragon/blob/main/security.md).
Every effort will be made to resolve security concerns as they arise.

Threat Dragon is open source software and contains many other open source components.
Threat Dragon's community strives to stay abreast of security vulnerabilities
and incidents impacting upstream providers or Threat Dragon itself.

If there is a high impact or high profile incident or vulnerability,
the Threat Dragon community/maintainers will create a [GitHub Issue](https://github.com/owasp/threat-dragon/issues)
and leave it pinned for as long as it is relevant to the community.
This issue will have the "security" label, and is intended to serve as a transparency report,
not necessarily a real-time feed of incident response.

Threat Dragon is maintained by a community of volunteers and so
it will not always be possible to immediately investigate or immediately respond to incidents,
but this community will do its best.

----

Threat Dragon: _making threat modeling less threatening_
OWASP Threat Modeling: dast

---
layout: page
title: DAST
nav_order: 3
path: /trust/dast
group: Trust
---

## Dynamic Application Security Testing (DAST)

DAST is the process of testing code that is running to identify potential vulnerabilities and misconfigurations.
This is provided by [ZAP](https://www.zaproxy.org/docs/docker/about/) and is run as part of every commit.

ZAP scan results are attached to the output of an action.
An ignore-list is maintained as a TSV (tab separated values, careful what editor you use).
Any modifications to the exclusions should be approved by a maintainer as part of a pull request.

----

Threat Dragon: _making threat modeling less threatening_