Threat Modeling with AWS Security Agent: A Complete DevSecOps Guide

AWS Security Agent provides a built-in "Threat Model Review" capability that evaluates design and requirements documents against your source code using a declarative, CLI-driven workflow that requires no prior code scan.

The AWS Security Agent, available in the aws/agent-toolkit-for-aws repository, enables security teams to automate STRIDE-based threat analysis by comparing architecture specifications against actual implementation. This skill creates a feedback loop that identifies security gaps early in the development lifecycle without requiring manual security expertise or pre-existing vulnerability scans.

How the Threat Model Review Skill Works

According to the source code in plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md, the threat modeling process operates through a deterministic, state-driven workflow. The skill manages all resources through a workspace-local state directory (.security-agent/) that stores configuration metadata and scan histories, eliminating the need to manage passwords or secrets manually.

The workflow relies on conventions established by the setup-security-agent skill, which provisions the underlying Agent Space, IAM role, and S3 bucket infrastructure.

Step-by-Step Workflow

1. Workspace Initialization

The skill first ensures a Security Agent workspace exists by reading .security-agent/config.json. If the configuration is missing, it invokes the setup workflow to create an Agent Space, IAM role, and the deterministic S3 bucket security-agent-scans-<account>-<region>.

2. Document Collection and Validation

The skill prompts for absolute paths to your specification files, specifically requirements.md and/or design.md. These documents define the intended architecture and business requirements that the source code must implement securely.

3. Source Code Packaging

Using the same exclusion list as the code-scan skill, the workflow packages only relevant source files. The following patterns are automatically excluded to prevent uploading build artifacts or sensitive cache data:

• Version control: .git/*
• Dependencies: node_modules/*, .venv/*, venv/*
• Build outputs: dist/*, build/*, target/*, .next/*, cdk.out/*
• Cache directories: __pycache__/*, .mypy_cache/*, .pytest_cache/*, .tox/*
• System files: .DS_Store, *.pyc
• Agent state: .security-agent/*

4. Artifact Upload to S3

The workflow uploads three artifacts to deterministic S3 locations under your account's scan bucket:

• source.zip → s3://security-agent-scans-<account>-<region>/security-scans/source/<workspace-id>/source.zip
• requirements.md → s3://security-agent-scans-<account>-<region>/security-scans/threat-models/<scan-id>/specs/requirements.md
• design.md → s3://security-agent-scans-<account>-<region>/security-scans/threat-models/<scan-id>/specs/design.md

5. Threat Model Job Creation

The skill invokes aws securityagent create-threat-model, passing the S3 locations of both the source code and specification documents. This command requires:

• The agent-space-id from .security-agent/config.json
• A service role ARN (created during setup)
• Asset definitions pointing to the source zip S3 location
• Scope documents array containing the requirements and design file locations

The command returns a unique threatModelId that identifies this specific analysis.

6. Job Execution

With aws securityagent start-threat-model-job, the skill initiates the analysis using the threatModelId created in the previous step. The service begins correlating the architecture documents against the actual codebase to identify threats across STRIDE categories (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege).

7. Metadata Persistence

Job metadata is written to .security-agent/scans.json with type THREAT_MODEL, enabling later reference and UI integration. This log tracks the scan ID, timestamp, and job status for the workspace.

8. Completion Polling and Results Retrieval

The skill polls every two minutes using aws securityagent batch-get-threat-model-jobs until the status reaches COMPLETED. Upon completion, it fetches detailed findings via aws securityagent list-threats.

9. Report Generation

Findings are formatted as a markdown report containing:

• Threat statement and severity level
• STRIDE category classification
• Business impact assessment
• Affected assets enumeration
• Specific remediation recommendations

The report is persisted to .security-agent/findings-<scan-id>.md for team review and audit trails.

Practical Implementation

Prerequisites

Execute the setup skill once per workspace to establish the required infrastructure:

# Verify or create Agent Space

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

The plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md automatically provisions the IAM role (SecurityAgentScanRole) and S3 bucket following the naming convention security-agent-scans-<account>-<region>.

Running a Complete Threat Model Review

Replace <absolute-workspace-path>, <path-to-requirements>, and <path-to-design> with your actual file system paths:

# Navigate to workspace

cd <absolute-workspace-path>

# Generate unique scan identifier

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}"

# Package source code with exclusions

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"

# Upload artifacts to S3

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

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

# Create threat model

AGENT_SPACE_ID=$(jq -r .agent_space_id .security-agent/config.json)

THREAT_MODEL_ID=$(aws securityagent create-threat-model \
  --agent-space-id ${AGENT_SPACE_ID} \
  --title "threat-model-$(basename $(pwd))" \
  --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)

# Start analysis job

THREAT_JOB_ID=$(aws securityagent start-threat-model-job \
  --agent-space-id ${AGENT_SPACE_ID} \
  --threat-model-id ${THREAT_MODEL_ID} \
  --query threatJobId --output text)

# Poll for completion (checks every 2 minutes)

while true; do
  STATUS=$(aws securityagent batch-get-threat-model-jobs \
    --agent-space-id ${AGENT_SPACE_ID} \
    --threat-model-job-ids ${THREAT_JOB_ID} \
    --query 'threatModelJobs[0].status' \
    --output text)
  
  echo "Current status: $STATUS"
  
  if [ "$STATUS" == "COMPLETED" ]; then
    break
  fi
  
  sleep 120
done

# Retrieve and save findings

aws securityagent list-threats \
  --agent-space-id ${AGENT_SPACE_ID} \
  --threat-job-id ${THREAT_JOB_ID} \
  --output json > .security-agent/findings-${SCAN_ID}.json

State Management and Output Files

The threat modeling skill generates several persistent artifacts in your workspace:

• .security-agent/config.json – Stores agent_space_id and region; read by all Security Agent skills to maintain session continuity.
• .security-agent/scans.json – append-only log tracking all threat model runs with type THREAT_MODEL, enabling historical analysis and audit trails.
• .security-agent/findings-<scan-id>.md – Human-readable markdown report containing the complete STRIDE analysis, severity ratings, and remediation guidance.

Summary

• Threat modeling with AWS Security Agent requires no pre-existing code scans and operates entirely through AWS CLI commands defined in the DevSecOps skill library.
• The workflow uploads requirements.md and design.md alongside filtered source code to a deterministic S3 bucket (security-agent-scans-<account>-<region>).
• State persistence through .security-agent/config.json and .security-agent/scans.json eliminates credential management and enables CI/CD integration.
• Results categorize threats using STRIDE methodology and include actionable remediation steps stored in markdown format.

Frequently Asked Questions

What document formats does the threat modeling skill accept?

The skill specifically looks for requirements.md and design.md files containing architecture and business logic specifications. These markdown documents should describe intended functionality, data flows, trust boundaries, and security assumptions that the AWS Security Agent validates against actual implementation.

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

No. The Threat Model Review capability operates independently and does not require prior vulnerability scans. The skill packages and uploads source code automatically during execution, making it suitable for initial architecture reviews or greenfield projects without existing security baselines.

How does the skill prevent sensitive files from being uploaded?

The implementation uses a strict exclusion list (defined in plugins/aws-agents-for-devsecops/skills/threat-modeling-with-aws-security-agent/SKILL.md) that filters out .git directories, virtual environments, dependency folders (node_modules), build artifacts, and cache files before creating the source zip archive. This ensures only application logic reaches the AWS analysis environment.

Where are threat modeling results permanently stored?

Findings persist in two locations: the raw JSON response from aws securityagent list-threats is saved to .security-agent/findings-<scan-id>.json, and the skill generates a formatted markdown report at .security-agent/findings-<scan-id>.md. Additionally, job metadata is logged in .security-agent/scans.json with type THREAT_MODEL for long-term reference and compliance auditing.

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