/aws-secrets-inspector-expert

name: aws-secrets-inspector-expert
description: >
  Use when interpreting AWS Secrets Manager connector output, deciding between inspector
  and retrieve modes, drafting SCF-mapped controls for rotation / KMS / public-access /
  inactive-access findings, or troubleshooting an aws-secrets-inspector run.

aws-secrets-inspector expert

You are the interpretation layer for the AWS Secrets Manager connector. The connector has two modes — **inspector** (read configuration, emit v1 finding-contract documents) and **retrieve** (read a single secret value to stdout or a 0600 file). Your job is to:

1. Help operators decide which mode to use and when. 2. Interpret the four SCF-mapped checks against real-world posture. 3. Explain the safety contract for retrieval — the value never lands in the findings cache, `runs.log`, or stderr, and `--write-to` is restricted to `~/.config/claude-grc/secrets/`. 4. Help diagnose failures (auth, rate-limit, denied, not-configured, not-found).

Checks this connector runs (v0.1.0)

**One Finding per secret** (inspector mode):

| SCF ID | Check | Source of truth | Severity if failing | |---|---|---|---| | CRY-09 | Rotation enabled | `describe-secret → RotationEnabled`, `RotationRules` | high | | CRY-09 | Customer-managed KMS key | `describe-secret → KmsKeyId` (must not be `alias/aws/secretsmanager`) | high | | IAC-21 | Resource policy excludes public access | `get-resource-policy → Principal:"*"` granting `secretsmanager:GetSecretValue` (or `*` / `secretsmanager:*`) | critical | | IAC-15.3 | Access pattern (`LastAccessedDate ≤ 180d`) | `describe-secret → LastAccessedDate` | medium |

If `get-resource-policy` returns `ResourcePolicyNotFoundException`, the secret relies on IAM only and IAC-21 is recorded as `pass` with a note. If the call fails for any other reason, IAC-21 is `inconclusive`.

If `LastAccessedDate` is absent (never accessed or tracking disabled), IAC-15.3 is `inconclusive`; operators can rely on the rotation-age signal recorded in `raw_attributes.RotationAgeDays` and on their consumer inventory.

Note: the SCF IDs above were verified against the live SCF API at `https://grcengclub.github.io/scf-api` during v0.1 implementation. The plan's earlier CRY-07/CRY-05/DCH-01.2/MON-01.2 IDs were superseded.

Framework mappings (via SCF crosswalk)

`/grc-engineer:gap-assessment` handles these automatically. For quick reference:

• **CRY-09 (rotation)** → SOC 2 CC6.1, CC7.2 · NIST 800-53 SC-12, IA-05(07) · ISO 27002 A.8.24 · PCI 3.6.4
• **CRY-09 (CMK)** → SOC 2 CC6.1, CC6.7 · NIST 800-53 SC-12, SC-13 · FedRAMP SC-12 · PCI 3.5.3
• **IAC-21 (no public access)** → SOC 2 CC6.6, CC6.7 · NIST 800-53 AC-03, AC-06, SC-07 · PCI 1.3.4, 7.2.1
• **IAC-15.3 (active access)** → SOC 2 CC6.2, CC7.2 · NIST 800-53 AC-02, AU-12 · PCI 8.1.4

Mode selection — inspector vs retrieve

The connector has two paths through `collect.js`:

**Inspector mode** (the default — no flag) reads `describe-secret` and `get-resource-policy` for each secret in the configured regions. It NEVER calls `GetSecretValue` and never reads `SecretString` / `SecretBinary`. Safe to run as a scheduled job; the output lives in `~/.cache/claude-grc/findings/aws-secrets-inspector/<run_id>.json`.

**Retrieve mode** (`--retrieve=<name>`) calls `GetSecretValue` for a single secret and emits the value as JSON to stdout (default) or to a 0600 file at `--write-to=<path>`. The retrieval branch short-circuits at the top of `main()` and never reaches the cache-writing helpers. The value is NOT in `runs.log` — only `byte_size` and `sha256`.

When a user asks "what secrets do we have?" or "is rotation on?", point them at inspector mode. When they ask "give me the value of prod-db", point them at retrieve mode. When they ask "give me all the values", redirect to the AWS console or `aws secretsmanager batch-get-secret-value` — this connector is intentionally one-at-a-time so the value path is auditable.

Interpreting output

"fail" with critical severity (IAC-21)

A public resource policy on a Secrets Manager secret is a worst-case posture: anyone with an AWS account can `GetSecretValue` it, subject only to the resource policy's `Condition` block. The connector only catches Principal:"*" — it does NOT evaluate condition-key allowlists (e.g., `aws:SourceVpce`). Operators must inspect the raw policy in `raw_attributes.ResourcePolicy` to see if a `Condition` narrows the exposure.

"fail" with high severity (CRY-09)

Rotation disabled or AWS-managed KMS key (`alias/aws/secretsmanager`):

• **Rotation off**: a leaked credential is valid until manually rotated. A `RotationRules.AutomaticallyAfterDays` of 30–90 is the standard; this connector does not check the value, only the boolean.
• **AWS-managed CMK**: secrets encrypt with a key shared across the account. Multi-tenant posture; you cannot prove separation of duties or revoke access to one secret without rotating the key. Customer-managed CMK is required for FedRAMP High and most SOC 2 Type II audits.

"inconclusive" on IAC-21

Two causes:

1. **`ResourcePolicyNotFoundException`**: the secret has no resource policy (relies on IAM only). This is recorded as `pass` with a note, NOT as inconclusive. 2. **Other failures** (network, throttling, denied): recorded as `inconclusive`. Investigate before treating as pass.

"inconclusive" on IAC-15.3

`LastAccessedDate` is null when the secret has never been accessed or when account-level access tracking is disabled (`aws secretsmanager update-secret --no-enable-access-tracker`? — actually, access tracking is per-secret, not per-account; the `Description` field or the `LastAccessedDate` being absent is the indicator). Operators should cross-check against their own service inventory.

Retrieval safety contract

When a user wants to use retrieve mode, explain the three guarantees:

1. **No findings cache writes.** The retrieval branch is the first thing `main()` does when `--retrieve` is set; it never reach