threat-composer

Goal

A simple threat modeling tool to help humans to reduce time-to-value when threat modeling

----> Live demo <----

Summary

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:

1. 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.
2. 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.
3. 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.
4. 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.

Features

• 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.

Threat model example

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.

Feedback

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.

Usage

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.

Security considerations

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.

Data protection

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.

Network accessibility

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).

Authentication

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.

Identity and Access Management (IAM) permissions for CDK

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-*"
            ]
        }
   

GitHub Pages

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.

Content Security Policy

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.

Importing content

You should only import content into threat-composer from sources that you trust.

Vulnerability management

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.

CloudFront Security Policy

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.

AWS Well-Architected Framework

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.

Learn how to threat model

• 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.

Deployment

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.

Prerequisites

• NodeJS (version 16 or higher)
• Yarn (installed via npm install -g yarn)
• 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)

Configuration

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.

Deployment - Static Website Only

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.

Deployment Instructions

1. Clone the repository

   git clone https://github.com/awslabs/threat-composer.git

   cd threat-composer

2. 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.

Maintenance

It is recommended to watch this GitHub repository for any updates and run the commands below periodically to deploy the latest changes in our GitHub repository:

git pull origin main

/scripts/deployDev.sh

Deployment – With CI/CD

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

Deployment Instructions

1. Clone the repository

   git clone https://github.com/awslabs/threat-composer.git

   cd threat-composer

2. 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.

1. Add the newly created CodeCommit repo as a git remote.

   git remote add codecommit <CodeCommitGRCUrl>

2. Update configuration/code and git commit your changes

3. 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.

Maintenance

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

Development

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.

Repository Structure

Prerequisites

• git-secrets
• oss-attribution-generator

npm install -g oss-attribution-generator

Commands

• Install dependencies

  yarn install --frozen-lockfile & npx projen

• Build all the projects

  yarn run build

• Run Storybook

  yarn run storybook

  Runs 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

  yarn run dev

Contribution guide

Contribution guide are available at the Contributing Guidelines.

License

This project is licensed under the Apache-2.0 License.