Scanning With Aws Security Agent

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

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:

These are derived rather than stored in config so they can never drift out of sync with reality.

Pre-scan checks

1. Read `config.json`. If missing → run the setup-security-agent workflow inline first, then continue.
2. Verify agent space still exists:

   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.

1. Resolve account, role ARN, and bucket name from the table above.
2. Generate workspace ID:

   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.

1. Run pre-scan checks above.
2. Zip the workspace. Exclude common build/cache directories. Honor .gitignore. Bail if zip > 2 GB.

   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

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

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

1. 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:

     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.

1. Start the job:

   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.

1. Capture codeReviewJobId. Generate a local scan_id like scan-<8-hex>. Append to scans.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"
   }

1. Tell user: "Full scan started (scan_id: {id}). Takes ~45 minutes. I'll check every 5 minutes — say 'stop polling' to opt out."
2. Run the Polling Loop below with sleep 300 between checks.

Polling Loop

After starting a scan:

1. sleep 300 (5 minutes). Do not poll faster than this.
2. Call status:

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

1. 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).
2. Do not report "still in progress" multiple times — that's noise.
3. If user says "stop polling" or "check later" → stop the loop and tell them: "Say 'scan status' or 'show findings' anytime."
4. On COMPLETED → run the Findings workflow.
5. 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":

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

Workflow: Findings

After a scan completes (or on user request):

1. Fetch findings (paginate)

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

If nextToken is returned, call again with --next-token <token> until exhausted.

2. Enrich with full details

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

# Security Scan Report — {scan_id}

**Scan type**: FULL
**Title**: {title}
**Started**: {started_at}