# How to Set Up AWS Security Agent for Vulnerability Scanning in CI/CD Pipelines

> Set up AWS Security Agent for vulnerability scanning in CI/CD. Provision IAM roles and S3 buckets, then scan your repository with the agent toolkit for automated security checks.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-26

---

**To set up AWS Security Agent for vulnerability scanning in CI/CD, initialize your workspace with the `setup-security-agent` skill to provision the required IAM role and S3 bucket, then execute the `scanning-with-aws-security-agent` skill to zip your repository, upload it to AWS, and retrieve findings after the approximately 45-minute scan completes.**

The `aws/agent-toolkit-for-aws` repository provides DevSecOps skills that automate vulnerability scanning by orchestrating AWS Security Agent jobs directly within your CI/CD pipelines. By leveraging these agent-toolkit skills as documented in the source code, you can integrate automated security reviews into your build process without manual AWS console configuration.

## Architecture and Resource Provisioning

The **AWS Security Agent** integration relies on a workspace-local state directory and dynamically provisioned AWS resources that persist across pipeline runs.

### Workspace-Local State Management

All Security Agent skills share a hidden folder `.security-agent/` in your repository workspace. According to the `setup-security-agent` skill implementation in [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md), this directory contains:

- **[`config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/config.json)** – Stores the **agent-space ID** and **AWS region**; the IAM role ARN and S3 bucket name are derived from your AWS account at runtime.
- **[`scans.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/scans.json)** – Maintains a rolling record of the last 50 scan jobs, including job IDs, status, and timestamps.
- **`.gitignore`** – Automatically generated with a wildcard `*` to ensure scan artifacts never enter version control.

This local state allows the skill to perform idempotent setup checks on every pipeline run without creating duplicate resources.

### AWS Resources Created by the Setup Skill

When you invoke the setup skill, it provisions three core resources if they do not already exist:

1. **Agent Space** – A logical namespace for Security Agent jobs, created via `aws securityagent create-agent-space`.
2. **IAM Service Role** – `SecurityAgentScanRole` with ARN pattern `arn:aws:iam::<account>:role/SecurityAgentScanRole`. The trust policy allows `securityagent.amazonaws.com`, and the permissions policy grants S3 read/write and CloudWatch Logs access.
3. **S3 Bucket** – Named `security-agent-scans-<account>-<region>` for uploading source archives and receiving scan results.

## Understanding the Scan Workflow

The `scanning-with-aws-security-agent` skill, documented in [`plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md), implements a complete scan workflow that handles the heavy lifting of vulnerability assessment.

**Pre-scan checks** verify that [`config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/config.json) exists and that the agent space is still active. If either is missing, the skill automatically invokes the setup workflow inline before proceeding.

**Source packaging** respects your existing `.gitignore` patterns and excludes large build artifacts (such as `node_modules/`, `target/`, `dist/`, and `build/` directories) before creating a zip archive.

**Job orchestration** uploads the archive to the provisioned S3 bucket, creates or reuses a **CodeReview** object, and starts a scan job via `aws securityagent start-code-review-job`. The skill polls the job status every 5 minutes until completion. Once finished, it fetches the findings and writes a human-readable Markdown report to `.security-agent/findings-<scan_id>.md`.

## CI/CD Pipeline Implementations

You can invoke these skills from any CI runner that has AWS credentials configured (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN`).

### GitHub Actions Workflow

This example workflow checks out your code, installs the AWS CLI, initializes the Security Agent workspace, runs the full scan, and archives the findings as a build artifact.

```yaml
name: Security Scan
on:
  push:
    branches: [main, feature/*]
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    env:
      AWS_DEFAULT_REGION: us-east-1
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install AWS CLI v2
        run: |
          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
          unzip awscliv2.zip
          sudo ./aws/install

      - name: Set up Security Agent (workspace init)
        run: |
          ./agent-toolkit plugins/aws-agents-for-devsecops/commands/setup-security-agent.md

      - name: Run full code scan
        id: scan
        run: |
          ./agent-toolkit plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md

      - name: Upload findings as artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: security-findings
          path: .security-agent/findings-*.md

```

The `setup-security-agent` step guarantees the IAM role, S3 bucket, and agent space exist, while the scanning step handles job submission and polling automatically.

### Bash Script for Any CI Platform

For GitLab CI, Azure Pipelines, or other runners, use this portable bash script:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Verify AWS credentials are present

aws sts get-caller-identity >/dev/null

# Provision or reuse agent space, role, and bucket

./agent-toolkit plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md

# Run the full scan

./agent-toolkit plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md

# Publish findings to console (or pipe to PR commenter)

find .security-agent -name "findings-*.md" -print0 | while IFS= read -r -d '' f; do
  echo "=== Findings in $f ==="
  cat "$f"
done

```

This script mirrors the exact logic defined in the skill files and works in any Linux-based CI environment.

### Custom Python Integration

For custom CI steps using the AWS SDK for Python, you can replicate the skill workflow manually:

```python
import json, subprocess, os, pathlib, hashlib, boto3

def sh(cmd):
    return subprocess.check_output(cmd, shell=True, text=True).strip()

# Ensure config exists (runs same logic as the skill)

if not pathlib.Path('.security-agent/config.json').exists():
    sh('agent-toolkit plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md')

# Load workspace configuration

with open('.security-agent/config.json') as f:
    cfg = json.load(f)

account = boto3.client('sts').get_caller_identity()['Account']
region = cfg.get('region', 'us-east-1')
bucket = f'security-agent-scans-{account}-{region}'
agent_space = cfg['agent_space_id']

# Zip source with same excludes as the skill

zip_path = '/tmp/source.zip'
sh(f'zip -r {zip_path} . -x ".git/*" ".security-agent/*" "node_modules/*" "__pycache__/*" "venv/*" "dist/*" "build/*" "target/*"')

if os.path.getsize(zip_path) > 2 * 1024**3:
    raise RuntimeError('Source zip exceeds 2 GB limit')

# Upload to S3

s3 = boto3.client('s3')
workspace_id = hashlib.md5(os.getcwd().encode()).hexdigest()[:12]
s3.upload_file(zip_path, bucket, f'security-scans/source/{workspace_id}/source.zip')

# Create CodeReview and start scan job via boto3 (follow the full workflow in the SKILL.md)

```

This approach allows you to embed Security Agent scans directly into existing Python-based build scripts or custom automation tools.

## Summary

- **Initialize once**: The `setup-security-agent` skill creates the `.security-agent/` directory, IAM role, and S3 bucket, storing configuration in [`config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/config.json).
- **Scan repeatedly**: The `scanning-with-aws-security-agent` skill zips your code (excluding build artifacts), uploads it to `security-agent-scans-<account>-<region>`, and polls the AWS Security Agent service every 5 minutes.
- **Retrieve results**: Findings are written to `.security-agent/findings-<scan_id>.md` and can be archived as build artifacts or posted to pull requests.
- **Cross-platform**: The idempotent setup and single-command scan work across GitHub Actions, GitLab CI, Azure Pipelines, or custom runners using the AWS CLI or SDK.

## Frequently Asked Questions

### Is the AWS Security Agent setup process safe to run on every CI/CD pipeline execution?

Yes. The `setup-security-agent` skill is fully idempotent according to the [`plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md) implementation. It checks for existing resources using the agent-space ID stored in [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json) and skips provisioning if the IAM role and S3 bucket already exist, making it safe to include in every pipeline run without creating duplicate infrastructure.

### What specific AWS permissions are required for the Security Agent to function?

The setup skill automatically provisions an IAM role named `SecurityAgentScanRole` with a trust policy allowing `securityagent.amazonaws.com` to assume it. The attached permissions policy grants specific S3 read/write access to the `security-agent-scans-<account>-<region>` bucket and CloudWatch Logs permissions for scan logging. Your CI runner only needs temporary credentials with permissions to create these resources (or assume the role if using IAM roles for service accounts).

### How long do vulnerability scans take and where are the results stored?

Scan jobs typically run for approximately 45 minutes in the AWS-managed Security Agent service. The skill polls the job status every 5 minutes using `aws securityagent start-code-review-job` APIs. Upon completion, findings are written to `.security-agent/findings-<scan_id>.md` in your workspace, which you can archive as pipeline artifacts or parse to post comments on pull requests.

### Can I integrate AWS Security Agent scanning with CI platforms other than GitHub Actions?

Absolutely. Because the skills are implemented as command-line scripts that invoke standard AWS CLI commands (`aws securityagent`), they function identically in GitLab CI, Azure DevOps, Jenkins, or any other CI platform that provides a Linux runner with AWS credentials. The bash example provided in [`plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/scanning-with-aws-security-agent/SKILL.md) demonstrates the platform-agnostic approach.