Install Environment

Quickstart

1. Generate Keys for encryption and JWT signing
2. Copy example.env to .env
3. Update the values in .env
4. npm install
5. npm run serve

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 has advice on managing and rotating encryption keys.

Config Via DotEnv

Environment variables are configured via dotenv. 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.

Alternatively, you can also set your environment variables via command line if you’d prefer.

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

NODE_ENV=production
ENCRYPTION_KEYS='[{"isPrimary": true, "id": 0, "value": "0123456789abcdef0123456789abcdef"}]'
ENCRYPTION_JWT_SIGNING_KEY=deadbeef112233445566778899aabbcc
ENCRYPTION_JWT_REFRESH_SIGNING_KEY=00112233445566778899aabbccddeeff

Note that the environment variable SERVER_API_PROTOCOL defaults to ‘https’, and in a production environment the server will need valid certificates to run HTTPS.

Environment Errors

The application will throw an error if a required environment variable is missing during application start:

ENCRYPTION_KEYS is a required property.  Threat Dragon server cannot start without it.
Refer to development/environment.md for more information

File Based Secrets

If using file based secrets, add _FILE to the end of the secret name, and the value should point to the file location. This is particularly useful if you are running Threat Dragon in docker context, as you can use docker secrets or orchestrator such as kubernetes.

An example using docker secrets:

• Create your secrets, for example: echo "01234567890123456789" | docker secret create github_client_id -
• Create a docker compose file (example below)
• Deploy to your docker swarm, for example: docker stack deploy --compose-file docker-compose.yaml owasp-threatdragon

Example compose file:

version: '3.1'
services:
  threatdragon:
    # Always use a specific version tag, as "latest" may be a development build
    # Alternatively, you can use the "stable" tag, as that will always
    # be the most recently released version
    image: owasp/threat-dragon:v2.0.0
    ports:
      - 3000:3000
    environment:
      GITHUB_CLIENT_ID_FILE: /run/secrets/github_client_id
      GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
      ENV_FILE: /run/secrets/node_env
      ENCRYPTION_KEYS_FILE: /run/secrets/encryption_keys
      ENCRYPTION_JWT_SIGNING_KEY_FILE: /run/secrets/jwt_signing_key
      ENCRYPTION_JWT_REFRESH_SIGNING_KEY_FILE: /run/secrets/jwt_refresh_signing_key
      SERVER_API_PROTOCOL_FILE: /run/secrets/protocol
    secrets:
      - github_client_id
      - github_client_secret
      - node_env
      - encryption_keys
      - jwt_signing_key
      - jwt_refresh_signing_key
      - protocol

secrets:
  github_client_id:
    external: true
  github_client_secret:
    external: true
  node_env:
    external: true
  encryption_keys:
    external: true
  jwt_signing_key:
    external: true
  jwt_refresh_signing_key:
    external: true
  protocol:
    external: true

Command Line

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

MacOS / Linux

export GITHUB_CLIENT_ID=deadbeef0123456789ab

export ...

Windows

set GITHUB_CLIENT_ID=deadbeef0123456789ab

set ...

Environment variable reference

The secure cookie flag is set only if running in ‘production’ mode.

The desktop environment variable WEBPACK_DEV_SERVER_URL determines the mode for webpack; either development/test mode if defined (for example http://localhost:3000/) or production mode if not defined.

Note: the JWT refresh signing key should be different from the JWT signing key as they are different tokens. A JWT is used as a refresh token because it is tamper resistant and provides user context.

Refer to the step by step GitHub configuration page for an example of setting up Github specific variables.

There is a step by step Bitbucket configuration page with an example of setting up Bitbucket specific variables.

There is also a step by step Gitlab configuration page to explain the setting up of Gitlab specific variables.