Threat Designer: AI-powered threat modeling for secure system design

Threat Designer is an AI-driven agent that automates and streamlines the threat modeling process for secure system design. Harnessing the power of large language models (LLMs), it analyzes system architectures, identifies potential security threats, and generates detailed threat models—empowering developers and security professionals to incorporate security from the earliest stages of development.

---

Quick Links

• 📖 Read the AWS Blog Post
• 🏢 Customer story: How TUI scales threat modeling for 100+ teams
• ⭐ Star this repo to support the project
• 📚 Getting started Guide
• 💻 CLI Quick Start — no deployment needed, runs fully local
• 📘 Code Wiki

---

CLI — No Deployment Required

Want to run threat modeling without deploying any AWS infrastructure? The Threat Designer CLI lets you generate STRIDE-based threat models entirely on your local machine, using only your existing Amazon Bedrock or OpenAI credentials.

pip install ./cli
threat-designer

See the CLI Quick Start guide to get up and running in minutes.

---

Features

• Architecture Analysis - Submit up to 3 architecture diagrams per submission and analyze for threats
• Interactive Editing - Update threat modeling results via the user interface
• Iterative Refinement - Replay threat modeling based on your edits and additional input
• Multiple Export Formats - Export results in PDF, DOCX, or JSON format
• AI Assistant (Sentry) - Interact with a built-in assistant to dive deep into threat models
• Spaces - Attach a knowledge base of your own documents (runbooks, policies, diagrams) to enrich threat modeling with organization-specific context
• Threat Catalog - Explore and manage past threat models

---

Architecture

Solution Architecture

AWS Services Used:

• AWS Amplify
• Amazon API Gateway
• Amazon Cognito
• AWS Lambda
• Amazon Bedrock AgentCore Runtime
• Amazon Bedrock Knowledge Bases
• Amazon OpenSearch Serverless
• Amazon DynamoDB
• Amazon S3

Agent Logic Flow

---

Getting Started

Prerequisites

Required Tools:

The following tools must be installed on your local machine:

• Node.js (v18 or later) and npm
• curl
• jq
• Python (v3.12 or later) and pip
• Terraform CLI
• Docker running
• AWS CLI configured with appropriate credentials

AI Model Provider:

Threat Designer supports two AI providers. Choose one based on your preference:

Option 1: Amazon Bedrock (Default)

You must enable access to the following models in your AWS region:

• Claude Opus 5.5
• Claude Sonnet 5
• Claude Haiku 4.5

To enable Claude models, follow the instructions here. Make sure you are already subscribed to the models otherwise you will receive an AccessDeniedException exception whe using the application.

Note: If deploying in a non-US region, verify the inference profile ID for your region. See Supported Regions and models for inference profiles.

Option 2: OpenAI

You'll need:

• A valid OpenAI API key
• Access to the GPT models used (GPT-6 Sol, GPT-5.6 Terra, GPT-5.6 Luna)

You'll be prompted to enter your API key during deployment.

Option 3: Amazon Bedrock Runtime (GPT models on Bedrock)

The same GPT models served through the OpenAI-compatible route of the Amazon Bedrock Runtime endpoint. No OpenAI API key is required: authentication uses SigV4-derived bearer tokens minted from the agent's IAM role.

Note: GPT models on Bedrock Runtime are only available through the global cross-region inference profile, so requests may be processed in any commercial AWS region.

Installation and Deployment

1. Clone the Repository

git clone https://github.com/awslabs/threat-designer.git
cd threat-designer

2. Make the deployment script executable:

chmod +x deployment.sh

3. Export AWS credentials

# Option I: Export AWS temporary credentials
export AWS_ACCESS_KEY_ID="your_temp_access_key"
export AWS_SECRET_ACCESS_KEY="your_temp_secret_key"
export AWS_SESSION_TOKEN="your_temp_session_token"
export AWS_DEFAULT_REGION="your_region"

# Option II: Export AWS Profile
export AWS_PROFILE="your_profile_name"

4. Run the deployment:

./deployment.sh

During deployment, you'll be prompted to:

• Select your AI model provider (Amazon Bedrock, OpenAI, or Amazon Bedrock Runtime for GPT)
• Enter your OpenAI API key (if using OpenAI)
• Provide a valid email address for user credentials
• Choose whether to enable Sentry AI Assistant
• Select a web search provider for Sentry (none, Tavily, or Amazon Bedrock AgentCore)

Note: A user will be created in Amazon Cognito User Pool and temporary credentials will be sent to the configured email address.

Accessing the Application

After successful deployment, you can find the Login URL in the output:

Application Login page: https://dev.xxxxxxxxxxxxxxxx.amplifyapp.com

---

Configuration Options

AI Model Provider Selection

Threat Designer supports three AI provider options that can be selected during deployment:

Select AI model provider:
1) Amazon Bedrock (Claude) (default)
2) OpenAI (GPT)
3) Amazon Bedrock Runtime (GPT, no OpenAI API key needed, runs in your deployment region)

Amazon Bedrock Configuration (default model)

Used Models:

• Claude Opus 5.5 — main threat modeling workflow, attack trees, and Sentry assistant
• Claude Sonnet 5 — structured output
• Claude Haiku 4.5 — summaries

Key Characteristics:

• Reasoning: Adaptive thinking (Claude 5 family)
• Reasoning Levels: Low, Medium, High, Extra High (maps to adaptive effort levels; token budgets remain only for pre-4.6 models)

Note: Models listed in the adaptive_thinking_models Terraform variable (e.g., Claude Opus 5.5, Claude Sonnet 5) use adaptive thinking with effort levels instead of token budgets. For these models, the reasoning_budget configuration is ignored — the reasoning level from the UI is mapped directly to an effort string. Pre-4.6 models continue to use token-budget-based reasoning as before.

Note: The highest selectable level (Extra High) maps to xhigh, the recommended effort for demanding coding and agentic work. The models also support max above it, but it costs substantially more for marginal gains — opt in per stage by setting "4" = "max" in that stage's effort_map in infra/variables.tf.

Note: There is no "off" reasoning level. Every current model is a reasoning model, and on Claude Opus 5 thinking is on by default and cannot be disabled above effort high — omitting the thinking config does not turn it off, it just runs adaptive thinking at the provider's default effort. An "off" level therefore billed for thinking while discarding the reasoning output, so the ladder starts at Low. Levels are 1–4; a legacy 0 from an older client is accepted and normalized to 1.

Note: Claude 5 family models support a maximum output of 128K tokens, while older Claude 4.x models may support less. If switching between models, make sure to update the max_tokens configuration accordingly to avoid API errors.

OpenAI Configuration

Used Models:

• GPT-6 Sol — main threat modeling workflow, attack trees, and Sentry assistant (flagship capability)
• GPT-5.6 Terra — structured output (strong performance at lower price)
• GPT-5.6 Luna — summaries (efficient, high-volume workloads)

Key Characteristics:

• Reasoning: Reasoning models on the Responses API
• Reasoning Levels: Low, Medium, High, Extra High (maps to OpenAI's reasoning_effort: low, medium, high, xhigh). GPT models also support max above xhigh — opt in via reasoning_effort in infra/variables.tf — and no longer accepts minimal.

To use OpenAI:

1. Select option 2 when prompted for model provider during deployment
2. Enter your OpenAI API key when prompted
3. The system will configure both Threat Designer and Sentry to use OpenAI

Amazon Bedrock Runtime (GPT) Configuration

Runs the same GPT models (and prompts) as the OpenAI option, served by the OpenAI-compatible Responses route of the Bedrock Runtime endpoint (/openai/v1):

• No OpenAI API key: auth is a SigV4-derived bearer token minted from the agent's IAM role (the bedrock:InvokeModel and bedrock:CallWithBearerToken permissions are granted automatically at deploy time)
• Deployment region: calls go to the Bedrock Runtime endpoint in your deployment region (override with the bedrock_openai_region Terraform variable)
• Global inference profile: model IDs are automatically prefixed with global.openai. (e.g., global.openai.gpt-6-sol), so requests may be processed in any commercial AWS region

To use Amazon Bedrock Runtime for GPT:

1. Select option 3 when prompted for model provider during deployment
2. The system will configure both Threat Designer and Sentry to use GPT via Bedrock Runtime

Switching Between Providers

To switch between Amazon Bedrock and OpenAI:

1. Redeploy the solution using ./deployment.sh
2. Select a different provider when prompted

Important: Existing conversation sessions from one provider cannot be continued with a different provider. You'll need to start new threat modeling sessions after switching.

Web Search Integration (Optional Feature)

Sentry can perform real-time web searches to research CVEs, vulnerabilities, and security topics. This feature is optional, and you choose the provider at deployment time.

Enabling Web Search

During deployment, you will be prompted:

Select web search provider for Sentry:
1) None (default)
2) Tavily (search + page extraction, requires an API key)
3) Amazon Bedrock AgentCore (search only, no API key needed)

Provider	Tools Sentry gains	Credentials
None	—	—
Tavily	tavily_search + tavily_extract	Tavily API key
Bedrock AgentCore	web_search only	None — SigV4 from the Sentry execution role

Note: The AgentCore connector offers search only — there is no page-extraction counterpart. When it is selected the extract tool is simply absent, and Sentry's prompt is adjusted so it works from result snippets and does not offer to read a page in depth. Choose Tavily if you need full page content.

Amazon Bedrock AgentCore

AgentCore's web search is reachable only as a built-in connector target on an AgentCore Gateway (there is no direct search API), so selecting it provisions a gateway with AWS_IAM inbound auth plus its service role, and Sentry calls it over MCP signed with SigV4 from its own execution role. No API key is stored anywhere.

Warning: The connector is only offered in us-east-1, eu-west-1, and ap-northeast-1. The gateway is created in web_search_region (default us-east-1), which may differ from your deployment region — queries are served inside AWS but can leave the deployment's region. Tune result volume with the web_search_max_results Terraform variable (1–25, default 5).

Getting a Tavily API Key

1. Sign up at tavily.com
2. Navigate to your dashboard to get your API key
3. Keys start with tvly- prefix

Web Search Capabilities

When enabled, Sentry can:

• Search for CVEs and vulnerability information
• Research threat intelligence and attack techniques
• Look up technical security documentation
• Extract content from security advisories and research papers

Web search is focused on security-related topics and will not search for general information, people, or organizations.

---

Sentry AI Assistant (Optional Feature)

Sentry is an AI-powered assistant that helps you analyze and explore threat models through conversational interaction. This feature is optional and can be enabled or disabled during deployment.

Enabling/Disabling Sentry During Deployment

When you run ./deployment.sh, you will be prompted:

Enable Sentry AI Assistant? (y/n, default: y)

• Enable (y): Deploys the full Sentry infrastructure including Amazon Bedrock AgentCore Runtime, DynamoDB session table, and ECR repository. The Assistant drawer will be available in the UI.
• Disable (n): Skips Sentry infrastructure deployment. The Assistant drawer will be hidden from the UI, and core threat modeling features will continue to work normally.

Toggling Sentry in Existing Deployments

To disable Sentry:

1. Update the .deployment.config file in the project root:

ENABLE_SENTRY=false

2. Redeploy the solution

To enable Sentry:

1. Update the .deployment.config file in the project root:

ENABLE_SENTRY=true

2. Redeploy the solution

---

Threat Modeling Methodology

Threat Designer supports two methodologies, selectable per threat model:

• STRIDE (default) — classifies threats by kind: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege.
• MAESTRO — the Cloud Security Alliance's agentic AI threat modeling framework. Classifies threats by where they sit in the agentic stack across seven layers, and is the better fit for systems built around agents, tools and multi-agent collaboration.

Existing threat models are unaffected — they remain STRIDE, and a model's methodology is fixed once created so a catalog is never classified along two axes at once.

Toggling MAESTRO

MAESTRO is enabled by default. To disable it, update the .deployment.config file in the project root and redeploy:

ENABLE_MAESTRO=false

When disabled, the API rejects new requests that ask for MAESTRO rather than silently falling back to STRIDE. Replaying or versioning an existing MAESTRO model is unaffected by the flag — its methodology is fixed at creation and is loaded from the stored record either way, so disabling MAESTRO doesn't strand catalogs created while it was on. STRIDE threat modeling is unaffected either way.

---

Governance (System Spaces)

The Governance page manages System Spaces: organization-managed knowledge bases that are queried for every threat model, in addition to any team Space a user attaches to a specific run. Use them for mandatory context that should always apply, such as compliance requirements, approved configurations, and internal security standards. Insights from a System Space are labeled as organization standards so the agent and the Trail can tell them apart from team documents.

Uploading, editing, and deleting System Spaces works the same as a regular Space, but the page and its API are restricted to members of the governance Cognito group. Non-members do not see the Governance entry in the sidebar, and the backend enforces the same restriction independently (a live group check against Cognito on every request), so the UI gate is not the only line of defense.

Granting access

Membership is managed directly in the Cognito console (there is no in-app admin UI):

1. Open the Cognito User Pool created by the deployment.
2. Create the governance group if it does not exist (the deployment provisions it; the group name is configurable).
3. Add the user to the group.

Note: A newly added member must sign out and sign back in before the Governance page appears. Group membership is carried in the ID token claim, and the frontend reads it from there; the claim is only refreshed on a new sign-in. The backend authorizes against Cognito live, so a revoked member loses API access within about a minute regardless of their token, but the sidebar entry follows the token claim.

---

Clean Up

1. Empty the Architecture Bucket, following instructions here

2. Make the destroy script executable:

chmod +x destroy.sh

3. Export AWS credentials

# Option I: Export AWS temporary credentials
export AWS_ACCESS_KEY_ID="your_temp_access_key"
export AWS_SECRET_ACCESS_KEY="your_temp_secret_key"
export AWS_SESSION_TOKEN="your_temp_session_token"
export AWS_DEFAULT_REGION="your_region"

# Option II: Export AWS Profile
export AWS_PROFILE="your_profile_name"

4. Execute the script:

./destroy.sh

---

End-to-end tests

The frontend has a Playwright suite that runs the app against a fully mocked backend — no AWS, Cognito, or Bedrock required. VITE_E2E_MOCK=true swaps Amplify auth for a mock module (src/e2e/amplifyAuthMock.js) and Playwright intercepts every business API call.

bun install
bunx playwright install chromium         # one-time browser download

bun run test:e2e                         # full suite, headless (~24s)
bun run test:e2e:headed                  # visible browsers
bun run test:e2e:ui                      # interactive runner
bun run test:e2e -- e2e/tests/wizard     # scope to one suite

Playwright auto-boots bun run dev:e2e on port 5173 — no need to start the dev server separately. The HTML report opens with open playwright-report/index.html after a run. See e2e/README.md for the harness details and how to add suites.

---

Contributing

See CONTRIBUTING for more information.

License

This library is licensed under the Apache License. See the LICENSE file.