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.
A structured version number (e.g., “1.0”) representing the current version of the threat model. Helps track evolution of the model over time.
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”
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.
Describes the system’s purpose and behavior and any other business context not otherwise captured.
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.
Interfaces where data crosses from one trust zone to another. These are high-risk areas in any architecture:
These are commonly known as entities. Human or machine entities that interact with the system. Key to identifying external threats and misuse scenarios.
Building blocks of the system (e.g., APIs, backend services). Central to threat modeling since most threats target specific components.
Where data is stored or persisted. Important for identifying risks like unauthorized access, data corruption, and backups.
Logical groupings of data. Mapping datasets to their stores helps clarify data flow, exposure, and sensitivity.
Represents communication between components, actors, and data stores. Data flows are key to STRIDE-based threat modeling and attack path analysis.
Enables visual system modeling using PlantUML, Mermaid, or similar. Essential for collaboration and reviewing architecture.
Things you take as true about your system (e.g., “TLS terminates at the load balancer”). Helps clarify model boundaries and gaps.
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.
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.
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:
In short, “control” unifies threat modeling with risk governance and enterprise security frameworks — making threat models more actionable and aligned with business processes.
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.
To formulate a risk summary consider how a threat with an exploitable weakness or vulnerability leads to a risk event and certain impact.
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.
The cross product of impact and likelihood yields the risk score (1–25). Color-coded with emojis to reflect severity bands:
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: Likelihood \ Impact|1 (Negligible)|2 (Minor)|3 (Moderate)|4 (Major)|5 (Severe) 1 (Rare)|🟩 1 (Very Low)|🟩 2 (Very Low)|🟨 3 (Low)|🟨 4 (Low)|🟧 5 (Medium) 2 (Unlikely)|🟩 2 (Very Low)|🟨 4 (Low)|🟧 6 (Medium)|🟧 8 (Medium)|🟥 10 (High) 3 (Possible)|🟨 3 (Low)|🟧 6 (Medium)|🟧 9 (Medium)|🟥 12 (High)|🟪 15 (Very High) 4 (Likely)|🟨 4 (Low)|🟧 8 (Medium)|🟥 12 (High)|🟪 16 (Very High)|🔴 20 (Critical) 5 (Almost Certain)|🟧 5 (Medium)|🟥 10 (High)|🟪 15 (Very High)|🔴 20 (Critical)|🔴 25 (Critical) Based on the numerical value of the risk score, we define the following risk levels: Risk Score Range|Risk Level 🟩 1–2|Very Low 🟨3–4|Low 🟧 5–9|Medium 🟥 10–12|High 🟪13–16|Very High 🔴20–25|Critical
| Value | Likelihood | Definition |
|---|---|---|
| 1 | Rare | Very unlikely to occur; may happen only in exceptional circumstances, such as once in 10+ years. |
| 2 | Unlikely | Could occur but not expected; has happened once in 5–10 years. |
| 3 | Possible | Might occur under some circumstances; happens every 2–5 years. |
| 4 | Likely | Expected to occur in some situations; happens at least once a year. |
| 5 | Almost Certain | Expected to occur regularly; happens multiple times a year or more frequently. |
| Value | Impact Severity | Operational Impact | Financial Impact | Reputation Impact | Regulatory/Legal Impact |
|---|---|---|---|---|---|
| 1 | Insignificant | Minimal disruption, no noticeable effect on business operations. | <0.1% of annual revenue. | No damage to reputation. | No legal or regulatory implications. |
| 2 | Minor | Some minor disruption, but recoverable with little effort. | 0.1% to 0.5% of annual revenue. | Small, localized damage to reputation, quickly recoverable. | Minor compliance issues, no fines or legal action. |
| 3 | Moderate | Noticeable operational impact, moderate recovery efforts required. | 0.5% to 1% of annual revenue. | Moderate reputation damage; some negative press, recoverable. | Possible fines or legal action; warning from regulators. |
| 4 | Major | Significant operational disruption; requires substantial resources. | 1% to 5% of annual revenue. | Significant damage to reputation; major loss of customer trust. | Substantial legal issues; fines and regulatory penalties. |
| 5 | Severe | Critical operational impact; operations cease or major losses. | >5% of annual revenue. | Severe reputation damage; long-term loss of market position. | Major legal action; large fines; potential shutdown. |
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.
Project Resources
Project Leaders
wears funny conference t-shirts
the community
Chair of Ecma TC54
Security Leader at ServiceNow
ized access
data corruption
backups
Julian Mehnle
Project Leader
Project Information
Incubator Project
Classification
Other
Language
Python
Contributors
12
GitHub Stars
430
Downloads
0
Corporate Supporters
OWASP is a nonprofit foundation improving software security through open-source projects, global communities, and education. All resources are free and open to everyone.
Quick Links
Legal & Governance
SlackOWASP, the OWASP logo, and Global AppSec are registered trademarks and AppSec Days, AppSec California, AppSec Cali, SnowFROC, OWASP Boston Application Security Conference, and LASCON are trademarks of the OWASP Foundation, Inc.
© 2026, OWASP Foundation Inc. All rights reserved.