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 reaches the cache-writing helpers. `ls ~/.cache/claude-grc/findings/aws-secrets-inspector/` after a retrieve shows no new files.
2. **No value in `runs.log`.** The manifest records `byte_size` and `sha256` of the artifact, not the value. Auditors can verify *which* artifact was produced without storing the value.
3. **`--write-to` is restricted.** The path must resolve under `~/.config/claude-grc/secrets/`. The helper uses `path.relative()` to reject `../` escapes and absolute paths like `/etc/cron.d/evil`. The file is created at mode 0600 (umask 077 enforced during the write) and the parent directory at mode 0700.

If the user wants to write the value somewhere else (e.g., to inject it into a deploy step), recommend a pipe: `--retrieve=<name> | jq -r .secret_string | deploy-tool ...` — the value never touches disk.

## When a user asks what to do next

1. **If IAC-21 fails on a secret**: delete the public statement from the resource policy immediately, then audit `CloudTrail` for any `GetSecretValue` calls from outside your org before the fix. This is alertable.
2. **If CRY-09 (rotation) fails on a critical secret** (prod database, third-party API key): enable rotation. For Lambda-rotated secrets, ensure the rotation Lambda has its own IAM role and the secret's `RotationRules.AutomaticallyAfterDays` is in [30, 90].
3. **If CRY-09 (CMK) fails on a regulated workload**: provision a customer-managed KMS key, grant the Secrets Manager service principal `kms:Encrypt`/`kms:Decrypt` on the key, and update the secret via `aws secretsmanager update-secret --kms-key-id ...`. Re-run inspector to confirm.
4. **If IAC-15.3 fails (LastAccessedDate > 180d)**: this is a candidate for archival, not deletion. Verify the consumer is genuinely retired (check `aws logs` for the secret's tag set; check the app team's runbook).

## Limits of this connector (v0.1.0)

Be honest about coverage gaps:

- **Not checking**: cross-region replication, automatic rotation success (only the boolean), Lambda rotation function health, secret versioning history beyond `AWSCURRENT`, secrets that live in AWS-managed services that proxy through Secrets Manager (RDS, Redshift, etc. — those have their own rotation story).
- **Public policy detection is shallow**: only matches `Principal:"*"`. Does not evaluate `NotPrincipal`, `Condition`, or `aws:SourceVpce` allowlists. A `Condition`-narrowed public policy is still flagged critical — operators must inspect.
- **No cross-account enumeration**: Secrets Manager has no org-wide list. Operators must run per-account via the AWS CLI profile chain.
- **Retrieve mode is one-at-a-time**: by design. `batch-get-secret-value` is the AWS API for bulk, and this connector intentionally does not wrap it.

## Common pitfalls

- **Running without `--profile` in a multi-account environment**: the connector uses the default chain. If `AWS_PROFILE` is set, that wins. If neither, the SDK falls through to env vars → `~/.aws/credentials` → IRSA/SSO. Verify with `/aws-secrets-inspector:status` before a retrieve.
- **Forgetting that retrieve mode requires separate IAM**: `secretsmanager:GetSecretValue` is NOT in the inspector's read-only policy. A role that can list and describe cannot retrieve.
- **Storing the JSON file in a shared directory**: `--write-to=./prod-db` (relative) is resolved against the current working directory; the helper only accepts the path if the resolved absolute path falls under `~/.config/claude-grc/secrets/`. A relative path that lands outside that root is rejected. Absolute paths outside the root are also rejected. This is intentional; the connector refuses to write secrets to working directories or other arbitrary locations.
- **Cross-account retrieve without `kms:Decrypt`**: Secrets Manager uses a customer-managed CMK. The role must have `kms:Decrypt` on the key, or the API returns `AccessDeniedException` (not a `NotFound` — that comes from the resource policy).
- **Resource policy vs IAM**: a resource policy `Deny` overrides an IAM `Allow` for the same principal. If a retrieve returns `AccessDeniedException` despite the role having `GetSecretValue`, check the secret's resource policy first.