setup-security-agent

AWS Security Agent — Setup

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.

---

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.

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.

---

Workflow

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

2. Caller identity + region:

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