AWS Security Agent — Code Scans

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.

Action mapping

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`

Rules for proactive suggestions

Always ask before running — never auto-trigger scans
Single-line suggestions, not multi-paragraph pitches
If the user declines, do not bring it up again in the same session

Local state

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.

Resolving the values you need

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.

Pre-scan checks

Read
config.json
. If missing → run the
```
setup-security-agent
```
workflow inline first, then continue.

Verify agent space still exists:

bash

aws securityagent batch-get-agent-spaces --agent-space-ids <id>

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:

bash

WORKSPACE_ID=$(printf '%s' "$(pwd)" | md5sum | cut -c1-12)

Workflow: Full Scan (~45 min)

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.

bash

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 "Thumbs.db" \
  -x "*.pyc" -x "*.pyo"
ZIP_BYTES=$(stat -f%z /tmp/source.zip 2>/dev/null || stat -c%s /tmp/source.zip)
if [ "$ZIP_BYTES" -gt 2147483648 ]; then echo "Zip too large (>2GB)"; exit 1; fi

Upload to the per-workspace stable key (overwrites any prior upload):

bash

aws s3 cp /tmp/source.zip s3://<bucket>/security-scans/source/<WORKSPACE_ID>/source.zip

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:

bash

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}]

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:

bash

aws securityagent start-code-review-job --agent-space-id <id> --code-review-id <cr-id>

If the response is
ResourceNotFoundException
: the CodeReview was deleted externally. Recreate it (step 4) and retry.

Capture

codeReviewJobId

. Generate a local

scan_id

scan-<8-hex>

. Append to

scans.json

json

{
  "scan_id": "scan-...",
  "code_review_id": "cr-...",
  "job_id": "cj-...",
  "agent_space_id": "as-...",
  "scan_type": "FULL",
  "title": "pre-cr-main",
  "path": "/abs/path",
  "started_at": "2026-06-01T20:00:00Z",
  "status": "IN_PROGRESS"
}

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.

Polling Loop

After starting a scan:

```
sleep 300
```
(5 minutes). Do not poll faster than this.

Call status:

bash

aws securityagent batch-get-code-review-jobs --agent-space-id <id> --code-review-job-ids <job_id>

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
```
.

Workflow: Status check (ad-hoc)

User says "scan status" / "how's the scan":

If user names a
```
scan_id
```
, use it. Otherwise use the most recent entry in
```
scans.json
```
.
Call
```
batch-get-code-review-jobs
```
once.
Update
```
scans.json
```
status field.
Report: status + elapsed time + current step (if any).

Workflow: Findings

After a scan completes (or on user request):

1. Fetch findings (paginate)

bash

aws securityagent list-findings --agent-space-id <id> --code-review-job-id <job-id>

nextToken

is returned, call again with

--next-token <token>

until exhausted.

2. Enrich with full details

bash

aws securityagent batch-get-findings --agent-space-id <id> --finding-ids <id1> <id2> ...

3. Filter (optional)

If the user asked for a minimum severity (e.g., "high and above"), filter to that level:

Severity order: CRITICAL > HIGH > MEDIUM > LOW > INFORMATIONAL.

4. Concise summary in chat

Group by severity. File path + line for each:

🟣 CRITICAL: {name}
   File: {filePath}:{lineStart}
   {description}

🔴 HIGH: {name}
   File: {filePath}:{lineStart}
   {description}

🟡 MEDIUM: {name}
   File: {filePath}:{lineStart}
   {description}

🟢 LOW: {name}
   File: {filePath}:{lineStart}
   {description}

5. Detailed report file

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).

markdown

# Security Scan Report — {scan_id}

**Scan type**: FULL
**Title**: {title}
**Started**: {started_at}
**Total findings**: {count}

## Summary
| Severity | Count |
|----------|-------|
| CRITICAL | N |
| HIGH | N |
| MEDIUM | N |
| LOW | N |

## Findings

### 🟣 CRITICAL: {name}
- **ID**: {findingId}
- **Risk type**: {riskType}
- **Confidence**: {confidence}
- **Status**: {status}
- **Location**: `{filePath}:{lineStart}-{lineEnd}`

**Description**: {description}

**Remediation**:
{remediationCode or remediation guidance from description}

(repeat for every finding)

Tell user: "Full details written to

.security-agent/findings-{scan_id}.md

6. Follow-ups

Ask:

"Would you like to focus on the critical/high findings first?"
"Should I explain any of these in more detail?"
"Want me to fix these issues?"

For fixes: read the finding's description and code location, then synthesize and apply the fix via the Edit tool.

Workflow: Stop a scan

User says "stop the scan":

bash

aws securityagent stop-code-review-job --agent-space-id <id> --code-review-job-id <job_id>

Update

scans.json

status to

STOPPED

Workflow: List recent scans

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

Rules

Always run pre-scan checks (config exists + agent space verified) before any scan
Scan APIs return immediately — poll status every 5 minutes
Use the most recent scan in
```
scans.json
```
if the user doesn't name one
Title must not contain spaces — use hyphens. Default to git branch name.
Don't dump raw JSON — format with severity icons + file locations

ResourceNotFoundException

from

start-code-review-job

, recreate the CodeReview and retry once

Troubleshooting

"Not configured" /
config.json
missing → run
```
setup-security-agent
```
skill first
AccessDenied
on
s3 cp
→ bucket not registered on agent space, or trust policy wrong. Re-run setup.
ResourceNotFoundException
on agent space → it was deleted. Re-run setup.
Scan stuck in PREFLIGHT for >10 min → backend issue, not client. Show
```
batch-get-code-review-jobs
```
output and tell user to escalate.
Code too large (zip > 2 GB) → run on a subdirectory instead.

scanning-with-aws-security-agent

NPX Install

Tags

SKILL.md Content

AWS Security Agent — Code Scans

Action mapping

Rules for proactive suggestions

Local state

Resolving the values you need

Pre-scan checks

Workflow: Full Scan (~45 min)

Polling Loop

Workflow: Status check (ad-hoc)

Workflow: Findings

1. Fetch findings (paginate)

2. Enrich with full details

3. Filter (optional)

4. Concise summary in chat

5. Detailed report file

6. Follow-ups

Workflow: Stop a scan

Workflow: List recent scans

Rules

Troubleshooting