threat-modeling-with-aws-security-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Security Agent — Threat Model Review

Analyze spec documents (

requirements.md

design.md

) against the source code to identify security-posture changes using STRIDE methodology. No prior scan needed.

针对源代码分析规格文档（

requirements.md

、

design.md

），使用STRIDE方法论识别安全态势变化。无需预先扫描。

Local state

本地状态

Read

.security-agent/config.json

for

agent_space_id

and

region

. If missing, run the

setup-security-agent

workflow inline first.

读取

.security-agent/config.json

获取

agent_space_id

和

region

。如果缺失，请先内联运行

setup-security-agent

工作流。

Resolving the values you need

获取所需值

Placeholder	How to resolve
`<id>` (agent space)	`config.agent_space_id`
`<region>`	`config.region` (default `us-east-1` )
`<account>`	`aws sts get-caller-identity --query Account --output text`
`<role-arn>`	`arn:aws:iam::<account>:role/SecurityAgentScanRole`
`<bucket>`	`security-agent-scans-<account>-<region>`

占位符	获取方式
`<id>` （agent空间）	`config.agent_space_id`
`<region>`	`config.region` （默认值 `us-east-1` ）
`<account>`	`aws sts get-caller-identity --query Account --output text`
`<role-arn>`	`arn:aws:iam::<account>:role/SecurityAgentScanRole`
`<bucket>`	`security-agent-scans-<account>-<region>`

Workflow

工作流程

Pre-checks. Read config, verify agent space, resolve values.
Collect spec files. Identify the
```
requirements.md
```
and/or
```
design.md
```
the user is working on. Use absolute paths. Ask if unclear which files to review.

Zip the workspace (same exclusions as code scan):

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"

Upload source zip:

bash

SCAN_ID="tm-$(date +%s)-$(openssl rand -hex 3)"
WORKSPACE_ID=$(printf '%s' "$(pwd)" | md5sum | cut -c1-12)
aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/${WORKSPACE_ID}/source.zip

Upload spec files:

bash

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:

bash

aws securityagent create-threat-model --agent-space-id <id> --title <title> \
  --service-role <role-arn> \
  --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"}]'

Capture

threatModelId

Start threat model job:

bash

aws securityagent start-threat-model-job --agent-space-id <id> --threat-model-id <tm-id>

Capture

threatJobId

Persist to
```
scans.json
```
with
```
scan_type: "THREAT_MODEL"
```
.
Tell user: "Threat model review started. Runtime varies with workspace size. I'll check every 2 minutes — say 'stop polling' to opt out."

Poll every 2 minutes:

bash

aws securityagent batch-get-threat-model-jobs --agent-space-id <id> --threat-model-job-ids <tj-id>

Only respond when status changes.

On COMPLETED → fetch threats:

bash

aws securityagent list-threats --agent-space-id <id> --threat-job-id <tj-id>

nextToken

, paginate with

--next-token

预检查。读取配置，验证agent空间，解析所需值。
收集规格文件。确定用户正在处理的
```
requirements.md
```
和/或
```
design.md
```
。使用绝对路径。若不清楚要评审哪些文件，请询问用户。

压缩工作区（排除规则与代码扫描相同）：

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"

上传源代码压缩包：

bash

SCAN_ID="tm-$(date +%s)-$(openssl rand -hex 3)"
WORKSPACE_ID=$(printf '%s' "$(pwd)" | md5sum | cut -c1-12)
aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/${WORKSPACE_ID}/source.zip

上传规格文件：

bash

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

创建威胁模型：

bash

aws securityagent create-threat-model --agent-space-id <id> --title <title> \
  --service-role <role-arn> \
  --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"}]'

记录

threatModelId

。

启动威胁模型任务：

bash

aws securityagent start-threat-model-job --agent-space-id <id> --threat-model-id <tm-id>

记录

threatJobId

。

将扫描信息以
```
scan_type: "THREAT_MODEL"
```
保存到
```
scans.json
```
。
告知用户：“威胁模型评审已启动。运行时间因工作区大小而异。我将每2分钟检查一次 — 输入‘停止轮询’即可退出。”

轮询：每2分钟执行一次：

bash

aws securityagent batch-get-threat-model-jobs --agent-space-id <id> --threat-model-job-ids <tj-id>

仅在状态变化时回复。

完成后 → 获取威胁信息：

bash

aws securityagent list-threats --agent-space-id <id> --threat-job-id <tj-id>

如果存在

nextToken

，使用

--next-token

进行分页查询。

Findings presentation

发现结果展示

Each threat includes:

statement

severity

stride

category,

threatImpact

recommendation

impactedAssets

🟣 CRITICAL: {statement}
   STRIDE: {stride}
   Impact: {threatImpact}
   Assets: {impactedAssets}
   Recommendation: {recommendation}

🔴 HIGH: {statement}
   ...

Write full report to

.security-agent/findings-{scan_id}.md

. Call out any threat that represents a regression from the prior design.

每个威胁包含：

statement

（描述）、

severity

（严重程度）、

stride

（分类）、

threatImpact

（威胁影响）、

recommendation

（建议）、

impactedAssets

（受影响资产）。

🟣 CRITICAL: {statement}
   STRIDE: {stride}
   Impact: {threatImpact}
   Assets: {impactedAssets}
   Recommendation: {recommendation}

🔴 HIGH: {statement}
   ...

将完整报告写入

.security-agent/findings-{scan_id}.md

。特别指出任何代表与先前设计相比出现安全倒退的威胁。

Rules

规则

Threat model reviews are standalone — no prior scan needed
Poll every 2 minutes, not faster
At least one spec file is required
Use absolute paths for workspace and spec files
Title:
```
threat-model-<feature-name>
```
(no spaces)

威胁模型评审可独立进行 — 无需预先扫描
每2分钟轮询一次，不可更频繁
至少需要一个规格文件
工作区和规格文件需使用绝对路径
标题格式：
```
threat-model-<feature-name>
```
（无空格）