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.

3. Resolve account, role ARN, and bucket name from the table above.

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

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

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

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

6. 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"
   }

7. Tell user: "Full scan started (scan_id: {id}). Takes ~45 minutes. I'll check every 5 minutes — say 'stop polling' to opt out."

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

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

4. Do not report "still in progress" multiple times — that's noise.

5. If user says "stop polling" or "check later" → stop the loop and tell them: "Say 'scan status' or 'show findings' anytime."

6. On COMPLETED → run the Findings workflow.

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