feat(aws-secrets-inspector): hybrid AWS Secrets Manager connector with safe retrieval mode

.claude-plugin/marketplace.json

@@ -225,6 +225,12 @@
       "description": "GRC connector for AWS: IAM, S3, CloudTrail, EBS compliance checks \u2192 v1 finding contract",
       "version": "0.1.0"
     },
+    {
+      "name": "aws-secrets-inspector",
+      "source": "./plugins/connectors/aws-secrets-inspector",
+      "description": "GRC connector for AWS Secrets Manager: rotation, customer-managed KMS, resource policy, and access-pattern checks \u2192 v1 finding contract. Hybrid shape supports opt-in secret retrieval to stdout or 0600-permission files.",
+      "version": "0.1.0"
+    },
     {
       "name": "github-inspector",
       "source": "./plugins/connectors/github-inspector",

package.json

@@ -21,6 +21,7 @@
     "scaffold-framework": "node plugins/grc-engineer/scripts/scaffold-framework.js",
     "generate-coverage": "node plugins/grc-engineer/scripts/generate-coverage.js",
     "test:wiz-inspector": "node --test tests/wiz-inspector-collect.test.js",
+    "test:aws-secrets-inspector": "node --test tests/aws-secrets-inspector-collect.test.js",
     "test:contract": "bash tests/validate-contract-fixtures.sh",
     "test:grc-diagrams": "bash tests/validate-grc-diagram-skills.sh",
     "test:plugin-manifests": "bash tests/validate-plugin-manifests.sh",

plugins/connectors/aws-secrets-inspector/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "aws-secrets-inspector",
+  "version": "0.1.0",
+  "description": "GRC connector for AWS Secrets Manager: evaluates rotation, customer-managed KMS key, resource policy (public access), and access patterns. Hybrid shape — emits v1 finding-contract documents in inspector mode and supports opt-in secret retrieval to stdout or 0600 files in retrieve mode.",
+  "author": { "name": "GRC Engineering Club Contributors" },
+  "license": "MIT",
+  "repository": "https://github.com/GRCEngClub/claude-grc-engineering",
+  "keywords": ["grc", "compliance", "aws", "secrets-manager", "scf", "soc2", "fedramp", "connector"]
+}

plugins/connectors/aws-secrets-inspector/commands/collect.md

@@ -0,0 +1,112 @@
+---
+name: AWS Secrets Inspector Collect
+description: Query AWS Secrets Manager for compliance-relevant configuration (rotation, KMS, resource policy, access patterns) and emit findings conforming to the v1 contract.
+---
+
+# /aws-secrets-inspector:collect
+
+Scans AWS Secrets Manager for compliance-relevant configuration. Emits one Finding document per secret. Inspector mode is the default path of `aws-secrets-inspector`. For value retrieval, use `/aws-secrets-inspector:retrieve` instead.
+
+## How to run
+
+```bash
+node plugins/connectors/aws-secrets-inspector/scripts/collect.js [options]
+```
+
+## Arguments
+
+- `--regions=<csv>` — regions to scan (default: the config's `default_region` or `defaults.regions`)
+- `--profile=<name>` — override the configured AWS profile
+- `--output=<fmt>` — `silent` | `summary` (default) | `json`
+- `--refresh` — ignore cache; re-query AWS (always refreshes for now)
+- `--quiet` — no stderr progress
+
+## What it evaluates
+
+One Finding per secret, with four SCF-mapped evaluations. The SCF IDs were verified against the live SCF API at `https://grcengclub.github.io/scf-api` during implementation (the implementation plan's prior guesses were superseded).
+
+| SCF | Check | Severity if failing | Source of truth |
+|---|---|---|---|
+| CRY-09 | Rotation enabled | high | `describe-secret` → `RotationEnabled`, `RotationRules` |
+| CRY-09 | Customer-managed KMS key | high | `describe-secret` → `KmsKeyId` (must not be `alias/aws/secretsmanager`) |
+| IAC-21 | Resource policy excludes public access | critical | `get-resource-policy` → policy statements with `Principal: "*"` granting `secretsmanager:GetSecretValue` (or `secretsmanager:*` / `*`) |
+| IAC-15.3 | Access pattern (LastAccessedDate ≤ 180d) | medium | `describe-secret` → `LastAccessedDate` |
+
+If a `get-resource-policy` call 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`; the operator can rely on the rotation-age signal recorded in `raw_attributes.RotationAgeDays` and on their consumer inventory.
+
+## Output
+
+- Writes `~/.cache/claude-grc/findings/aws-secrets-inspector/<run_id>.json` — array of Findings
+- Appends a run manifest to `~/.cache/claude-grc/runs.log`
+- One-line summary unless `--quiet` or `--output=json`:
+
+  ```
+  aws-secrets-inspector: 12 resources, 48 evaluations, 7 failing (1 critical, 4 high, 2 medium).
+  ```
+
+The `raw_attributes` block on each Finding carries everything needed for downstream triage without a re-query: `Name`, `ARN`, `RotationEnabled`, `RotationRules`, `LastRotatedDate`, `LastChangedDate`, `LastAccessedDate`, `KmsKeyId`, `OwningService`, `PrimaryRegion`, `Description`, `InactiveDays`, `RotationAgeDays`. `resource.tags` carries the secret's tag set.
+
+## Exit codes
+
+- `0` success
+- `2` credentials invalid or expired; or `--retrieve` not yet implemented (U4 follow-up)
+- `3` rate-limited (AWS throttling; retry later)
+- `4` partial (some regions inaccessible; report still written)
+- `5` config missing — run setup
+- `6` retrieval mode: secret not found (U4)
+
+## Permissions
+
+Minimum IAM policy for inspector mode (read-only):
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "secretsmanager:ListSecrets",
+        "secretsmanager:DescribeSecret",
+        "secretsmanager:GetResourcePolicy"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+For retrieve mode (U4), additionally: `secretsmanager:GetSecretValue`, `kms:Decrypt`.
+
+The AWS-managed `ReadOnlyAccess` policy is a superset that also works.
+
+## Examples
+
+```bash
+# Default region, all secrets
+/aws-secrets-inspector:collect
+
+# Multi-region scan
+/aws-secrets-inspector:collect --regions=us-east-1,us-west-2,eu-west-1
+
+# Alternate profile (e.g., for cross-account via the AWS CLI profile chain)
+/aws-secrets-inspector:collect --profile=audit-target
+
+# CI/CD-friendly
+node plugins/connectors/aws-secrets-inspector/scripts/collect.js --quiet --output=json
+```
+
+## Cross-account access
+
+This connector does NOT implement `sts:AssumeRole` itself. For cross-account access, configure the standard AWS CLI profile chain in `~/.aws/config` and pass `--profile=<name>`:
+
+```ini
+[profile audit-target]
+role_arn = arn:aws:iam::222233334444:role/SecurityAudit
+source_profile = default
+mfa_serial = arn:aws:iam::111122223333:mfa/you   # optional
+```
+
+The AWS SDK performs the `AssumeRole` transparently; this connector sees the resolved credentials. See `commands/setup.md` and `commands/retrieve.md` for the same pattern applied to setup and retrieval.

plugins/connectors/aws-secrets-inspector/commands/retrieve.md

@@ -0,0 +1,108 @@
+---
+name: AWS Secrets Inspector Retrieve
+description: Retrieve a single AWS Secrets Manager secret value to stdout or a 0600-permission file. Opt-in retrieval mode — never writes to the findings cache.
+---
+
+# /aws-secrets-inspector:retrieve
+
+Retrieves a single AWS Secrets Manager secret value and returns it to stdout (default) or to a 0600-permission file under `~/.config/claude-grc/secrets/`. This is the **only** path through the connector that produces a secret value; the inspector mode never reads `SecretString` or `SecretBinary`.
+
+## How to run
+
+```bash
+node plugins/connectors/aws-secrets-inspector/scripts/collect.js --retrieve=<secret-name> [options]
+```
+
+## Arguments
+
+- `--retrieve=<name>` — required; the secret's name or full ARN
+- `--version-stage=<stage>` — `AWSCURRENT` (default), `AWSPREVIOUS`, or a custom stage label
+- `--version-id=<uuid>` — alternative to `--version-stage`; explicit version UUID
+- `--write-to=<path>` — write the JSON to a 0600-permission file at `<path>` (must resolve under `~/.config/claude-grc/secrets/`); confirmation line is printed to stdout
+- `--region=<region>` — region for the `get-secret-value` call; falls back to the first of `--regions`, then `config.defaults.regions[0]`, then `config.default_region`, then `AWS_DEFAULT_REGION` / `AWS_REGION`, then `us-east-1`. Pass this when the secret lives in a region other than the one encoded in your AWS profile.
+- `--profile=<name>` — override the configured AWS profile
+- `--quiet` — no stderr progress
+
+## Output
+
+**Stdout (default).** A single line of JSON:
+
+```json
+{"name":"prod-db","arn":"arn:aws:secretsmanager:us-east-1:123456789012:secret:prod-db-AbCdEf","version_id":"a1b2c3d4-...","version_stages":["AWSCURRENT"],"created_at":"2026-04-13T15:10:00Z","secret_string":"<value>"}
+```
+
+For binary secrets, `secret_binary` is set to the base64 string returned by AWS (text-safe on stdout); `secret_string` is absent.
+
+**File (`--write-to`).** The same JSON is written to `<path>`, with the file created at mode 0600 and the parent directory at mode 0700. Stdout emits a confirmation:
+
+```
+aws-secrets-inspector:retrieve wrote 247 bytes to ~/.config/claude-grc/secrets/prod-db (sha256=...)
+```
+
+The confirmation does **not** include the secret value.
+
+## Safety contract
+
+This connector enforces three invariants for retrieval runs:
+
+1. **No findings cache writes.** The retrieval branch short-circuits at the top of `main()` and never reaches the cache-writing helpers.
+2. **No value in `runs.log`.** The retrieval manifest records `byte_size` and `sha256` of the artifact, not the value. Operators and auditors can verify *which* artifact was produced without storing the value.
+3. **`--write-to` is restricted to `~/.config/claude-grc/secrets/`.** Any path that resolves outside that root — including `../` escapes and absolute paths like `/etc/cron.d/evil` — is rejected with exit 2 and a clear error. The parent directory is created with mode 0700; the destination file is created with mode 0600 (umask 077 enforced during the write).
+
+The retrieval manifest in `runs.log` looks like:
+
+```json
+{"source":"aws-secrets-inspector","run_id":"20260620-...","mode":"retrieve","secret_name":"prod-db","version_id":"a1b2c3d4-...","version_stage":"AWSCURRENT","destination":"~/.config/claude-grc/secrets/prod-db","byte_size":247,"sha256":"...","exit_code":0}
+```
+
+## Exit codes
+
+- `0` success
+- `2` usage error (unknown flag, `--write-to` outside the permitted root)
+- `2` auth failure (credentials invalid or expired)
+- `3` rate-limited
+- `5` config missing — run setup
+- `6` secret not found in this account/region (or denied by the resource policy)
+
+## Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    { "Effect": "Allow", "Action": ["secretsmanager:GetSecretValue"], "Resource": "<secret-arn-or-*>" },
+    { "Effect": "Allow", "Action": ["kms:Decrypt"], "Resource": "<kms-key-arn>" }
+  ]
+}
+```
+
+For cross-account access, configure the standard AWS CLI profile chain in `~/.aws/config` and pass `--profile=<name>` (this connector does NOT implement `sts:AssumeRole` itself).
+
+## Examples
+
+```bash
+# Default: AWSCURRENT to stdout
+/aws-secrets-inspector:retrieve --retrieve=prod-db
+
+# Explicit region when the secret lives outside your profile's region
+/aws-secrets-inspector:retrieve --retrieve=prod-db --region=eu-west-1
+
+# Previous version, captured into a 0600 file
+/aws-secrets-inspector:retrieve --retrieve=prod-db --version-stage=AWSPREVIOUS \
+  --write-to=~/.config/claude-grc/secrets/prod-db-prev
+
+# Use in a CI step: pipe the JSON into a jq extractor
+/aws-secrets-inspector:retrieve --retrieve=prod-db --quiet | jq -r .secret_string
+
+# Cross-account via the profile chain
+/aws-secrets-inspector:retrieve --retrieve=prod-db --profile=audit-target
+```
+
+## Why this is not a `secret get` replacement
+
+This connector is a thin wrapper around `aws secretsmanager get-secret-value`. It adds two things the raw CLI does not:
+
+- **A safety wrapper** that guarantees no value lands in the findings cache, `runs.log`, or stderr.
+- **A restricted `--write-to`** that prevents the operator from accidentally writing the value to a world-readable file.
+
+Operators who prefer the raw `aws` CLI for ad-hoc work can use it directly. Operators who need a CI-friendly secret source should use `/aws-secrets-inspector:retrieve` so the audit trail is consistent.

plugins/connectors/aws-secrets-inspector/commands/setup.md

@@ -0,0 +1,101 @@
+---
+name: AWS Secrets Inspector Setup
+description: Verify the aws-secrets-inspector connector's prerequisites and write its config. Idempotent.
+---
+
+# /aws-secrets-inspector:setup
+
+Prepares the aws-secrets-inspector connector. Confirms `aws` CLI is installed and credentials resolve, writes `~/.config/claude-grc/connectors/aws-secrets-inspector.yaml`, and creates `~/.config/claude-grc/secrets/` (mode 0700) as the destination for `--write-to=` retrievals. Runs a read-only health check.
+
+## How to run
+
+```bash
+bash plugins/connectors/aws-secrets-inspector/scripts/setup.sh [--profile=<name>] [--region=<region>]
+```
+
+Exits 0 on success, 2 on missing/invalid credentials, 5 on missing `aws` binary.
+
+## Credential precedence
+
+Honors the standard AWS credential chain:
+
+1. `--profile` flag (writes it to config)
+2. `AWS_PROFILE` environment variable
+3. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env vars
+4. `~/.aws/credentials` default profile
+5. Instance metadata / IRSA / SSO
+
+The setup script runs `aws sts get-caller-identity` to verify credentials resolve *before* writing the config. If none resolve, it fails with actionable remediation.
+
+## What it does
+
+1. Check `aws` CLI is installed (`aws --version`).
+2. Resolve credentials (`aws sts get-caller-identity`).
+3. Resolve default region (from `--region`, `AWS_REGION`, config, or fall back with a warning).
+4. Write config:
+
+   ```yaml
+   version: 1
+   source: aws-secrets-inspector
+   source_version: "0.1.0"
+   account_id: "<12-digit>"
+   caller_arn: "<arn>"
+   profile: "<if set>"
+   default_region: "us-east-1"
+   defaults:
+     regions: ["us-east-1"]
+     rotation: true
+     kms: customer_managed
+   ```
+
+5. Create the cache dir `~/.cache/claude-grc/findings/aws-secrets-inspector/` and ensure `~/.cache/claude-grc/runs.log` exists.
+6. Create the secrets dir `~/.config/claude-grc/secrets/` at mode 0700 (operator-only).
+7. Warn if the caller ARN has administrative privileges (dogfooding: production scans and retrievals should use a dedicated least-privilege role).
+
+## Typical output
+
+```
+aws-secrets-inspector:setup ✓
+  aws:            /opt/homebrew/bin/aws 2.15.1
+  account:        123456789012
+  caller:         arn:aws:iam::123456789012:user/you
+  profile:        default
+  default region: us-east-1
+  config written: /Users/you/.config/claude-grc/connectors/aws-secrets-inspector.yaml
+  secrets dir:    /Users/you/.config/claude-grc/secrets (mode 700)
+
+WARNING: caller ARN appears to have administrative privileges. For production
+scans and retrieval, prefer a dedicated least-privilege role. Minimum IAM
+actions for the aws-secrets-inspector:
+  - Inspector mode: secretsmanager:ListSecrets, secretsmanager:DescribeSecret,
+                    secretsmanager:GetResourcePolicy
+  - Retrieve mode:  + secretsmanager:GetSecretValue, kms:Decrypt
+
+Next:
+  /aws-secrets-inspector:collect
+  /aws-secrets-inspector:retrieve --retrieve=<secret-name>
+```
+
+## Failure modes
+
+- **aws not installed**: exit 5. Install via `brew install awscli` or https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html.
+- **NoCredentialProviders**: exit 2. Remediation printed with the specific credential paths tried.
+- **InvalidClientTokenId**: exit 2. Credentials are present but rejected. Check `aws configure` or SSO session.
+- **Region not set**: warning; defaults to `us-east-1` and notes it in the config.
+
+## Cross-account access
+
+This connector does NOT implement `sts:AssumeRole` itself. For cross-account access, configure the standard AWS CLI profile chain in `~/.aws/config`:
+
+```ini
+[profile audit-target]
+role_arn = arn:aws:iam::222233334444:role/SecurityAudit
+source_profile = default
+mfa_serial = arn:aws:iam::111122223333:mfa/you   # optional
+```
+
+Then run `/aws-secrets-inspector:setup --profile=audit-target` and the connector will pick up the AssumeRole transparently. See `commands/retrieve.md` for the same pattern applied to retrievals.
+
+## Safe to re-run
+
+Yes. Overwrites the config; preserves cached findings and the existing secrets directory (mode 0700 is preserved).