View a markdown version of this page

Create a threat model - AWS Security Agent
PrerequisitesHow AWS Security Agent runs a threat modelAccess the threat models pageCreate a threat modelRun a threat modelMonitor a threat model runEdit a threat modelDelete a threat modelNext steps

Create a threat model

Create threat models in the AWS Security Agent web application to analyze your application’s architecture and identify security threats. A threat model produces two main outputs: a system overview that describes how your system is built and behaves, and a set of threats that describe how the system could be attacked, each with a severity level, STRIDE classification, and actionable recommendations.

A threat model accepts two kinds of inputs, and you can provide either or both:

  • Scope docs – Technical design documents, API specifications, or architecture documentation that define what the threat model focuses on. When provided, the agent scopes its analysis to the context described in these documents. You can upload files (DOC, DOCX, JPEG, MD, PDF, PNG, TXT), provide S3 URIs, or connect Confluence pages through an integration.

  • Sources – Source code from connected repositories (GitHub, GitHub Enterprise Server, GitLab, GitLab Self-Managed, or Bitbucket) or from S3 locations. AWS Security Agent reads source code to understand your existing system. When combined with scope docs, the source code provides context about the current implementation.

In this procedure, you create a threat model by configuring its inputs and permissions, then start a run.

Prerequisites

Before you begin, ensure you have:

  • Access to the AWS Security Agent web application

  • At least one of the following:

    • A connected repository (GitHub, GitHub Enterprise Server, GitLab, GitLab Self-Managed, or Bitbucket) to use as a source (see Enable threat modeling)

    • An S3 bucket containing source code

    • Design documents to upload as scope docs, or a Confluence integration

Tip

If you already have repositories or S3 buckets connected to your Agent Space (for example, through code review or penetration testing setup), you can create a threat model immediately — no additional setup is required.

How AWS Security Agent runs a threat model

The inputs you provide determine how AWS Security Agent runs the threat model. There are three scenarios.

Inputs you provide How AWS Security Agent runs the threat model

Sources only (source code)

AWS Security Agent analyzes the source code to understand your application’s structure, classifies components, extracts data flows, builds a threat model, and identifies threats based on how the system is actually implemented.

Scope docs only (design documents)

AWS Security Agent runs a threat model focused on the design described in your documents. It identifies threats based on the architecture, data flows, and components described in the scope docs — useful for threat modeling a design before any code exists.

Both sources and scope docs

AWS Security Agent scopes the threat model to the context described in the scope docs (for example, a design document for a new feature). It uses the source code to understand your existing system, then threat models the design described in the scope docs — whether that design is already implemented or not.

Access the threat models page

Navigate to the threat modeling section in the web application.

  1. Log in to the AWS Security Agent web application.

  2. In the left sidebar, choose Threat models.

  3. You’ll see a list of existing threat models with their title, latest run status, and threat counts by severity.

Create a threat model

Set up a new threat model by configuring its inputs and permissions.

  1. On the Threat models page, choose Create threat model.

Configure threat model details

Provide a title for your threat model.

  1. In the Title field, enter a descriptive name for your threat model.

    Tip

    Use a name that identifies the application or service being modeled. For example, "billing-service" or "checkout-api".

Add scope documents

Provide the technical design documents that define what the threat model focuses on, such as architecture documentation, API specifications, or design proposals. When scope docs are provided, the agent scopes its analysis to the context described in these documents. Scope docs are optional if you provide sources.

  1. In the Scope documents section, add documents using one or more of the following methods:

    • Upload files – Upload design documents directly (DOC, DOCX, JPEG, MD, PDF, PNG, or TXT).

    • S3 URIs – Enter S3 URIs pointing to documents stored in connected S3 buckets.

    • Confluence pages – If you have a Confluence integration connected to your Agent Space, select pages from your Confluence workspace.

Tip

For best results, include architecture diagrams, API specifications, and technical documentation that describe your system’s components, data flows, and trust boundaries.

Add sources

Select the source code AWS Security Agent uses to understand your existing system. When combined with scope docs, the source code provides context about the current implementation — the agent uses it to understand what already exists. Sources are optional if you provide scope docs.

  1. In the Sources section, add source code using one or more of the following methods:

Integrated repositories

Select from repositories connected to your Agent Space (GitHub, GitHub Enterprise Server, GitLab, GitLab Self-Managed, or Bitbucket).

  1. Select the checkbox next to each repository you want to include as a source.

  2. Use the search field to find specific repositories by name.

Note

Only repositories connected to your Agent Space appear here. To add more repositories, ask your administrator to update the Agent Space configuration.

S3 sources

Add S3 URIs pointing to source code stored in connected S3 buckets.

  1. Enter the S3 URI for each source code location you want to include.

Configure AWS resources

Select the IAM service role and optional CloudWatch log group for this threat model.

  1. In the Service role dropdown, select the IAM role from your configured service roles.

    Note

    The service role must have permissions to access your source code in S3 and write to CloudWatch logs. Service roles are configured during Agent Space setup in the AWS Management Console.

  2. (Optional) In the Log group dropdown, select a CloudWatch log group to store threat model execution logs.

Create the threat model

  1. Review your configuration.

  2. Choose Create threat model.

You’ll be redirected to the threat model detail page where you can start a run.

Run a threat model

After creating a threat model, start a run to begin the analysis.

  1. On the threat model detail page, choose Start run.

  2. AWS Security Agent begins analyzing your sources and scope docs.

You can also start a run from the Threat models list page by choosing Start run next to the threat model you want to run.

Monitor a threat model run

Track the progress of your threat model as it executes.

Run status

The run page header displays a status indicator:

  • In progress – The threat model agent is running.

  • Stopping – A cancel was requested; the agent is finishing its current task before halting.

  • Completed – The run finished successfully.

  • Failed – The run encountered an error. An error message is displayed with details. Start a new run after resolving the issue.

  • Stopped – The run was canceled by the user. Any threats generated before the stop are preserved.

Run page tabs

On the run detail page, navigate between tabs:

  • Overview – View the run summary (run ID, creation time, status, duration) with a severity distribution chart and breakdown (High, Medium, Low counts). After the run completes, view the system overview produced by the agent.

  • Progress – View the progress of the threat model tasks. Each task shows its status, and you can expand completed tasks to view their detailed logs.

  • Threats – View the threats identified during the run (see Review threats from a threat model).

Run timeout

If a run takes longer than 10 minutes, a warning appears with options to Keep waiting or Cancel run.

Run history

Each threat model maintains a history of all runs. On the threat model detail page:

  • The runs table lists all runs with their start time, status, duration, threats count, and ID.

  • Choose any run’s start time link to view its full details.

Tip

Re-run the same threat model after you update your source code or revise your scope docs to see how the system overview and threats change over time.

Edit a threat model

To modify your threat model configuration:

  1. On the threat model detail page, choose Edit.

  2. Update the title, sources, scope docs, or AWS resources as needed.

  3. Choose Save changes.

Note

Editing a threat model does not affect previously completed runs. Those preserve the configuration snapshot used at the time they ran.

Delete a threat model

To delete a threat model and all its associated runs and threats:

  1. On the threat model detail page, open the actions menu and choose Delete.

  2. Confirm the deletion.

Important

If a run is currently in progress, you must stop it before deleting the threat model.

Next steps

After running a threat model:

  • Review the system overview and threats (see Review threats from a threat model)

  • Re-run the threat model after making changes to verify threats are addressed

  • Adjust your sources and scope docs as your application evolves