DOCSEARCHbyAlgolia
Submit Docs

OWASP Threat Dragon Documentation

repository·main·Indexed 23 days ago

https://github.com/owasp/threat-dragon

A free, open-source, cross-platform threat modeling tool used to create data flow diagrams and identify potential threats and mitigations. Documentation covers building version 2.x from source, running via Docker, configuring environment variables for GitHub, Bitbucket, and GitLab, and developing the Express-based backend (td.server) and Vue/Electron frontend (td.vue).

Tokens
28.8K
Snippets
61
Records
177
Agent score
78%

What's inside OWASP Threat Dragon

  1. Overview of OWASP Threat Dragon

    main
    OWASP Threat Dragon is an open-source threat modeling tool used to create threat models as data-flow diagrams. It allows users to associate threats and remediations with diagrams, using categorization frameworks such as STRIDE, LINDDUN, CIA, CIA-DIE, and PLOT4ai.

  2. Choose a Threat Dragon deployment variant

    main

    Threat Dragon is available in two primary variants depending on your storage and environment needs:

    1. Web application: Can be run from source or via a Docker container. It supports storing threat model files on the local filesystem or via various repository providers:

      • GitHub / GitHub Enterprise
      • Bitbucket / Bitbucket Enterprise
      • GitLab

    2. Desktop application: Available as installers for Windows, Mac OSX, and Linux. This variant stores model files on the local filesystem only.

  3. Configure environment variables for repository access

    main

    The Threat Dragon web application uses environment variables to determine which repository types are accessible. Configuring these variables allows the application to connect to:

    • GitHub
    • Bitbucket
    • GitLab
    • GitHub Enterprise
    • The client's local file system

    Refer to the configuration documentation for specific variable names and values.

  4. How Threat Dragon handles security incidents

    main
    Threat Dragon uses GitHub Issues to provide transparency regarding high-impact or high-profile security incidents. When an incident is relevant to the community, maintainers will create a pinned GitHub Issue with the security label. This issue serves as a transparency report rather than a real-time incident response feed.

  5. How locale resolution works

    main

    The application determines the active locale using a multi-step pipeline (defined in td.vue/src/service/locale/locale-resolver.js and orchestrated by td.vue/src/store/modules/locale.js):

    1. Saved preference: If the user has a previously selected locale that is still allowed by the server, it is restored.
    2. Browser languages: If no preference exists, the app checks navigator.languages and selects the first match from the supported locales.
    3. Server default: If no browser match is found, the app uses the defaultLocale configured on the server via the LOCALE_DEFAULT environment variable.
    4. Fallback: If all else fails, the hardcoded DEFAULT_LOCALE ('en') is used.

  6. Select and switch diagram threat types

    main

    Threat Dragon supports multiple threat categorization frameworks. You select the diagram type as part of the diagram attributes when editing a model.

    Supported types include:

    • STRIDE
    • LINDDUN
    • CIA
    • CIA-DIE
    • PLOT4ai
    • Generic

    Key Behavior:

    • Persistence: Changing the diagram type does not delete existing threats. If you add CIA threats and then switch the diagram type to LINDDUN, the CIA threats remain in the model and can still be edited.
    • Mixing Types: You can have diagrams of different types within the same model.
    • Generic Mode: If you need to associate a threat category with an element that is normally restricted by the current framework (e.g., assigning a STRIDE threat to an element where it isn't typically suggested), switch the diagram type to Generic. This allows you to select any threat type for any element. You can switch back to a specific framework like STRIDE or LINDDUN later.

  7. Mark elements as Out of Scope

    main

    Processes, data stores, actors, and data flows can be marked as Out of Scope. This is useful for elements that provide context to the diagram but do not require threat modeling.

    • Visual Indicator: Out of scope elements are displayed with dashed lines.
    • Behavior: Threat generation is automatically disabled for any element marked as out of scope.
    • Documentation: You can specify a Reason for out of scope in the element properties to assist reviewers.

  8. Understand container vulnerability scanning with Trivy

    main

    Threat Dragon uses Trivy to identify known vulnerable packages within containers. Scanning occurs during:

    • Every commit and pull-request.
    • A nightly cron job against the default branch.

    Strict Failure Policy: The GitHub action is designed to fail if Trivy identifies any vulnerabilities. When vulnerabilities are found, maintainers are notified via the GitHub security tab.

  9. How locale identifiers are formatted

    main

    Threat Dragon uses IETF BCP 47 language tags for all locale identifiers. These tags are case-insensitive, but the application uses the canonical form internally for messages object keys and the SUPPORTED_LOCALES array.

    • Language: ISO 639-1 two-letter code (lowercase), e.g., en, pt, zh.
    • Region (optional): ISO 3166-1 alpha-2 country code (uppercase), e.g., BR, US, GB.

    Example: pt-BR (Brazilian Portuguese). If no region variant is needed, use only the language code (e.g., es).

  10. Use Styles and Bootstrap in Threat Dragon

    main

    The project uses SCSS and Bootstrap-Vue:

    • SCSS: You can use scoped <style scss> blocks within .vue files. For global variables and mixins, place them in the src/styles directory to make them available across all components.
    • Bootstrap: The project uses bootstrap-vue, which is available globally throughout the application.

  11. Understand Dynamic Application Security Testing (DAST) in Threat Dragon

    main
    Threat Dragon utilizes ZAP to perform Dynamic Application Security Testing (DAST). This process tests running code to identify potential vulnerabilities and misconfigurations. In the Threat Dragon workflow, ZAP scans are executed as part of every commit, and the resulting scan results are attached to the output of the action.