# AWS Security Agent Diff Scanning for Pull Requests: Fast Security Reviews on Changed Code > Accelerate security reviews with AWS Security Agent diff scanning for pull requests. Inspect only changed code for faster, efficient security checks on your PRs. - Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) - Tags: how-to-guide - Published: 2026-07-01 --- **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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/config.json): Stores the agent-space ID and AWS region - [`scans.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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. ```bash # 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--` ## 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: ```bash git diff ..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 ```bash 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: ```bash 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-.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md) - Local workspace state tracks scan history in [`.security-agent/scans.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/scans.json) and configuration in [`.security-agent/config.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.security-agent/config.json) - The skill packages code into a ZIP (2 GB limit) and uploads to `s3://security-agent-scans--/` - Polls run every 2 minutes with final results written to `.security-agent/findings-.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-security-agent/SKILL.md). The S3 bucket follows the naming convention `security-agent-scans--` 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-.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.