# Threat Composer: a threat model as a diagram and a diffable JSON file

> Threat Composer is an ecosystem of threat modeling tools, from a browser application and a VS Code extension to an AI assisted CLI and an MCP server, that keeps the model in a .tc.json file so it can be reviewed, versioned and exported. The web app and the IDE extension are marked stable, while the AI components are still experimental and cost money per inference.

**awslabs/threat-composer** — A simple threat modeling tool to help humans to reduce time-to-value when threat modeling

- Repository: https://github.com/awslabs/threat-composer
- Website: https://awslabs.github.io/threat-composer/
- Stars: 792 · Forks: 126
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/awslabs-threat-composer

## An ecosystem rather than a single application

Threat Composer is described as a simple threat modeling tool to help humans reduce time-to-value when threat modeling, and as an ecosystem of threat modeling tools. The two descriptions sit together because the project ships four separate ways of working with the same model, and each has a different maturity label.

The web application is marked stable and is available two ways. There is a hosted version on GitHub Pages to try immediately, and there is a self hosted static site you deploy to your own AWS account with full customisation. The VS Code extension is also marked stable, and it edits the .tc.json files directly in the editor, with the AWS Toolkit integration and version control support. The AI powered CLI and MCP server are marked experimental, and the browser extension for viewing models on GitHub, GitLab, Bitbucket and Amazon CodeCatalyst is experimental too.

That distribution of stability is the most useful thing in the README for an evaluator. The core, the file format and the diagram editor are settled, while the automated generation path is explicitly a work in progress.

The stated purpose is to help identify security issues and develop strategies to address them in the context of your system, and the design goal is to support the iterative and non-linear nature of real-world threat modeling. That is a design position rather than a feature list, and it explains the rest of the project.

## Threat grammar and the shape of a threat statement

The feature that makes Threat Composer different from a freeform diagram tool is the threat grammar, a structured way of writing threats with adaptive suggestions, with full examples for inspiration. The grammar is documented by AWS in their threat modelling catalogue, and the tooling uses it to help you iteratively write useful threats rather than leave you in front of an empty box.

The grammar matters because a threat model is only useful if two people write the same kind of sentence. A free text field produces notes, and notes do not compare well across reviews. A grammar produces a statement with structure, which is what makes the other features possible at all.

Around the grammar sit the rest of the model elements. Assumptions can be documented and linked to the threats and mitigations they underpin, which is the part most threat models leave implicit and therefore lose. There is an insights dashboard with quality metrics and suggestions for improvement, and reusable threat and mitigation packs that are self hosted, so an organisation can carry its own standard library of threats rather than starting from nothing each time.

## The .tc.json file and what the web app does with it

Everything in the ecosystem converges on one artefact, a .tc.json file, and the README is explicit that the JSON format works with Git.

That single decision is what makes the other tools possible. The web application stores models in the browser and supports import and export, the VS Code extension edits the same files with a full featured editor, the browser extension renders them from a code host with one click, and the AI tooling generates them. Because the format is a file rather than a database row, a threat model can be reviewed in a pull request, diffed between revisions, and branched.

The export formats listed in the features are JSON, Markdown, DOCX and PDF, which is the usual pattern of a JSON system of record with document exports for consumption, and workspace management lets you work on several threat models at once, which matters when one product has several components.

There is a worked example in the repository: an example threat model of the Threat Composer web application itself, which you open by switching to the Example workspace in the application. The README notes that changes in the Example workspace are not saved, so it is a reference point rather than something to edit, and it is a reasonable way to see what a finished model looks like before you start one.

## The AI CLI and the MCP server on AWS Bedrock

The AI assisted path is the one that generates a starter threat model from your source code, and it is where the cost and the maturity caveats both sit.

The installation uses uv to install the CLI and the MCP server together from the packages/threat-composer-ai subdirectory of the repository:

```bash
uv tool install --from "git+https://github.com/awslabs/threat-composer.git#subdirectory=packages/threat-composer-ai" threat-composer-ai
```

and the CLI then analyses a codebase directly:

```bash
threat-composer-ai-cli /path/to/your/code
```

The MCP server is configured per assistant, and the README gives the shape for Kiro, Cline and Claude Desktop:

```json
{
  "mcpServers": {
    "threat-composer-ai": {
      "command": "threat-composer-ai-mcp",
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-west-2"
      }
    }
  }
}
```

There is a second form that runs the server through uvx with no installation at all, passing the same git subdirectory reference as an argument.

Two things about this path deserve emphasis. It uses AWS Bedrock with a multi-agent architecture, and the README states plainly that Bedrock inference costs apply, with a link to the pricing page. And the component is labelled experimental. The value proposition in the README is that you never face a blank page, while also stating that human expertise and participation remain essential to refine, validate and evolve the model.

## Reading threat models in the editor and in the browser

The two extension tools exist for the same reason the file format is JSON: to get a threat model in front of the person who needs to read it.

The VS Code extension is for the people who live in the repository. It edits the .tc.json files directly, integrates with the AWS Toolkit extension, and provides a full featured editor with version control support. The README recommends installing the AWS Toolkit extension if you want to view and edit the generated files in your IDE with full visual editing capabilities, which is the intended path from generated model to reviewed model.

The browser extension is for the people who do not. It gives one click viewing of .tc.json files on GitHub, GitLab, Bitbucket and Amazon CodeCatalyst, and is available for Chrome and Firefox. That list of code hosts is the point: a reviewer who does not have the repository checked out can still read the model from the pull request page, which is the difference between a threat model that gets reviewed and one that lives in a document nobody opens.

Both extensions read the same file, and neither requires a server, since the format carries the model and the diagram data with it.

## Self hosting the web app and the shape of the monorepo

Deploying the web application to your own AWS account is documented as a three step sequence:

```bash
git clone https://github.com/awslabs/threat-composer.git
cd threat-composer
./scripts/deployDev.sh
```

The Web App documentation covers deployment, configuration and customisation, including CI/CD setup.

The repository is a pnpm workspace driven by Nx, and the root package.json shows the shape of the toolchain. The name is @aws/threat-composer-monorepo, and the scripts are all Nx targets, with build, test, lint, typecheck and a set of end to end targets, including separate ones for the extension and for the browser variants. There is a storybook target, a schema build target, a packs build target, a dependency graph command, and a license checker, plus a generate:attribution script and a LICENSE-THIRD-PARTY file and a NOTICE file, which is the shape you would expect from a tool that ships into an AWS account.

The Dockerfile is a two stage build on Amazon Linux, installing a pinned Node 24 through nvm, pnpm 10, and uv at version 0.11.26 for the AI package, and it runs the build as a non-root user named app. The postinstall hook of the root package runs the AI package install with the Nx daemon disabled, and husky installs the git hooks through the prepare script.

## Where Threat Composer is the wrong tool

Three situations point elsewhere.

The first is a compliance exercise that needs a scan. Threat Composer models threats; it does not analyse your running system for weaknesses. If what you need is a finding about a specific version of a dependency, or evidence that a host is exposed, that is a different category of tool and no amount of threat grammar will produce it.

The second is a team that will not keep the model alive. The fifth reason the README gives for the tool is that it enables iteration and living threat models that evolve with your system, and that only works if the model lives in the repository and is updated. A threat model that is written once and filed away is what the project exists to replace, and adopting the tooling without changing the practice buys a diagram tool.

The third is an environment that cannot reach AWS. The AI assisted CLI and the MCP server run on AWS Bedrock, and the self hosted web application deploys to an AWS account. The static parts of the ecosystem, the web app, the VS Code extension and the browser extension, do not need that, so this is a limit on the automated path rather than on the tool, but it is the limit most likely to bite in a locked down environment.

One practical note on the AI path. It is the component marked experimental, it costs money per inference through Bedrock, and its output is a starter model that the README says still needs human refinement and validation. Treating generated threats as findings rather than as a first draft is the difference between using it well and using it badly.

## Conclusion

Adopt Threat Composer if your team wants a threat model that lives in a repository next to the code, reviewed through pull requests and shared between planners, and if you can host the web application or run the static site yourself. Do not adopt it as a scanner that finds vulnerabilities, since it models threats and does not analyse your running system for flaws, and think twice before wiring the AI components into an automated pipeline while they are labelled experimental. Verify three things first: which components you actually need, since the web app and the VS Code extension are stable while the CLI, MCP server and browser extension are experimental; how you will pay for the AI assisted path, because it runs on AWS Bedrock with a multi-agent architecture and inference costs apply; and where the model files live, because the format is JSON and works with Git but the browser based storage and the self hosted deployment behave differently. The licence is Apache-2.0, the last push was on 2026-10-20, and the newest release is v1.0.86 dated 2026-10-14.

## FAQ

### What is Threat Composer?

It is an ecosystem of threat modeling tools that helps identify security issues and develop strategies to address them in the context of your system, designed to support the iterative and non-linear nature of real-world threat modeling. It includes a web application, a VS Code extension, an AI powered CLI and MCP server, and a browser extension.

### In what format does Threat Composer store threat models?

In .tc.json files. The README describes the JSON format as working seamlessly with Git, and the same files are edited in VS Code, viewed from GitHub, GitLab, Bitbucket and CodeCatalyst through the browser extension, and generated by the AI tooling.

### How do I install the Threat Composer AI CLI?

With uv, using uv tool install --from the threat-composer-ai subdirectory of the GitHub repository, which provides both the CLI and the MCP server. You then run threat-composer-ai-cli against a path to your code, and the MCP server is configured per assistant with AWS_PROFILE and AWS_REGION environment variables.

### Does using the Threat Composer AI tools cost anything?

Yes. The AI powered CLI and MCP server use AWS Bedrock with a multi-agent architecture, and the README states that Bedrock inference costs apply with a link to the pricing page. The web application, the VS Code extension and the browser extension do not depend on that path.

### Which Threat Composer components are stable?

The web application, available hosted on GitHub Pages or self hosted on AWS, and the VS Code extension are marked stable. The AI powered CLI and MCP server and the browser extension are marked experimental.

## Sources

- [awslabs/threat-composer on GitHub](https://github.com/awslabs/threat-composer)
- [License: Apache-2.0](https://github.com/awslabs/threat-composer/blob/main/LICENSE)
- [Project website](https://awslabs.github.io/threat-composer/)
- [README](https://github.com/awslabs/threat-composer/blob/main/README.md)
- [Releases](https://github.com/awslabs/threat-composer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/awslabs-threat-composer