AWS Security Agent — Setup

Local state convention

.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

config.json

.gitignore

Derived values (convention over config)

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

1. Check existing state: read

   .security-agent/config.json

   if it exists.
2. Caller identity + region:
   bash

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

3. 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

       .
4. Service role (

   SecurityAgentScanRole

   , ARN

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

   ):
   • Probe:
     bash

     aws iam get-role --role-name SecurityAgentScanRole

   • If

     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

5. 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

6. 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>...]

7. Persist to

   .security-agent/config.json

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

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

8. Create gitignore if missing:
   bash

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

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

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.

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.