OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add aws/agent-toolkit-for-aws --skill scanning-with-aws-security-agent
Run an AWS Security Agent scan on the workspace — uploads the source to AWS, scans it with the managed Security Agent service, and returns ranked, verified findings with code locations and remediations. Use when the user asks to scan code, find vulnerabilities, run a security scan or review, check security issues, check scan status, show findings, list recent scans, or stop a scan.
npx skills add aws/agent-toolkit-for-aws --skill scanning-with-aws-security-agent
This skill handles full repository scans. Setup (agent space, role, bucket) is handled by the setup-security-agent skill — if .security-agent/config.json is missing, the scan workflow auto-runs setup inline first.
| User intent | Workflow |
|---|---|
| Direct scan request ("scan my code", "find vulnerabilities") | Full Scan |
| Scan status check ("how's the scan", "progress") | Status workflow |
| View findings ("what did it find", "show results") | Findings workflow |
| List scans ("recent scans", "show my scans") | Read .security-agent/scans.json |
| Stop a scan | aws securityagent stop-code-review-job |
Read .security-agent/config.json for agent_space_id and region. If config.json is missing, tell the user one line — "First scan in this workspace — running setup first." — and run the setup-security-agent workflow inline (steps from that skill's SKILL.md) before continuing. First-time scans should "just work."
Track scans in .security-agent/scans.json (keep last 50 entries). The per-workspace CodeReview ID is stored in config.json → code_reviews[<abs_path>] so subsequent scans reuse the same CodeReview.
The CLI examples below use placeholders. Resolve them at the start of every scan:
| 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 (cache for the rest of the turn) |
<role-arn> | arn:aws:iam::<account>:role/SecurityAgentScanRole |
<bucket> | security-agent-scans-<account>-<region> |
<cr-id> | code_review_id from config.json → code_reviews[<abs_path>] |
<job_id> | codeReviewJobId returned by start-code-review-job |
<WORKSPACE_ID> | printf '%s' "$(pwd)" | md5sum | cut -c1-12 |
These are derived rather than stored in config so they can never drift out of sync with reality.
Read config.json. If missing → run the setup-security-agent workflow inline first, then continue.
Verify agent space still exists:
If response shows it doesn't exist, clear agent_space_id from config.json and run setup-security-agent again.
Resolve account, role ARN, and bucket name from the table above.
Generate workspace ID:
For scanning only changed code, use the diff-scanning-with-aws-security-agent skill instead. For threat modeling specs, use threat-modeling-with-aws-security-agent.
Run pre-scan checks above.
Zip the workspace. Exclude common build/cache directories. Honor .gitignore. Bail if zip > 2 GB.
Upload to the per-workspace stable key (overwrites any prior upload):
Get or create the per-workspace CodeReview. Look up config.json → code_reviews[<abs_path>].
If present, use that code_review_id.
If absent, create:
Capture codeReviewId and persist to config.json → code_reviews[<abs_path>].
Title default: pre-cr-<git-branch> (use git rev-parse --abbrev-ref HEAD). Replace any spaces with hyphens.
Start the job:
ResourceNotFoundException: the CodeReview was deleted externally. Recreate it (step 4) and retry.Capture codeReviewJobId. Generate a local scan_id like scan-<8-hex>. Append to scans.json:
Tell user: "Full scan started (scan_id: {id}). Takes ~45 minutes. I'll check every 5 minutes — say 'stop polling' to opt out."
Run the Polling Loop below with sleep 300 between checks.
After starting a scan:
sleep 300 (5 minutes). Do not poll faster than this.
Call status:
Compare status to last seen status. Only respond to the user when status CHANGES (e.g., IN_PROGRESS → COMPLETED) or on terminal state (COMPLETED, FAILED, STOPPED).
Do not report "still in progress" multiple times — that's noise.
If user says "stop polling" or "check later" → stop the loop and tell them: "Say 'scan status' or 'show findings' anytime."
On COMPLETED → run the Findings workflow.
On FAILED → fetch the job's error info (statusReason if present), tell the user, write a brief failure note to .security-agent/findings-{scan_id}.md.
User says "scan status" / "how's the scan":
scan_id, use it. Otherwise use the most recent entry in scans.json.batch-get-code-review-jobs once.scans.json status field.After a scan completes (or on user request):
If nextToken is returned, call again with --next-token <token> until exhausted.
If the user asked for a minimum severity (e.g., "high and above"), filter to that level:
Group by severity. File path + line for each:
Write to .security-agent/findings-{scan_id}.md. Include EVERY field returned (findingId, name, description, riskLevel, riskType, confidence, status, codeLocations with filePath/lineStart/lineEnd, and remediationCode if present).
Tell user: "Full details written to .security-agent/findings-{scan_id}.md"
Ask:
For fixes: read the finding's description and code location, then synthesize and apply the fix via the Edit tool.
User says "stop the scan":
Update scans.json status to STOPPED.
User asks "show my recent scans" / "list scans":
Read .security-agent/scans.json. Show in a compact table:
| scan_id | type | title | status | started |
|---|---|---|---|---|
| scan-abc | FULL | pre-cr-main | COMPLETED | 2h ago |
| scan-def | FULL | pre-cr-feature-x | FAILED | 1d ago |
scans.json if the user doesn't name oneResourceNotFoundException from start-code-review-job, recreate the CodeReview and retry onceconfig.json missing → run setup-security-agent skill firstAccessDenied on s3 cp → bucket not registered on agent space, or trust policy wrong. Re-run setup.403 / ExpectedBucketOwner mismatch on s3 cp → the derived bucket is owned by a different account (bucket-squatting). The upload is rejected by design — do not retry without the guard. Re-run setup-security-agent, which aborts on foreign-owned buckets.ResourceNotFoundException on agent space → it was deleted. Re-run setup.batch-get-code-review-jobs output and tell user to escalate.