⭐ Key Contributors

Izar Tarandach — pytm Project Leader and just a guy that talks a lot and wears funny conference t-shirts
Jon Gadsden — Threat Dragon & DevGuide Co-Leader
Steve Springett — OWASP Dependency-Track Leader, OWASP SCVS Co-Author, Chair of the OWASP CycloneDX Core Working Group, Chair of Ecma TC54, Core Member of the PackageURL specification, Member of the OWASP Global Board of Directors, and Security Leader at ServiceNow

Contributing Guidelines

Thank you for your interest in contributing to the Threat Model Library - an OWASP project. We welcome all contributions and appreciate your efforts to improve our projects.

Getting Started

To get started with contributing to any OWASP project, please follow these steps:

1. Join the OWASP Slack workspace to connect with the OWASP community and get help with any questions you may have.

2. Head over to our OWASP Slack channel - #project-threat-model-library if any questions.

3. Fork the repository and clone it to your local machine.

4. To understand the schema better head over to the schema specification tab on our page!

5. Go ahead and create a threat model in the json format!

6. Validate against the json schema.

7. Submit a pull request with your changes. You can ping the reviewers on the Slack channel, or just sit tight and wait - we will review!

Pull Request Guidelines

Before submitting a pull request, please make sure:

1. Your changes are consistent with the project’s goals and objectives.

2. Your changes are well-documented and follow the project’s coding standards.

3. Your changes do not introduce new bugs or break existing functionality.

4. Your changes are accompanied by tests, if applicable.

5. Your pull request includes a clear and concise description of the changes you have made.

Code of Conduct

We ask that all contributors to OWASP projects abide by our Code of Conduct. This code outlines our expectations for behavior within the project community and helps us maintain a welcoming and inclusive environment for all contributors.

Hackathon Interest

Register interest for a hackathon here.

OWASP Threat Model Library Schema Specification

This specification explains each major element defined in the OWASP Threat Model Library JSON Schema. It is designed to help understand the purpose and relationships of various schema components.

Document Metadata

version

A structured version number (e.g., “1.0”) representing the current version of the threat model. Helps track evolution of the model over time.

$schema

Specifies the Threat Model Library schema, and its specific version, the threat model document conforms to. For example:

“$schema”: “https://github.com/OWASP/www-project-threat-model-library/blob/v1.0.0/threat-model.schema.json”

System Description

The following top-level properties describe the system being threat-modeled.

scope

Defines the boundary and criticality of what is being modeled. This is foundational to any threat modeling exercise, as it determines what is included/excluded - “scoping the work” is a common terminology used in threat modelling or other security domains like pentesting.

• title: Name of the system being modeled.
• description: Describes what’s in scope and what’s out of scope. This is distinct from the description of the system’s purpose and behavior, which goes in the top-level description property, separate from scope.
• business_criticality: Indicates how important the system is to business operations. This helps prioritize risk mitigation.
• data_sensitivity: Flags if the system handles sensitive data types (e.g., credentials, PII). Critical for compliance and privacy.
• exposure: internal or external access. Externally facing systems are at higher risk.
• tier: Prioritization tier used to guide depth of modeling, risk exposure and review frequency.
  • mission_critical:
    • business criticality maximal + external
    • business critical maximal + stores sensitive data
    • business criticality high + stores sensitive data + external
  • business_critical
    • business criticality maximal and no sensitive data, internal
    • business criticality high + external but no sensitive data
    • business criticality high + sensitive data + internal
    • business criticality moderate but sensitive data + external
  • important
    • business criticality moderate and below + sensitive data
    • business criticality moderate + external, no sensitive data
  • non_critical
    • business criticality moderate and below + internal and no sensitive data
    • business criticality low and minimal, no sensitive data, can be external

description

Describes the system’s purpose and behavior and any other business context not otherwise captured.

Architecture Modeling

trust_zones

Logical areas with uniform trust assumptions (e.g., public internet, internal VPC, secure enclave). Used to define boundaries of exposure and control. Each component is assigned to a trust zone.

trust_boundaries

Interfaces where data crosses from one trust zone to another. These are high-risk areas in any architecture:

• Controls (e.g., authentication, access control) must be explicitly modeled here.
• To exist they must be defined with controls such as encryption, authentication, token management, session security …
• If a trust boundary is not defined then that is a threat modelling finding - the root cause of potential threats!

actors

These are commonly known as entities. Human or machine entities that interact with the system. Key to identifying external threats and misuse scenarios.

components

Building blocks of the system (e.g., APIs, backend services). Central to threat modeling since most threats target specific components.

data_stores

Where data is stored or persisted. Important for identifying risks like unauthorized access, data corruption, and backups.

data_sets

Logical groupings of data. Mapping datasets to their stores helps clarify data flow, exposure, and sensitivity.

data_flows

Represents communication between components, actors, and data stores. Data flows are key to STRIDE-based threat modeling and attack path analysis.

diagrams

Enables visual system modeling using PlantUML, Mermaid, or similar. Essential for collaboration and reviewing architecture.

Security Modeling

assumptions

Things you take as true about your system (e.g., “TLS terminates at the load balancer”). Helps clarify model boundaries and gaps.

• description: An arbitrary statement about the system.
• topics: A list of topics on which the assumption makes a statement. These topics will be of a standardized taxonomy and must not be arbitrarily chosen. As of right now, no topics have been standardized, so this property must not be specified.
• validity: Whether the assumption is unconfirmed (proposed/assumed by a stakeholder), confirmed (definitely true), or rejected (proposed but known to be false).

threat_personas

Adversary profiles that inform how and why threats might be realized. Useful for risk assessment and simulating realistic attacker behavior.

Aids in justifying and validating threats. Supports structured persona-based modeling and possible support for integration with threat detection tools in the future.

threats

Individual threat events. Each threat references its persona, attack vector (CAPEC), and weakness (CWE). They are the core unit of security concern in the model.

controls

Implementations of mitigations tied to specific threats. Helps ensure your model leads to actionable recommendations.

Effectiveness of controls: Added as a property (e.g., minimal to maximal scale) to assess relative control strength.

Distinguished from mitigations which is the process of implementing countermeasures. A mitigation is the effect or strategy of reducing risk, rather than the specific tool or mechanism.

We chose the term “controls” over alternatives like “mitigations” or “countermeasures” because:

• controls is more aligned with risk and governance frameworks such as ISO 27001, NIST, CIS, and SOC2
• it reflects the language used in security audits, risk treatment plans, and governance reporting
• it’s broader and implementation-agnostic, a control can be preventive, detective, or corrective - not just a technical fix
• “mitigation” often implies reduction in risk, but not full prevention
• “countermeasure” is more military/technical and less used in enterprise security governance
• it enables clearer mapping between threat models and control libraries, using controls makes it easier to link threat model outputs to control catalogs like NIST 800-53, OWASP ASVS, or CIS Controls

In short, “control” unifies threat modeling with risk governance and enterprise security frameworks — making threat models more actionable and aligned with business processes.

risks

Risk is a function of the likelihood of a threat event / scenario’s occurrence and potential adverse impact should the event occur. A risk should be present only if a vulnerability or weakness are present that could lead to a threat event. Ties the threat model to risk management practices and governance. Enables prioritization.

Even though risks are influenced by org-specific factors (impact context, likelihood drivers), the schema retains this optional element to support linkage with enterprise risk registers.

summary

To formulate a risk summary consider how a threat with an exploitable weakness or vulnerability leads to a risk event and certain impact.

likelihood

Likelihood is a factor of risk. To estimate the likelihood consider the applicability of the threat persona to the business context, threat source, threat scenario, existing vulnerabilities or pre-existing conditions.

impact

Impact is a factor of Risk. Key considerations for impact are:

• Operational Impact: How the threat affects business processes.
• Financial Impact: The potential monetary loss.
• Reputation Impact: Public perception and long-term trust.
• Regulatory/Legal Impact: Fines, penalties, or legal consequences.

level

• Methodology: Likelihood x Impact
• Output:
  • Score: Numerical
  • Descriptive: Text label (e.g., Low, Medium, High)

score

The cross product of impact and likelihood yields the risk score, a scale from 1 to 25:

5x5 Risk Level Matrix

The cross product of impact and likelihood yields the risk score (1–25). Color-coded with emojis to reflect severity bands:

5x5 Risk Level Matrix

The cross product of impact and likelihood yields the risk score (1–25). The matrix below is color-coded with square emojis to reflect severity bands:

Based on the numerical value of the risk score, we define the following risk levels:

Likelihood and impact assesment guidance

Impact Severity Definitions

Extensions

extensions

Allows custom fields while enforcing namespace uniqueness. Enables organizations to capture additional data relevant to their threat modeling workflows. For example:

{
  ...
  "extensions": {
    "example.com/owasp-threat-model-foobar-extension": {
      // Whatever schema is needed, whereas the schema should be clearly
      // documented at https://example.com/owasp-threat-model-foobar-extension.
      ...
    },
    "example.net/other-extension": {
      // Analogously.
      ...
    }
  }
}

This schema enables traceable, evidence-backed, and enterprise-ready threat modeling for modern systems. It is optimized for structured outputs, tool integration, and supports formal risk analysis through linkage of threats, risks, and mitigations.

For implementation guidance or examples, refer to https://github.com/OWASP/www-project-threat-model-library.

🌟 Demonstrate Your Brand’s Commitment to Innovation

Sponsor the OWASP Threat Model Library (TML)

🚀 Shaping the Future of Threat Modeling

The OWASP Threat Model Library (TML) is the first open, community-driven dataset that collects real-world threat models.
It lowers the barriers to entry for developers, engineers, and security teams by providing reusable examples, structured schemas, and practical templates.

By supporting this project, you help move threat modeling from a niche activity to a widely adopted practice, embedded in how systems are designed and built.

🎯 Incentives to Support the OWASP Threat Model Library

🌍 Global Outreach

Stand alongside OWASP in creating the world’s most comprehensive open dataset of threat models — a resource that will influence organizations, regulators, and security research for years to come.

💡 Drive Innovation

Help drive innovation in threat modeling: from standardising schemas to building the pre-requisite for threat modelling / security AI development.

🤝 Join the Community

Your support powers events, workshops, and hackathons, where practitioners share hard-won lessons and refine models together.

🔧 Supporting the Evolution of TML

The OWASP Threat Model Library is powered by passionate volunteers.
Your sponsorship ensures ongoing improvements, outreach, and innovation, including:

• Development of new threat models for emerging technologies
• Threat modeling data model innovation support
• Community events and workshops
• Talks, training, and publications that spread adoption
• Building bridges with standards bodies and other OWASP projects (e.g., CycloneDX)

👉 Your contribution helps make threat modeling accessible to everyone — from developers to CISOs.

🏢 Benefits for Your Organization

• Visibility with Purpose: Be recognized at OWASP events, on project pages, and in research outputs as a company that invests in open source and transparent security.
• Reputation Boost: Show customers and partners that you are committed to systemic security improvements, not just proprietary solutions.
• Access to Experts: Engage with a diverse network of researchers, engineers, and industry leaders advancing the state of threat modeling.

💎 Sponsorship Tiers

🏆 Gold – $10,000+

• High-visibility sponsorship with prominent logo placement on the project page
• Logo placement on the project Sponsorship Tab as a Gold Sponsor
• Recognition in co-leader and key-contributor talks/presentations
• Prominent logo placement at project events and hackathons
• Additional visibility of your organisation’s product

🥈 Silver – $5,000+

• Placement as Silver Sponsor on the sponsorship tab
• Strong visibility in project communications
• Participation in project events, workshops, and hackathons with brand visibility

🥉 Bronze – $1,000+

• Acknowledgment on sponsor project pages
• Inclusion as a Bronze supporter

🌱 Startup Discounts & Alternatives

• Startups with < $30M funding receive a $2,500 discount on Silver and Gold sponsorships.
• In certain cases, we can substitute part of the funding with resources such as:
  • Hackathon or workshop planning
  • Direct project contributions
  • Community outreach
  • Event venues, speakers, and platforms

📩 Interested? Let’s talk!