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

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 and 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 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, 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:

# 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. 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. 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 and/or 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:

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:

# 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:

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:

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 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:

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:

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	Complete workflow definition and CLI commands
plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md	Agent space, IAM role, and S3 bucket provisioning
.security-agent/config.json	Stores agent_space_id and region for all CLI calls
.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 and 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, 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 and 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}