GRC connector for AWS Secrets Manager: rotation, customer-managed KMS, resource policy, and access-pattern checks → v1 finding contract. Hybrid shape supports opt-in secret retrieval to stdout or 0600-permission files.

version
0.1.0
GitHub stars
436

Install

/plugin install aws-secrets-inspector@grc-engineering-suite

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.

Contents

Discovered from source

Skills 1

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 IDCheckSource of truthSeverity if failing
CRY-09Rotation enableddescribe-secret → RotationEnabled, RotationRuleshigh
CRY-09Customer-managed KMS keydescribe-secret → KmsKeyId (must not be alias/aws/secretsmanager)high
IAC-21Resource policy excludes public accessget-resource-policy → Principal:"*" granting secretsmanager:GetSecretValue (or * / secretsmanager:*)critical
IAC-15.3Access pattern (LastAccessedDate ≤ 180d)describe-secret → LastAccessedDatemedium

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.

Commands 4

/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

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

SCFCheckSeverity if failingSource of truth
CRY-09Rotation enabledhighdescribe-secret → RotationEnabled, RotationRules
CRY-09Customer-managed KMS keyhighdescribe-secret → KmsKeyId (must not be alias/aws/secretsmanager)
IAC-21Resource policy excludes public accesscriticalget-resource-policy → policy statements with Principal: "*" granting secretsmanager:GetSecretValue (or secretsmanager:* / *)
IAC-15.3Access pattern (LastAccessedDate ≤ 180d)mediumdescribe-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; usage error in retrieval mode
  • 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 in this account/region

Permissions

Minimum IAM policy for inspector mode (read-only):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:ListSecrets",
        "secretsmanager:DescribeSecret",
        "secretsmanager:GetResourcePolicy"
      ],
      "Resource": "*"
    }
  ]
}

For retrieve mode, additionally: secretsmanager:GetSecretValue, kms:Decrypt.

The AWS-managed ReadOnlyAccess policy is a superset that also works.

Examples

# 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>:

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

/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

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:

{"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:

{"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)
  • 2 access denied by IAM, KMS key policy, or the secret's resource policy
  • 3 rate-limited
  • 5 config missing — run setup
  • 6 secret not found in this account/region

Permissions

{
  "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

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

/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 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:

    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:

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

/aws-secrets-inspector:status

Non-destructive health check. Shows whether the connector is configured, whether credentials still work, whether secretsmanager:ListSecrets resolves, whether the secrets directory is at mode 0700, and when the connector last produced findings.

How to run

bash plugins/connectors/aws-secrets-inspector/scripts/status.sh

Output

aws-secrets-inspector
  aws:             /opt/homebrew/bin/aws 2.15.1
  account:         123456789012
  caller:          arn:aws:iam::123456789012:role/SecurityAudit
  default region:  us-east-1
  profile:         audit
  config:          ~/.config/claude-grc/connectors/aws-secrets-inspector.yaml
  secrets dir:     ~/.config/claude-grc/secrets (mode 700)
  list-secrets:    ok (sample 1 secret(s) visible)
  status:          ready
  last run:        3h ago (run_id 20260413-a1b2c3d4)
  cached:          12 resources, 48 evaluations

Status values

  • ready — all systems go; credentials resolve, list-secrets resolves, cache is fresh (< 7 days)
  • not-configured — setup not run
  • credentials-expired — STS call fails; refresh SSO or rotate keys
  • stale — last run > 7 days
  • no-cache — configured but no runs yet
  • aws-not-installed — the aws CLI is missing

What the list-secrets line means

/aws-secrets-inspector:status runs aws secretsmanager list-secrets --max-results 1 to confirm the IAM action resolves. If it returns denied, the line says so and notes that retrieve mode may still work if the role has secretsmanager:GetSecretValue but lacks ListSecrets — a common least-privilege split. The connector does NOT fail on this line; it surfaces the gap for the operator to act on.

The secrets directory mode is reported from stat output. If the mode is anything other than 700 (or 0700 octal), the operator should run /aws-secrets-inspector:setup again to restore it.

Sponsors

Details

Marketplace
GRCEngClub/claude-grc-engineering
Source
plugins/connectors/aws-secrets-inspector
Category
Community

More from GRCEngClub/claude-grc-engineering

All 70