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

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, this directory contains:

• 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 – 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, implements a complete scan workflow that handles the heavy lifting of vulnerability assessment.

Pre-scan checks verify that 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.

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:

#!/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:

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.
• 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 implementation. It checks for existing resources using the agent-space ID stored in .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 demonstrates the platform-agnostic approach.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}