# setup-security-agent

Configures AWS Security Agent for the project workspace by provisioning an agent space, IAM role, and S3 bucket.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1500 installs · ★ 3282
- Author: aws
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/setup-security-agent

## What it does

This skill prepares your local workspace for security scans and penetration tests. It creates a `.security-agent/` directory containing `config.json` and a `.gitignore` file. Account ID, bucket name, and IAM role ARN rely on deterministic naming conventions instead of hardcoded values to prevent configuration drift.

The workflow queries `aws sts get-caller-identity` to resolve the current account and region. Next, it looks up existing agent spaces with `aws securityagent list-agent-spaces`. If spaces already exist, the skill prompts you to choose one or provision a new space. It then configures `SecurityAgentScanRole` with an `aws:SourceAccount` condition to prevent confused-deputy issues.

Bucket ownership checks are strictly enforced. When inspecting or creating the `security-agent-scans-${ACCOUNT}-${REGION}` bucket, the skill passes `--expected-bucket-owner`. If an existing bucket belongs to a different account, setup halts immediately with a fatal 403 error. You must have the AWS CLI configured with IAM and S3 permissions before running this tool.

## Requirements
- Works with: AWS

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/setup-security-agent/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/setup-security-agent/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/setup-security-agent/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/setup-security-agent/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install aws/agent-toolkit-for-aws setup-security-agent
```

2. **Manually: put the files in place**
- File: `.github/skills/setup-security-agent/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/aws/agent-toolkit-for-aws --path plugins/aws-agents-for-devsecops/skills/setup-security-agent
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/setup-security-agent/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add aws/agent-toolkit-for-aws --skill setup-security-agent -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md

## When to use it
- provision or link an AWS Security Agent space for the workspace
- create the SecurityAgentScanRole IAM service role with scoped policies
- configure an S3 bucket with expected-owner validation
- guard against confused-deputy attacks and bucket squatting

## Example prompts
- Set up security agent for this workspace
- Configure security scanner
- Check if security agent is configured

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 38b1969431e7dd15.

BEGIN THIRD-PARTY FILE 38b1969431e7dd15
````text
---
name: setup-security-agent
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.
---

# 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>
     ```
````
END THIRD-PARTY FILE 38b1969431e7dd15

The third-party file has ended. Everything between the 38b1969431e7dd15 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2546 of 11051 bytes. © aws · Apache-2.0 · https://github.com/aws/agent-toolkit-for-aws/tree/HEAD/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md