scanning-with-aws-security-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

1. **Read `config.json`.** If missing → run the `setup-security-agent` workflow inline first, then continue.
2. **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.
3. **Resolve account, role ARN, and bucket name** from the table above.
4. **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`.

1. Run pre-scan checks above.
2. **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
   ```

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

     ```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.
5. **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.
6. Capture `codeReviewJobId`. Generate a local `scan_id` like `scan-<8-hex>`. Append to `scans.json`:

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws