How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill diff-scanning-with-aws-security-agentBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
AWS Security Agent — Diff Scan
Scan only the code that changed since a git ref. Faster than a full scan — focuses findings on the diff. No prior full scan needed.
Local state
Read .security-agent/config.json for agent_space_id and region. If missing, run the setup-security-agent workflow inline first.
Track scans in .security-agent/scans.json.
Resolving the values you need
| Placeholder | How to resolve | ||
|---|---|---|---|
<id> (agent space) | config.agent_space_id | ||
<region> | config.region (default us-east-1) | ||
<account> | aws sts get-caller-identity --query Account --output text | ||
<role-arn> | arn:aws:iam::<account>:role/SecurityAgentScanRole | ||
<bucket> | security-agent-scans-<account>-<region> | ||
<WORKSPACE_ID> | `printf '%s' "$(pwd)" \ | md5sum \ | cut -c1-12` |
Workflow
- Pre-scan checks. Same as full scan — read config, verify agent space, resolve values, generate workspace ID.
- Ask what to scan against:
- Uncommitted changes →
BASE_REF=HEAD(default) - Branch vs main →
BASE_REF=main - Custom ref → user provides
- Generate diff (fail fast if empty):
cd <absolute-workspace-path>
if [ "$BASE_REF" = "HEAD" ]; then
git diff HEAD > /tmp/diff.patch
else
git diff "$BASE_REF..HEAD" > /tmp/diff.patch
fi
[ -s /tmp/diff.patch ] || { echo "No changes vs $BASE_REF"; exit 1; }- Zip the workspace (same exclusions as full scan, 2 GB limit):
cd <absolute-workspace-path>
zip -r /tmp/source.zip . \
-x ".git/*" -x ".security-agent/*" -x "node_modules/*" \
-x "__pycache__/*" -x ".venv/*" -x "venv/*" \
-x "dist/*" -x "build/*" -x "target/*" \
-x ".mypy_cache/*" -x ".pytest_cache/*" -x ".tox/*" \
-x ".next/*" -x "cdk.out/*" -x ".DS_Store" -x "*.pyc"- Upload both source zip and diff patch:
SCAN_ID="diff-$(date +%s)-$(openssl rand -hex 3)"
aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip --expected-bucket-owner <account>
aws s3 cp /tmp/diff.patch s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patch --expected-bucket-owner <account>- Get or create per-workspace CodeReview (same logic as full scan — lookup
config.json → code_reviews[<abs_path>], create if absent):
aws securityagent create-code-review --agent-space-id <id> --title <title> \
--service-role <role-arn> \
--assets sourceCode=[{s3Location=s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip}]- Start the diff job:
aws securityagent start-code-review-job --agent-space-id <id> --code-review-id <cr-id> \
--diff-source s3Uri=s3://<bucket>/security-scans/diffs/${SCAN_ID}/diff.patchIf ResourceNotFoundException: recreate CodeReview and retry.
- Capture
codeReviewJobId. Persist toscans.jsonwithscan_type: "DIFF"andbase_ref.
- Tell user: "Diff scan started. Takes a few minutes. I'll check every 2 minutes — say 'stop polling' to opt out."
- Poll every 2 minutes:
aws securityagent batch-get-code-review-jobs --agent-space-id <id> --code-review-job-ids <job_id>Only respond when status changes. On COMPLETED → fetch findings.
- Findings: same presentation as full scan — grouped by severity, report written to
.security-agent/findings-{scan_id}.md.
Rules
- Diff scans are standalone — no prior full scan needed
- Poll every 2 minutes, not faster
- Default to
BASE_REF=HEADif user doesn't specify - Title:
diff-<git-branch>-<timestamp>(no spaces) - If diff is empty, tell user and stop — don't start a scan



