setup-security-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Security Agent — Setup

AWS Security Agent — 设置

This skill handles ONE thing: making sure the workspace has a working agent space, IAM service role, and S3 bucket linked together. Scans and pentests live in separate skills and assume this is done.

该技能仅负责一件事：确保工作区拥有已关联的可用代理空间、IAM服务角色和S3存储桶。扫描和渗透测试由独立的技能处理，且默认此设置已完成。

Local state convention

本地状态约定

All Security Agent skills share workspace-local state at

.security-agent/

```
config.json
```
—
```
{ "agent_space_id": "as-...", "region": "us-east-1", "code_reviews": { "<abs_path>": "cr-..." } }
```
. Account ID, role ARN, and bucket name are derived by convention. The
```
code_reviews
```
map lets scans reuse the same CodeReview for a workspace.

scans.json

— array of

{ scan_id, code_review_id, job_id, agent_space_id, scan_type, title, started_at, status, path }

(keep last 50)

```
pentests.json
```
— same shape, for pentest jobs
```
.gitignore
```
— contents
```
*
```
so this directory stays untracked
```
findings-{scan_id}.md
```
— written by the scan skill after each scan completes

This skill's job is to populate

config.json

and create

.gitignore

所有Security Agent技能共享工作区本地状态，存储在

.security-agent/

目录下：

```
config.json
```
—
```
{ "agent_space_id": "as-...", "region": "us-east-1", "code_reviews": { "<abs_path>": "cr-..." } }
```
。账号ID、角色ARN和存储桶名称通过约定规则推导得出。
```
code_reviews
```
映射表允许扫描操作复用工作区的同一CodeReview。

scans.json

— 包含以下结构的数组：

{ scan_id, code_review_id, job_id, agent_space_id, scan_type, title, started_at, status, path }

（保留最近50条记录）

```
pentests.json
```
— 结构与
```
scans.json
```
一致，用于渗透测试任务
```
.gitignore
```
— 内容为
```
*
```
，确保该目录不被Git追踪
```
findings-{scan_id}.md
```
— 扫描技能在每次扫描完成后生成该文件

本技能的职责是填充

config.json

并创建

.gitignore

文件。

Derived values (convention over config)

推导值（约定优于配置）

Other skills compute these on each invocation rather than reading them from

config.json

Value	Convention
`ACCOUNT`	`aws sts get-caller-identity --query Account --output text`
`REGION`	`config.region` (default `us-east-1` )
`service_role_arn`	`arn:aws:iam::${ACCOUNT}:role/SecurityAgentScanRole`
`s3_bucket`	`security-agent-scans-${ACCOUNT}-${REGION}`

Why minimal config: the role name and bucket name are deterministic, so storing them adds drift risk (a user re-creating a role manually would silently use a stale path). Only

agent_space_id

is stored because users may have multiple agent spaces and we don't want to ask which one every session.

其他技能在每次调用时计算以下值，而非从

config.json

读取：

值	约定规则
`ACCOUNT`	`aws sts get-caller-identity --query Account --output text`
`REGION`	`config.region` （默认值为 `us-east-1` ）
`service_role_arn`	`arn:aws:iam::${ACCOUNT}:role/SecurityAgentScanRole`
`s3_bucket`	`security-agent-scans-${ACCOUNT}-${REGION}`

为何采用极简配置：角色名称和存储桶名称是确定性的，存储它们会增加配置漂移风险（用户手动重新创建角色后，可能会静默使用过时的路径）。仅存储

agent_space_id

是因为用户可能拥有多个代理空间，我们不希望每次会话都询问使用哪个。

Workflow

工作流程

Check existing state: read
```
.security-agent/config.json
```
if it exists.

Caller identity + region:

bash

export ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export REGION="${AWS_REGION:-us-east-1}"

Agent space:
- If
```
config.agent_space_id
```
  is set, verify with:
  bash
```
aws securityagent batch-get-agent-spaces --agent-space-ids <id>
```
  If the response shows it doesn't exist, treat as missing.
- If missing, list existing:
  bash
```
aws securityagent list-agent-spaces
```
  - If any exist → show them to the user with name + id and ask: "Would you like to reuse one of these, or should I create a new one?" Wait for the answer. Do not auto-select.
  - If user picks one, use that
    agentSpaceId
    .
  - If user wants new, or none exist:
    bash
```
aws securityagent create-agent-space --name security-scans
```
    Capture returned
    agentSpaceId
    .

Service role (

SecurityAgentScanRole

, ARN

arn:aws:iam::$ACCOUNT:role/SecurityAgentScanRole

Probe:

bash

aws iam get-role --role-name SecurityAgentScanRole

NoSuchEntity

is returned, create the role. Idempotency note:

create-role

will fail with

EntityAlreadyExists

if the role already exists. If that happens, fall through to

update-assume-role-policy

to ensure the trust policy is correct.

bash

# Trust policy — includes aws:SourceAccount confused-deputy guard
cat > /tmp/sa-trust.json <<EOF
{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"securityagent.amazonaws.com"},"Action":"sts:AssumeRole","Condition":{"StringEquals":{"aws:SourceAccount":"${ACCOUNT}"}}}]}
EOF
# Permissions policy (S3 + CloudWatch Logs)
cat > /tmp/sa-perms.json <<EOF
{"Version":"2012-10-17","Statement":[
  {"Effect":"Allow","Action":["s3:GetObject","s3:GetObjectVersion","s3:ListBucket"],"Resource":["arn:aws:s3:::security-agent-scans-${ACCOUNT}-${REGION}","arn:aws:s3:::security-agent-scans-${ACCOUNT}-${REGION}/*"]},
  {"Effect":"Allow","Action":["logs:CreateLogGroup","logs:CreateLogStream","logs:PutLogEvents"],"Resource":"arn:aws:logs:*:${ACCOUNT}:log-group:/aws/securityagent/*"}
]}
EOF

aws iam create-role --role-name SecurityAgentScanRole --assume-role-policy-document file:///tmp/sa-trust.json
# if EntityAlreadyExists:
aws iam update-assume-role-policy --role-name SecurityAgentScanRole --policy-document file:///tmp/sa-trust.json
# always (re)apply permissions:
aws iam put-role-policy --role-name SecurityAgentScanRole --policy-name SecurityAgentCodeReviewAccess --policy-document file:///tmp/sa-perms.json

S3 bucket (

security-agent-scans-$ACCOUNT-$REGION

Probe:

bash

BUCKET="security-agent-scans-${ACCOUNT}-${REGION}"
aws s3api head-bucket --bucket "$BUCKET"

If 404, create:

bash

# us-east-1: no LocationConstraint
aws s3api create-bucket --bucket "$BUCKET"
# other regions:
aws s3api create-bucket --bucket "$BUCKET" --create-bucket-configuration LocationConstraint="$REGION"

Always (re)apply public access block + 30-day lifecycle:

bash

aws s3api put-public-access-block --bucket "$BUCKET" \
  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

cat > /tmp/sa-lifecycle.json <<'EOF'
{"Rules":[{"ID":"AutoDeleteUploads","Status":"Enabled","Filter":{"Prefix":""},"Expiration":{"Days":30}}]}
EOF
aws s3api put-bucket-lifecycle-configuration --bucket "$BUCKET" --lifecycle-configuration file:///tmp/sa-lifecycle.json

Register role + bucket on the agent space (idempotent):

Read existing resources:

bash

aws securityagent batch-get-agent-spaces --agent-space-ids <id>

Look at

agentSpaces[0].awsResources.iamRoles

and

awsResources.s3Buckets

If the role ARN or the bucket name is missing from those lists, merge and update:

bash

aws securityagent update-agent-space --agent-space-id <id> --name <existing-name> \
  --aws-resources iamRoles=[<arn1>,<arn2>...],s3Buckets=[<bucket1>,<bucket2>...]

Persist to

.security-agent/config.json

(minimal — account/role/bucket are derived):

json

{
  "agent_space_id": "as-xxxxx",
  "region": "us-east-1"
}

Create gitignore if missing:

bash

mkdir -p .security-agent
echo '*' > .security-agent/.gitignore

Confirm to user: "Setup complete. You can run security scans or pentests now."

检查现有状态：若存在
```
.security-agent/config.json
```
则读取该文件。

调用者身份 + 区域：

bash

export ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export REGION="${AWS_REGION:-us-east-1}"

代理空间：
- 若已设置
```
config.agent_space_id
```
  ，通过以下命令验证：
  bash
```
aws securityagent batch-get-agent-spaces --agent-space-ids <id>
```
  若返回结果显示该ID不存在，则视为未配置。
- 若未配置，列出现有代理空间：
  bash
```
aws securityagent list-agent-spaces
```
  - 若存在代理空间 → 向用户展示名称和ID，并询问：「您希望复用其中一个，还是创建新的代理空间？」等待用户回复。请勿自动选择。
  - 若用户选择现有空间，使用对应的
    agentSpaceId
    。
  - 若用户希望创建新空间，或不存在现有空间：
    bash
```
aws securityagent create-agent-space --name security-scans
```
    捕获返回的
    agentSpaceId
    。

服务角色（

SecurityAgentScanRole

，ARN为

arn:aws:iam::$ACCOUNT:role/SecurityAgentScanRole

）：

探测角色是否存在：

bash

aws iam get-role --role-name SecurityAgentScanRole

若返回

NoSuchEntity

，则创建角色。幂等性说明：若角色已存在，

create-role

会返回

EntityAlreadyExists

错误。出现该错误时，执行

update-assume-role-policy

确保信任策略正确。

bash

# 信任策略 — 包含aws:SourceAccount confused-deputy防护
cat > /tmp/sa-trust.json <<EOF
{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"securityagent.amazonaws.com"},"Action":"sts:AssumeRole","Condition":{"StringEquals":{"aws:SourceAccount":"${ACCOUNT}"}}}]}
EOF
# 权限策略（S3 + CloudWatch Logs）
cat > /tmp/sa-perms.json <<EOF
{"Version":"2012-10-17","Statement":[
  {"Effect":"Allow","Action":["s3:GetObject","s3:GetObjectVersion","s3:ListBucket"],"Resource":["arn:aws:s3:::security-agent-scans-${ACCOUNT}-${REGION}","arn:aws:s3:::security-agent-scans-${ACCOUNT}-${REGION}/*"]},
  {"Effect":"Allow","Action":["logs:CreateLogGroup","logs:CreateLogStream","logs:PutLogEvents"],"Resource":"arn:aws:logs:*:${ACCOUNT}:log-group:/aws/securityagent/*"}
]}
EOF

aws iam create-role --role-name SecurityAgentScanRole --assume-role-policy-document file:///tmp/sa-trust.json
# 若返回EntityAlreadyExists:
aws iam update-assume-role-policy --role-name SecurityAgentScanRole --policy-document file:///tmp/sa-trust.json
# 始终（重新）应用权限:
aws iam put-role-policy --role-name SecurityAgentScanRole --policy-name SecurityAgentCodeReviewAccess --policy-document file:///tmp/sa-perms.json

S3存储桶（

security-agent-scans-$ACCOUNT-$REGION

）：

探测存储桶是否存在：

bash

BUCKET="security-agent-scans-${ACCOUNT}-${REGION}"
aws s3api head-bucket --bucket "$BUCKET"

若返回404错误，则创建存储桶：

bash

# us-east-1区域：无需LocationConstraint
aws s3api create-bucket --bucket "$BUCKET"
# 其他区域:
aws s3api create-bucket --bucket "$BUCKET" --create-bucket-configuration LocationConstraint="$REGION"

始终（重新）应用公共访问阻止规则 + 30天生命周期规则：

bash

aws s3api put-public-access-block --bucket "$BUCKET" \
  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

cat > /tmp/sa-lifecycle.json <<'EOF'
{"Rules":[{"ID":"AutoDeleteUploads","Status":"Enabled","Filter":{"Prefix":""},"Expiration":{"Days":30}}]}
EOF
aws s3api put-bucket-lifecycle-configuration --bucket "$BUCKET" --lifecycle-configuration file:///tmp/sa-lifecycle.json

在代理空间注册角色 + 存储桶（幂等操作）：

读取现有资源：

bash

aws securityagent batch-get-agent-spaces --agent-space-ids <id>

查看

agentSpaces[0].awsResources.iamRoles

和

awsResources.s3Buckets

。

若角色ARN或存储桶名称未在列表中，合并并更新：

bash

aws securityagent update-agent-space --agent-space-id <id> --name <existing-name> \
  --aws-resources iamRoles=[<arn1>,<arn2>...],s3Buckets=[<bucket1>,<bucket2>...]

持久化到

.security-agent/config.json

（极简配置——账号/角色/存储桶通过规则推导）：

json

{
  "agent_space_id": "as-xxxxx",
  "region": "us-east-1"
}

若缺失则创建gitignore：

bash

mkdir -p .security-agent
echo '*' > .security-agent/.gitignore

向用户确认：「设置完成。您现在可以运行安全扫描或渗透测试了。」

Rules

规则

Never auto-select an agent space when multiple exist — always ask the user
Never disable safety protections (the public-access-block stays on)
Trust policy must allow
```
securityagent.amazonaws.com
```
(production service principal) and include the
```
aws:SourceAccount
```
confused-deputy guard
If the user provides their own role name or bucket name (different from the conventional defaults), tell them: this plugin uses convention-based defaults (
```
SecurityAgentScanRole
```
/
```
security-agent-scans-${ACCOUNT}-${REGION}
```
). Either accept those defaults or extend the skill — the other skills derive these names rather than reading them from config.
The scan and pentest skills can call this skill inline if
```
config.json
```
is missing — first-time users don't need to run setup separately.

当存在多个代理空间时，绝不要自动选择——务必询问用户
绝不要禁用安全防护（公共访问阻止规则保持启用状态）
信任策略必须允许
```
securityagent.amazonaws.com
```
（生产服务主体）并包含
```
aws:SourceAccount
```
confused-deputy防护机制
若用户提供自定义的角色名称或存储桶名称（与约定的默认值不同），告知用户：本插件采用基于约定的默认值（
```
SecurityAgentScanRole
```
/
```
security-agent-scans-${ACCOUNT}-${REGION}
```
）。您可以接受这些默认值，或扩展本技能——其他技能会推导这些名称，而非从配置中读取。
若
```
config.json
```
缺失，扫描和渗透测试技能可以内联调用本技能——首次使用的用户无需单独运行设置流程。

Troubleshooting

故障排查

AccessDenied
calling
iam:CreateRole
→ user lacks IAM permissions. Ask them to run setup with their own role ARN, or to grant
```
iam:CreateRole
```
+
```
iam:PutRolePolicy
```
.
AccessDenied
on
s3api create-bucket
→ either the bucket name is taken globally, or the user lacks
```
s3:CreateBucket
```
. Suggest using an existing bucket they own and pass it explicitly.
Role exists but trust policy is wrong →
```
update-assume-role-policy
```
(step 4 fallback). If they don't want that role updated, ask them for a different role ARN.
Agent space exists but in a different region → tell the user; suggest using the right region or creating a new space in the current region.

调用
iam:CreateRole
时返回
AccessDenied
→ 用户缺少IAM权限。请用户使用自己的角色ARN运行设置，或授予
```
iam:CreateRole
```
+
```
iam:PutRolePolicy
```
权限。
调用
s3api create-bucket
时返回
AccessDenied
→ 要么存储桶名称已被全局占用，要么用户缺少
```
s3:CreateBucket
```
权限。建议使用用户拥有的现有存储桶并显式传入。
角色已存在但信任策略错误 → 执行
```
update-assume-role-policy
```
（步骤4的 fallback 逻辑）。若用户不希望更新该角色，请用户提供其他角色ARN。
代理空间已存在但位于其他区域 → 告知用户；建议使用正确的区域，或在当前区域创建新的代理空间。