# Setup Security Agent

Configure AWS Security Agent for the current workspace, provision or reuse an agent...

- Repository: https://github.com/aws/agent-toolkit-for-aws (3366 stars)
- Category: Security
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -g -a claude-code -y`
Codex: `npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -g -a codex -y`
Cursor: `npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -g -a cursor -y`
Gemini CLI: `npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add aws/agent-toolkit-for-aws`

## Description

Configure AWS Security Agent for the current workspace, provision or reuse an agent space, IAM service role, and S3 bucket. Use when the user asks to "set up security agent", "configure security scanner", "is security agent configured", or on first-time use before any scan or pentest.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/aws/agent-toolkit-for-aws/blob/HEAD/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md