AWS Security Agent Diff Scanning for Pull Requests: Fast Security Reviews on Changed Code

The AWS Security Agent diff-scan mode inspects only changed code between Git references, enabling fast security reviews that run as pre-commit or pull-request checks without requiring a full repository scan.

The aws/agent-toolkit-for-aws repository provides a lightweight diff-scanning capability that integrates AWS Security Agent into your CI/CD pipeline. This AWS Security Agent diff scanning feature analyzes only the code that changed between a base branch and your current HEAD, dramatically reducing scan time while maintaining the same depth of security findings as a full scan.

How Diff Scanning Works in AWS Security Agent

The diff-scan workflow operates through a series of automated steps defined in plugins/aws-agents-for-devsecops/skills/diff-scanning-with-aws-security-agent/SKILL.md.

Workspace State Management

All Security Agent skills share a hidden .security-agent/ directory that stores configuration and scan history. This directory contains:

• config.json: Stores the agent-space ID and AWS region
• scans.json: Maintains a log of recent scan jobs

If the configuration is missing, the diff-scan skill automatically invokes the setup workflow from plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md to provision an agent space, IAM role, and S3 bucket.

Selecting the Diff Base

The skill allows you to specify which Git reference serves as the comparison base:

• HEAD (default): Scans current unstaged changes
• main: Scans the diff between current branch and main
• Custom reference: Any valid Git ref

Configuring the Workspace for Diff Scans

Before running your first scan, ensure the workspace is initialized. The setup skill creates the necessary AWS resources and local configuration.

# Initialize the Security Agent workspace

aws-agents-for-devsecops:setup-security-agent

This command provisions:

• An agent space in the Security Agent service
• An IAM role with appropriate permissions
• An S3 bucket following the naming convention security-agent-scans-<account>-<region>

Generating and Packaging the Diff

The diff-scan workflow executes several file operations to prepare your code for analysis.

Creating the Patch File

The skill generates a patch file using standard Git commands:

git diff <base-ref>..HEAD > /tmp/diff.patch

If the resulting patch file is empty, the scan aborts immediately to avoid unnecessary processing.

Packaging the Workspace

The skill creates a ZIP archive of your working directory (excluding .git, node_modules, __pycache__, and other noise directories) with a 2 GB size limit. This archive is uploaded to the convention-based S3 bucket alongside the diff patch.

Running the Diff Scan from CLI

Invoke the diff-scan skill with specific parameters to control the scan behavior.

Basic Diff Scan Against Main

aws-agents-for-devsecops:diff-scanning-with-aws-security-agent \
  --base-ref main \
  --title "pr-123-diff-$(date +%s)" \
  --poll-interval 120

Scanning From a Custom Merge Base

For feature branches, scan only changes since the branch point:

BASE_REF=$(git merge-base main HEAD)
aws-agents-for-devsecops:diff-scanning-with-aws-security-agent \
  --base-ref "$BASE_REF" \
  --title "feature-branch-diff-$(date +%s)"

The CLI performs these actions:

1. Creates or reuses a CodeReview via the Security Agent API
2. Attaches the diff patch as an additional asset named diff.patch
3. Executes aws securityagent start-code-review-job with the diff as source
4. Polls job status every 2 minutes until completion

Understanding the Output and Findings

After the scan completes, the skill writes findings to .security-agent/findings-<scan_id>.md. The output format mirrors full-scan results, grouping issues by severity and including remediation suggestions.

The diff-scan operates as a stand-alone process—no prior full scan is required. The workflow respects IAM and bucket policies enforced by the setup skill, ensuring only authorized agents can upload source code.

Summary

• AWS Security Agent diff scanning targets only changed code between Git references, making it ideal for CI/CD gate checks
• The workflow is defined in plugins/aws-agents-for-devsecops/skills/diff-scanning-with-aws-security-agent/SKILL.md and relies on workspace configuration from plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md
• Local workspace state tracks scan history in .security-agent/scans.json and configuration in .security-agent/config.json
• The skill packages code into a ZIP (2 GB limit) and uploads to s3://security-agent-scans-<account>-<region>/
• Polls run every 2 minutes with final results written to .security-agent/findings-<scan_id>.md
• No prerequisite full scan is required; diff scans are self-contained and secure

Frequently Asked Questions

How does AWS Security Agent diff scanning differ from a full repository scan?

AWS Security Agent diff scanning inspects only the code changed between two Git references rather than the entire codebase. According to the source code in plugins/aws-agents-for-devsecops/skills/diff-scanning-with-aws-security-agent/SKILL.md, this mode generates a patch file via git diff, uploads it alongside your workspace ZIP, and runs a targeted analysis. This approach reduces data transfer and processing time while delivering the same depth of security findings as a full scan.

What AWS resources does the diff-scan skill require?

The skill requires an agent space, IAM role, and S3 bucket created by the setup-security-agent workflow. These resources are defined in plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md. The S3 bucket follows the naming convention security-agent-scans-<account>-<region> and stores both the workspace ZIP and diff patch files. If these resources are missing, the diff-scan skill automatically triggers the setup workflow before proceeding.

Can I run diff scans on unstaged changes or only committed code?

You can scan both. Set --base-ref HEAD to analyze unstaged changes, or use --base-ref main to scan committed changes between your branch and the main branch. The skill also accepts any valid Git reference, such as a merge base obtained via git merge-base main HEAD, allowing you to scan exactly the changes introduced by your feature branch.

Where are scan results stored and how long does the process take?

Results are written to .security-agent/findings-<scan_id>.md in your repository root. The skill polls the Security Agent API every 2 minutes (configurable via --poll-interval) until the job completes. While the scan itself runs in the AWS cloud, the local overhead consists only of generating the diff, packaging the workspace (with a 2 GB limit), and uploading to S3—typically adding just a few seconds to the overall CI/CD pipeline duration.

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