A simple threat modeling tool to help humans to reduce time-to-value when threat modeling
----> Live demo <----
The process of threat modeling helps you identify security issues and develop a strategy to address them in the context of your system. A threat model directly supports your ability to define, agree upon, and communicate what is necessary in order to deliver a secure product or service. You can threat model very early in your design phase. These early insights put you in a better position to identify sensible design choices early in the cycle, and efficiently build and ship your workload securely. Identifying and fixing security issues at design time is exponentially easier to do than doing so once the workload has been built.
There are many ways to perform threat modeling. Much like programming languages, there are advantages and disadvantages to each. You should choose the approach that works for you, and communicate it within your organization. A good place to start is Shostack’s 4 Question Frame for Threat Modeling which proposes four simple open ended questions.
The Threat composer tool has been built for the following reasons:
- Coming up with useful threats can be hard. Feedback from builders regarding the "What can go wrong?" question is that there are two key challenges in this step - firstly, no generally agreed standard on what 'good' looks like. This is contextual based on the system being assessed and the ownership model of the teams involved; and, secondly, there is no canonical list of possible things that could go wrong. Hence, threat identification necessitates brainstorming and collaboration between the individuals involved in the threat modeling process, and often involves starting from a "blank page". Threat composer uses "Threat Grammar", a prescriptive way to write threats, with the aim of making it easier to iteratively write useful threats. Threat Composer includes full examples to help the customer understand what good might look like. Customers can use these as inspiration or as a starting point for their own threats.
- Provide insights on how to improve quality and coverage. One of the toughest questions to answer is “did we do a good enough job?” because it can be highly subjective. Threat composer includes an ‘insights dashboard’ to help you quickly identify areas for improvement, including (a) threats without linked mitigations, (b) unprioritized threats, (c) threat category distribution, and (d) based on threat grammar usage, potential improvement to inputs for mitigation or prioritisation.
- Threat modeling is non-linear. Threat modeling is often taught as a linear process, where a person or team works on each of the threat modeling questions separately. In practice, threat modeling can be very non-linear. For example, you may think of a mitigation (“what are we going to do about?”) immediately after you’ve thought of a threat (“what can go wrong?), this may lead you to re-evaluate specific aspects of your design (”what are we building?“). Threat composer aims to support this kind of non-linear and natural workflow.
- Threat modeling is iterative. both at a micro and a macro level. For example, at a micro level, you may iterate on a given threat to the point you find you could decompose it into two discrete threats. At a macro level, a threat model can (and should) evolve and mature as the system you are threat modeling evolves through the software/hardware development lifecycle. In the early stages of design you may need to make a lot of assumptions, and as time passes previous assumptions may become invalidated which is a trigger to review the threat model. Additionally, as you progress it’s likely that new design decisions are made, new threats are thought of and mitigations go from being “planned”, to being “implemented”. Threat composer has been designed to support this iterative design and development lifecycle, and to support the ability of having a “living” threat model-as-code as your feature or service evolves and matures.
- Capture and store systems description, architecture diagram, and dataflow diagram.
- Capture and store assumptions related to the systems design, threats and/or mitigations, along with mapping of assumptions to threats to mitigations.
- Help iteratively compose useful threats, and encourage brainstorming. This feature is also available via a dedicated ‘Threats Only’ mode.
- Rendering structured threat statements (aligned to a prescriptive threat grammar) based on user input.
- Supporting an adaptive threat statement structure, this helps create progressively more complete threats.
- Provide dynamic suggestions based on supplied and missing user input.
- Provide complete threat statement examples to aid contextual brainstorming.
- Capture and store mitigation candidates and mapping to threats.
- Create a threat model document based on user-supplied input.
- Help users answer "Did we do a good enough job" by providing insights and suggestions for bar-raising actions via an 'Insights dashboard'
- Data persisted only client-side within the browser (100% local storage).
- JSON import/export capabilities to enable persistent storage, sharing, and version control outside of the web browser (e.g. by using git).
- Markdown and PDF static downloads of the threat model document.
- Workspace separation to allow working on multiple threat models.
We've included an example of how you could use Threat composer to create a threat model, we have chosen the threat composer tool itself as an example to illustrate this. This threat model does not claim to be 100% complete for every possible interaction. It aims to give the reader an example of what a set of threats, assumptions and mitigations could look like. We've chosen to share this example as it provides a common reference point for people who are starting off with Threat composer. You may have different perspectives on the assumptions, threats and mitigations. This is ok, and could be used to start conversations in your organization with the context of your risk appetite. You may want to use this as he base threat model as a starting point to generate a contextualised threat model for your own specific needs and deployment of Threat composer. You are responsible for making your own independent assessment of this threat model and its applicability to your organization.
To view the example threat model simply switch to the system-defined Example Workspace.
No changes you make within Example workspace will be saved. If you wish to modify it or use is a base, it's recommended you Export it, create a new Workspace and Import it.
We value your input! Please take a moment to provide us with your feedback. Thank you for helping us improve!
For bugs, issues and feature requests, please use GitHub issues.
You can try the threat-composer demo via the Github Pages deployment. It's RECOMMENDED that you use the included AWS Cloud Development Kit (CDK) app to self-host the static website, support your customization, and continuous development. Refer to the Security considerations section and Deployment section.
If you use threat-composer via your AWS account, please note that any sample code, software libraries, command line tools, proofs of concept, templates, or other related technology are provided as AWS Content or Third-Party Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content or Third-Party Content in your production accounts, or on production or other critical data. You are responsible for testing, securing, and optimizing the AWS Content or Third-Party Content, such as sample code, as appropriate for production grade use based on your specific quality control practices and standards. Deploying AWS Content or Third-Party Content may incur AWS charges for creating or using AWS chargeable resources, such as running Amazon EC2 instances or using Amazon S3 storage.
This tool stores all user-supplied input only within your browsers local storage (there is no backend or API). Given the nature of the data that you could be storing you should take the necessary steps to secure access to your browser, and keep your browser and operating system software up-to-date.
The tool supports the export of data out of the browser local storage to a local file, ensure that you are applying the appropriate protections to these file exports in terms of least privilege access control, encryption-at-rest and encryption-in-transit.
By default the WebACL associated with the CloudFront distribution is configured to only allow 192.160.0.0/24 (non-routable networks) to reach the static assets. You’d need to modify the configuration of the CDK application to ensure that you are able to scope access to your network(s) (see ‘Configuration’ section).
In the default configuration there is no authentication to reach the static web assets. You should integrate this with whatever identity management solution you currently use. To add authentication you would need to customise this application. One approach you could consider is to create a Lambda@Edge function to enforce authentication and associated cookie validation, then attach this function to the Amazon CloudFront distribution to protect the static web assets (see ‘Configuration’ section). You’d especially want to consider this if you modify the sample application to include your own data, such as example threat statements.
It’s recommended that you use a scoped down IAM policy to when interacting with CDK and it’s recommended that you consider customising and attaching the below example to the IAM Principal being used. This policy is scoped down, but does include some powerful permissive actions such as iam:* as CDK requires a role to do things like create IAM Roles, S3 Buckets, ECR repositories and SSM parameters when bootstrapping. The policy does scope each of the allowed actions to resources typically associated with CDK only (specifically, CDKToolkit/* stack, and resources with a cdk- prefix).
Note: You’d need to change the <aws-account-id> and <aws-region> to align to your values.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "0",
"Effect": "Allow",
"Action": [
"cloudformation:DescribeStacks",
"cloudformation:CreateChangeSet",
"cloudformation:DescribeChangeSet",
"cloudformation:ExecuteChangeSet",
"cloudformation:DeleteChangeSet",
"cloudformation:DescribeStackEvents",
"cloudformation:DeleteStack",
"cloudformation:GetTemplate"
],
"Resource": "arn:aws:cloudformation:<aws-region>:<aws-account-id>:stack/CDKToolkit/*"
},
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole",
"iam:*"
],
"Resource": [
"arn:aws:iam::*:role/cdk-*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:*"
],
"Resource": [
"arn:aws:ssm:<aws-region>:<aws-account-id>:parameter/cdk-*"
]
},
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::cdk-*"
]
},
{
"Effect": "Allow",
"Action": [
"ecr:*"
],
"Resource": [
"arn:aws:ecr:<aws-region>:<aws-account-id>:repository/cdk-*"
]
}
At the time of writing it is not possible to configure HSTS (HTTP Strict Transport Security) or custom HTTP headers for GitHub pages, and it’s recommended that you deploy threat-composer into your AWS account where these additional protections have been configured in the provided CDK project.
This tool includes a simple CSP (Content Security Policy) that should be customised to your needs and use-case. For example, to support showing architecture and data-flow diagrams from URLs the included CSP allows images loads from any source (img-src: *), you may want to scope this to the specific domain(s) that you wish to limit this too.
You should only import content into threat-composer from sources that you trust.
Like all software, it’s important that you have an on-going process in place to ensure that you are performing vulnerability management of the code included in this package and all of it’s dependencies. In this GitHub repository, we leverage dependabot security alerts and dependabot security updates to detect and update vulnerable dependencies.
Watch this repository for updates and deploy the latest changes. See ‘Maintenance’ section for each Deployment option below on how to deploy the latest changes.
When using the default CloudFront domain and certificate (*.cloudfront.net), CloudFront automatically sets the security policy to TLSv1. It’s recommended that you use a custom domain and certificate with the CloudFront distribution and configure it to use use a Security Policy that does not allow older protocols such as TLS 1.0. Consider using the TLSv1.2_2021 Security Policy.
The AWS Well-Architected Framework helps you understand the pros and cons of decisions you make while building systems on AWS. By using the Framework you will learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems in the cloud.
- Threat modeling for builders training - AWS Skill Builder - This free eLearning aims to teach you the fundamentals of performing threat modeling, with knowledge checks and exercises that use the threat-composer tool.
- How to approach threat modeling - AWS Security Blog provides observations and tips for practical ways to incorporate threat modeling into your organization, which center around communication, collaboration, and human-led expertise to find and address threats that your end customer expects.
Important: This application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the AWS Pricing page for details. You are responsible for any AWS costs incurred.
- NodeJS (version 18 or higher)
- Yarn (installed via
npm install -g yarn) - PDK (installed via
npm install -g @aws/pdk) - AWS CLI (version 2 or higher)
- AWS CLI Configuration (configured via
aws configure) - AWS CDK v2 CLI (installed via
npm install -g aws-cdk) - CDK Bootstrapping (e.g.
cdk bootstrap aws://<your_aws_account_id>/<aws-region>)
See Deployment section below for more instructions about CDK bootstrapping.
- git-remote-codecommit (e.g.
pip install git-remote-codecommit)
The threat-composer Infra CDK app support customization like custom domain name. You can update the configuration in the configuration file to set it up. The configuration file is located at packages/threat-composer -infra/cdk.context.json. Note that all the configurations are OPTIONAL.
Important note: The default values for cidrRangesDev and cidrRangesProd are non-routable CIDR ranges. In order to access threat-composer you've need to update these values to ranges that align with your access needs.
| Configuration Property | Description |
|---|---|
| repositoryName | (Optional) The CodeCommit repository name if Deployment with CI/CD option is used |
| accountPipeline | (Optional) The AWS account for deploying CodeCommit repository and CI/CD pipeline if Deployment with CI/CD option is used. Default value: current account |
| accountDev | (Optional) The AWS account for deploying dev instance of application stack. Default value: current account |
| accountProd | (Optional) The AWS account for deploying prod instance of application stack if Deployment with CI/CD option is used. |
| cidrTypeDev | (Optional) The IP address type for dev instance of WAF WebAcl IPSet. Options are IPV4 or IPV6. Default value: IPV4. |
| cidrTypeProd | (Optional) The IP address type for prod instance of WAF WebAcl IPSet. Options are IPV4 or IPV6. Default value: IPV4. |
| cidrRangesDev | (Optional) The IP address ranges for dev instance of WAF WebAcl IPSet. Multiple values is supported via , separator. Default value: 192.168.0.0/24. |
| cidrRangesProd | (Optional) The IP address ranges for prod instance of WAF WebAcl IPSet. Multiple values is supported via , separator. Default value: 192.168.0.0/24. |
| domainNameDev | (Optional) The custom domain name for dev deployment |
| domainNameProd | (Optional) The custom domain name for prod deployment |
| certificateDev | (Optional) The AWS Certificate Manager certificate ARN for the custom domain name of dev deployment if custom domain name is used |
| certificateProd | (Optional) The AWS Certificate Manager certificate ARN for the custom domain name of prod deployment if custom domain name is used |
| hostZoneNameDev | (Optional) The Route 53 host zone for the custom domain name of prod deployment if host zone record creation is required |
| hostZoneNameProd | (Optional) The Route 53 host zone for the custom domain name of prod deployment if host zone record creation is required |
| lambdaEdgeDev | (Optional) The lambda edge function ARN attached to CloudFront VIEWER_REQUEST event for CloudFront dev instance or the AWS Systems Manbager(SSM) parameter name (in us-east-1) storing the Lambda edge function ARN |
| lambdaEdgeProd | (Optional) The lambda edge function ARN attached to CloudFront VIEWER_REQUEST event for CloudFront prod instance or the AWS Systems Manbager(SSM) parameter name (in us-east-1) storing the Lambda edge function ARN |
Following the steps to deploy an instance of application CloudFormation stack into your AWS account. The application CloudFormation stack include a CloudFront distribution, S3 website bucket, and an associated AWS WAF WebACL.
We recommend you bootstrap your CDK project by specifying the specific AWS Managed Policies required for the ‘Static Website Only’ deployment to create the required resources, including Amazon S3 Buckets, IAM Roles, CloudFront Distribution etc. This will ensure that CloudFormation does not use the ‘Admin’ policy:
cdk bootstrap aws://<aws-account-id>/<aws-region> --cloudformation-execution-policies "arn:aws:iam::aws:policy/IAMFullAccess,arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AmazonS3FullAccess,arn:aws:iam::aws:policy/CloudFrontFullAccess,arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess"
Important: To avoid deployment failures, be sure the policies that you specify are sufficient for any deployments you will perform in the environment being bootstrapped. Meaning if you are using CDK bootstrap for other CDK apps in the same account, you may need to adjust the permissions to be inclusive of what is needed for other applications.
Learn more about customising CDK bootstrap here.
-
Clone the repository
git clone https://github.com/awslabs/threat-composer.gitcd threat-composer -
Run script:
./scripts/deployDev.sh
The script will install dependencies, build the project, and deploy the application CloudFormation stack.
If the script is run successfully, you will see output of your CloudFront domain name. Visit the URL or specified custom domain name (if provided) in a web browser to access the deployed website.
It is recommended to watch this GitHub repository for any updates and run the commands below periodically from the project root directory to deploy the latest changes in our GitHub repository:
git pull origin main
./scripts/deployDev.sh
If you are planning to customize the configurations or update code to fit your use cases, it is recommended to deploy the whole CI/CD infrastructure CloudFormation Stack. The CI/CD infrastructure includes a CodeCommit repository and a CodePipeline. The CodePipeline deploys the application stack (CloudFront distribution + S3 website bucket + AWS WAF WebACL) into the nominated dev and prod environments.
This deployment option does create resources beyond what is created in the ‘Static website only’ deployment, such as CodeCommit repository, CodePipeline and KMS keys, hence requires additional permissions within it’s CloudFormation execution policy. At the time of writing there appears to be a bug with CDK (see issue) when using a cross-account keys within the pipeline that the deployment will only be successful if one attaches the AdministratorAccess policy to the CloudFormation execution role, as follows:
cdk bootstrap aws://<aws-account-id>/<aws-region> --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
You may need to include the --trust option when bootstrapping the dev or production accounts if they are different from the pipeline AWS account shown below. This command is run from the AWS account that has been configured in the property accountDev or accountProd in packages/threat-composer -infra/cdk.context.json. See below for an example.
cdk bootstrap aws://<dev-or-prod-aws-account-id>/us-west-2 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess --trust <pipeline-aws-account-id>
-
Clone the repository
git clone https://github.com/awslabs/threat-composer.gitcd threat-composer -
Deploy the CI/CD infrastructure CloudFormation stack
./scripts/deployAll.sh
The script will install dependencies, build the project, and deploy the CI/CD infrastructure CloudFormation stack.
If the script is run successfully, you will see output of your CodeCommit repository GRC URL.
-
Add the newly created CodeCommit repo as a git remote.
git remote add codecommit <CodeCommitGRCUrl> -
Update configuration/code and
git commityour changes -
Push the code to the newly created CodeCommit repo
git push codecommit main
The CodePipeline will be automatically triggered to build the project and deploy the application stack to your nominated dev and prod environments.
It is recommended to watch this GitHub repository for any updates and run the commands below periodically to sync the latest changes in our GitHub repository to the mirrored CodeCommit repository.
git pull --no-rebase origin main
git push codecommit main
This monorepo hosts the code for threat-composer UI components, a create-react-app website, and a CDK app to allow you to deploy the website to your AWS account.
The repository is defined and maintained using projen and aws-prototyping-sdk.
| Project | Path | Description | Tech stack |
|---|---|---|---|
| threat-composer | packages/threat-composer | UI components for threat-composer | React, CloudScape design system |
| threat-composer-app | packages/threat-composer-app | threat-composer Single Page App (SPA) bootstraped by create-react-app | React |
| threat-composer-infra | packages/threat-composer-infra | threat-composer Infrastructure CDK App | aws-prototyping-sdk constructs |
| threat-composer-app-browser-extension | packages/threat-composer-app-browser-extension | threat-composer browser extension | wxt, React |
npm install -g oss-attribution-generator
-
Install dependencies
pdk install --frozen-lockfile -
Build all the projects
pdk build -
Run Storybook
pdk run storybookRuns storybook to navigate all the threat-composer UI components Open http://localhost:6006 to view it in the browser. The page will reload if you make edits.
It is recommended to use storybook as development environment.
-
Start website in dev mode
pdk run dev -
For the browser extension (Chrome and Firefox) please see this README
Contribution guide are available at the Contributing Guidelines.
This project is licensed under the Apache-2.0 License.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
