setup-security-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:**

   ```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`):

   > **Bucket-ownership enforcement (required).** The bucket name is derived from
   > the caller's AWS account ID and region — both non-secret and publicly
   > derivable from ARNs / ECR URIs — so any third party can pre-register
   > ("squat") the predictable name in their own account. Every S3 call MUST
   > pass `--expected-bucket-owner "$ACCOUNT"` so the operation fails closed if
   > the bucket is owned by someone else. A `403 Forbidden` on a bucket that
   > exists but is foreign-owned is **fatal** — abort setup and never upload.

   - Probe (asserts ownership):

     ```bash
     BUCKET="security-agent-scans-${ACCOUNT}-${REGION}"
     NEED_CREATE=0
     if aws s3api head-bucket --bucket "$BUCKET" --expected-bucket-owner "$ACCOUNT" 2>/tmp/sa-head.err; then
       : # bucket exists and is owned by this account — safe to reuse
     elif grep -q '404' /tmp/sa-head.err; then
       NEED_CREATE=1
     elif grep -Eq '403|Forbidden' /tmp/sa-head.err; then
       echo "FATAL: bucket $BUCKET exists but is owned by another account (403). Possible bucket-squatting — aborting. Nothing was uploaded." >&2
       exit 1
     else
       cat /tmp/sa-head.err >&2; exit 1

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws