threat-composer

Threat Composer

An ecosystem of threat modeling tools to help humans reduce time-to-value when threat modeling.

Live Demo | Documentation | Getting Started

What is Threat Composer?

Threat Composer is a threat modeling ecosystem that helps you identify security issues and develop strategies to address them in the context of your system. The various tools has been designed to support the iterative and non-linear nature of real-world threat modeling.

Why Threat Composer?

1. Helps you get started quickly - The AI-assisted CLI and MCP Server analyze your source code to generate a starter threat model, so you never face a blank page. Human expertise and participation remain essential to refine, validate, and evolve the threat model for your specific context
2. Makes threat identification easier - Uses "Threat Grammar" to help you iteratively write useful threats, with full examples for inspiration
3. Provides quality insights - Includes an insights dashboard to help identify areas for improvement
4. Supports non-linear workflows - Designed for how threat modeling actually works in practice
5. Enables iteration - Supports "living" threat models that evolve with your system

Key Features

• Threat Statement Composition: Structured threat grammar with adaptive suggestions
• Visual Diagrams: Architecture and data flow diagram support
• Assumptions Tracking: Document and link assumptions to threats and mitigations
• Insights Dashboard: Quality metrics and improvement suggestions
• Threat & Mitigation Packs: Reusable threat and mitigation libraries (self-hosted)
• Multiple Export Formats: JSON, Markdown, DOCX, and PDF
• Workspace Management: Work on multiple threat models simultaneously
• Version Control Friendly: JSON format works seamlessly with Git

Threat Composer Ecosystem

Threat Composer is available in multiple complementary tools to fit your workflow:

🌐 Web Application

Hosted or Self-Hosted Static Website

• GitHub Pages: Try the live demo
• Self-Hosted: Deploy to your AWS account with full customization
• Features: Full threat modeling capabilities, browser-based storage, import/export

📖 Web App Documentation

🤖 AI-Powered CLI & MCP Server

Automated Threat Modeling

• CLI: Analyze codebases and generate starter threat models automatically
• MCP Server: Workflow management and schema validation for AI assistants
• Uses AWS Bedrock with multi-agent architecture
• Note: Bedrock inference costs apply - see pricing

📖 AI/CLI/MCP Documentation

🔌 VS Code Extension

Native Threat Modeling in Your IDE

• Edit Threat Composer .tc.json files directly in VS Code
• Integrated with AWS Toolkit extension
• Full-featured editor with version control support

📖 VS Code Extension Documentation

🧩 Browser Extension

View Threat Models on the Web

• One-click viewing of Threat Composer .tc.json files on GitHub, GitLab, Bitbucket and Amazon CodeCatalyst
• Available for Chrome and Firefox

📖 Browser Extension Documentation

Getting Started

Try It Now

Web Application: Visit the live demo to start threat modeling immediately in your browser.

VS Code: Install the AWS Toolkit extension to view and edit local .tc.json files.

Use the AI CLI & MCP Server

Generate threat models automatically from your codebase with the CLI, or integrate with AI assistants using the MCP server:

# Install with uv (provides both CLI and MCP server)
uv tool install --from "git+https://github.com/awslabs/threat-composer.git#subdirectory=packages/threat-composer-ai" threat-composer-ai

# Use the CLI to analyze your codebase
threat-composer-ai-cli /path/to/your/code

MCP Server Configuration (for Kiro, Cline, Claude Desktop, etc.):

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

Or run directly with uvx (no installation required):

{
  "mcpServers": {
    "threat-composer-ai": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/awslabs/threat-composer.git#subdirectory=packages/threat-composer-ai",
        "threat-composer-ai-mcp"
      ]
    }
  }
}

The MCP server provides tools for starting workflows, monitoring progress, managing sessions, and validating threat models against the Threat Composer schema.

💡 Best Experience: For the best experience when using the CLI from VS Code/Kiro terminal or when using AI assistants via MCP, install the AWS Toolkit extension which includes the Threat Composer VS Code extension. This allows you to view and edit the generated .tc.json files directly in your IDE with full visual editing capabilities.

See AI/CLI/MCP Documentation for complete installation and usage instructions.

Self-Host the Web Application

Deploy Threat Composer to your AWS account:

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

See Web App Documentation for detailed deployment options including CI/CD setup.

Example Threat Model

We've included an example threat model of the Threat Composer Web App itself. This provides a reference point for getting started.

To view it, switch to the Example workspace in the application. Note: Changes in the Example workspace are not saved.

Documentation

User Guides

• Web Application - Deployment, configuration, and customization
• VS Code Extension - Installation and usage in VS Code
• Browser Extension - View threat models on GitHub and CodeCatalyst
• AI/CLI/MCP - Automated threat modeling with AI

Developer Resources

• Development Guide - Setup, architecture, and contribution guidelines
• Contributing Guidelines - How to contribute to the project
• Code of Conduct - Community guidelines

Learning Resources

• Threat Modeling for Builders - AWS Skill Builder - Free eLearning course
• How to Approach Threat Modeling - AWS Security Blog - Best practices and tips
• Threat Modeling Workshop - Hands-on workshop materials

Feedback & Support

We value your input!

• Feedback Survey: Share your thoughts
• Bug Reports & Feature Requests: GitHub Issues
• Discussions: GitHub Discussions

Quick Links

For Users

• Live Demo
• AWS Toolkit for VS Code

For Developers

• Development Setup
• Repository Structure
• Contributing Guide
• API Documentation

Repository Structure

This is a monorepo containing multiple packages:

Package	Description	Documentation
threat-composer	Core UI components library	README
threat-composer-app	Web application (SPA)	README
threat-composer-app-browser-extension	Browser extension	README
threat-composer-infra	AWS CDK infrastructure	README
threat-composer-ai	AI CLI & MCP server (Experimental)	README

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on:

• Code of conduct
• Development setup
• Pull request process
• Coding standards

Security

See CONTRIBUTING for information on reporting security issues.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

Acknowledgments

Built with:

• React and CloudScape Design System
• AWS CDK
• pnpm workspaces and nx for the monorepo
• Strands for AI agent orchestration