# How to Perform Threat Modeling with AWS Security Agent: A Complete CLI Guide

> Perform threat modeling with AWS Security Agent CLI Analyze your code against security requirements Use STRIDE to find vulnerabilities Automate your security process

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-26

---

**Use the AWS Security Agent CLI to evaluate design and requirements documents against your source code by creating a threat model job, uploading specs to S3, and polling for STRIDE-based findings.**

AWS Security Agent provides a built-in **Threat Model Review** capability that integrates directly into the `aws/agent-toolkit-for-aws` repository. This feature allows you to analyze [`requirements.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/requirements.md) and [`design.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/design.md) files against your actual source code without requiring a prior code scan, producing a declarative security assessment based on STRIDE categories.

## Prerequisites: Workspace Setup

Before running your first threat model, you must initialize a **workspace-local state directory** at `.security-agent/` in your project root. This directory stores a minimal [`config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/config.json) containing your `agent_space_id` and region, along with JSON logs for all scans.

According to the source code in [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md), the setup process provisions:
- An Agent Space for organizing scans
- An IAM role (`SecurityAgentScanRole`) for service access
- A deterministic S3 bucket (`security-agent-scans-<account>-<region>`)

Run the following once per workspace:

```bash

# Verify existing agent spaces

aws securityagent list-agent-spaces

# Create if missing (the setup skill automates role and bucket creation)

aws securityagent create-agent-space --name security-scans

```

## The Declarative Threat Modeling Workflow

The threat modeling process follows a deterministic nine-step pipeline defined in [`plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md). Each step uses the AWS CLI to interact with uploaded artifacts and managed services.

### Step 1: Ensure Security Agent Workspace Exists

The skill first checks for [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json). If missing, it triggers the setup workflow to establish the agent space and IAM prerequisites.

### Step 2: Collect Specification Documents

Provide absolute paths to your [`requirements.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/requirements.md) and/or [`design.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/design.md) files. These documents define the security requirements and architectural design to be evaluated by the agent.

### Step 3: Package Source Code

Use the same zip exclusion list as the code-scan skill to ensure only relevant source files are uploaded. Exclude version control, dependencies, and build artifacts:

```bash
cd <absolute-workspace-path>
zip -r /tmp/source.zip . \
  -x ".git/*" -x ".security-agent/*" -x "node_modules/*" \
  -x "__pycache__/*" -x ".venv/*" -x "venv/*" \
  -x "dist/*" -x "build/*" -x "target/*" \
  -x ".mypy_cache/*" -x ".pytest_cache/*" -x ".tox/*" \
  -x ".next/*" -x "cdk.out/*" -x ".DS_Store" -x "*.pyc"

```

### Step 4: Upload Artifacts to S3

Upload the source zip and specification files to deterministic S3 locations under the `security-scans/` prefix:

```bash

# Generate deterministic identifiers

SCAN_ID="tm-$(date +%s)-$(openssl rand -hex 3)"
WORKSPACE_ID=$(printf '%s' "$(pwd)" | md5sum | cut -c1-12)
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION="us-east-1"
BUCKET="security-agent-scans-${ACCOUNT_ID}-${REGION}"

# Upload source code

aws s3 cp /tmp/source.zip s3://${BUCKET}/security-scans/source/${WORKSPACE_ID}/source.zip

# Upload specification documents

aws s3 cp <path-to-requirements.md> s3://${BUCKET}/security-scans/threat-models/${SCAN_ID}/specs/requirements.md
aws s3 cp <path-to-design.md> s3://${BUCKET}/security-scans/threat-models/${SCAN_ID}/specs/design.md

```

### Step 5: Create the Threat Model Job

Invoke `aws securityagent create-threat-model` with the S3 locations of your source and specs. This returns a unique `threatModelId`:

```bash
THREAT_MODEL_ID=$(aws securityagent create-threat-model \
  --agent-space-id $(jq -r .agent_space_id .security-agent/config.json) \
  --title "threat-model-MyFeature" \
  --service-role arn:aws:iam::${ACCOUNT_ID}:role/SecurityAgentScanRole \
  --assets sourceCode=[{s3Location=s3://${BUCKET}/security-scans/source/${WORKSPACE_ID}/source.zip}] \
  --scope-docs "[{\"s3Location\":\"s3://${BUCKET}/security-scans/threat-models/${SCAN_ID}/specs/requirements.md\"},{\"s3Location\":\"s3://${BUCKET}/security-scans/threat-models/${SCAN_ID}/specs/design.md\"}]" \
  --query 'threatModelId' --output text)

```

### Step 6: Start the Analysis Job

Begin the evaluation using `aws securityagent start-threat-model-job`:

```bash
THREAT_JOB_ID=$(aws securityagent start-threat-model-job \
  --agent-space-id $(jq -r .agent_space_id .security-agent/config.json) \
  --threat-model-id ${THREAT_MODEL_ID} \
  --query 'threatJobId' --output text)

```

The skill persists this metadata to [`.security-agent/scans.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/scans.json) with type `THREAT_MODEL` for future reference.

### Step 7: Poll for Completion

Query the job status every two minutes using `aws securityagent batch-get-threat-model-jobs`. When the status reaches `COMPLETED`, proceed to retrieve findings:

```bash
while true; do
  STATUS=$(aws securityagent batch-get-threat-model-jobs \
    --agent-space-id $(jq -r .agent_space_id .security-agent/config.json) \
    --threat-model-job-ids ${THREAT_JOB_ID} \
    --query 'threatModelJobs[0].status' --output text)
  
  echo "Current status: $STATUS"
  [[ "$STATUS" == "COMPLETED" ]] && break
  sleep 120
done

```

### Step 8: Retrieve STRIDE-Based Findings

Extract the results using `aws securityagent list-threats` and convert to markdown:

```bash
aws securityagent list-threats \
  --agent-space-id $(jq -r .agent_space_id .security-agent/config.json) \
  --threat-job-id ${THREAT_JOB_ID} \
  --output json > .security-agent/findings-${SCAN_ID}.json

```

Each threat finding includes a statement, severity level, **STRIDE** category (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege), impact assessment, affected assets, and specific remediation recommendations. The skill automatically writes the formatted report to `.security-agent/findings-<scan-id>.md`.

## Key Configuration and State Files

The threat modeling workflow relies on several deterministic file locations:

| File | Purpose |
|------|---------|
| [`plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md) | Complete workflow definition and CLI commands |
| [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md) | Agent space, IAM role, and S3 bucket provisioning |
| [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json) | Stores `agent_space_id` and region for all CLI calls |
| [`.security-agent/scans.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/scans.json) | Persistent log of all threat model runs (type `THREAT_MODEL`) |
| `.security-agent/findings-<scan_id>.md` | Human-readable STRIDE threat report |

## Summary

Performing **threat modeling with AWS Security Agent** follows a fully declarative, CLI-driven workflow that requires no manual secret management:

- Initialize the workspace via the setup skill to create deterministic IAM roles and S3 buckets
- Upload [`requirements.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/requirements.md) and [`design.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/design.md) specs alongside your source code to namespaced S3 prefixes
- Create and start threat model jobs using `aws securityagent create-threat-model` and `start-threat-model-job`
- Poll for completion every two minutes, then retrieve STRIDE-categorized findings via `list-threats`
- Review the auto-generated markdown report at `.security-agent/findings-<scan_id>.md`

This approach integrates directly into CI/CD pipelines while maintaining security through AWS-managed credentials and deterministic resource naming based on account IDs.

## Frequently Asked Questions

### Do I need to run a code scan before performing threat modeling?

No. According to the source code in [`plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md), the threat model review runs independently and does not require a previous code scan. It evaluates your uploaded specifications and source code in a single workflow.

### What file formats are supported for specification documents?

The skill specifically looks for [`requirements.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/requirements.md) and [`design.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/design.md) files. You must provide the absolute paths to these Markdown documents when prompted. The agent uses these to understand your security requirements and architectural design before analyzing threats.

### How does the skill handle authentication and secrets?

The workflow relies on the IAM role created during the setup phase (`SecurityAgentScanRole`) and deterministic S3 bucket names based on your account ID and region. As implemented in [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md), downstream skills never store passwords or secrets locally; all authentication flows through the configured AWS CLI credentials and the service role.

### What information does the final threat report contain?

The markdown report generated at `.security-agent/findings-<scan_id>.md` includes each identified threat's statement, severity level, STRIDE category, business impact, list of affected assets, and specific remediation recommendations. This structured output allows teams to prioritize fixes based on established threat classification frameworks.