
aws-secrets-inspector
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-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 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:
- Help operators decide which mode to use and when.
- Interpret the four SCF-mapped checks against real-world posture.
- Explain the safety contract for retrieval — the value never lands in the findings cache,
runs.log, or stderr, and--write-tois restricted to~/.config/claude-grc/secrets/. - 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.AutomaticallyAfterDaysof 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:
ResourcePolicyNotFoundException: the secret has no resource policy (relies on IAM only). This is recorded aspasswith a note, NOT as inconclusive.- 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:
- No findings cache writes. The retrieval branch is the first thing
main()does when--retrieveis set; it never reaches the cache-writing helpers.ls ~/.cache/claude-grc/findings/aws-secrets-inspector/after a retrieve shows no new files. - No value in
runs.log. The manifest recordsbyte_sizeandsha256of the artifact, not the value. Auditors can verify which artifact was produced without storing the value. --write-tois restricted. The path must resolve under~/.config/claude-grc/secrets/. The helper usespath.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
- If IAC-21 fails on a secret: delete the public statement from the resource policy immediately, then audit
CloudTrailfor anyGetSecretValuecalls from outside your org before the fix. This is alertable. - 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.AutomaticallyAfterDaysis in [30, 90]. - If CRY-09 (CMK) fails on a regulated workload: provision a customer-managed KMS key, grant the Secrets Manager service principal
kms:Encrypt/kms:Decrypton the key, and update the secret viaaws secretsmanager update-secret --kms-key-id .... Re-run inspector to confirm. - If IAC-15.3 fails (LastAccessedDate > 180d): this is a candidate for archival, not deletion. Verify the consumer is genuinely retired (check
aws logsfor 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 evaluateNotPrincipal,Condition, oraws:SourceVpceallowlists. ACondition-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-valueis the AWS API for bulk, and this connector intentionally does not wrap it.
Common pitfalls
- Running without
--profilein a multi-account environment: the connector uses the default chain. IfAWS_PROFILEis set, that wins. If neither, the SDK falls through to env vars →~/.aws/credentials→ IRSA/SSO. Verify with/aws-secrets-inspector:statusbefore a retrieve. - Forgetting that retrieve mode requires separate IAM:
secretsmanager:GetSecretValueis 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 havekms:Decrypton the key, or the API returnsAccessDeniedException(not aNotFound— that comes from the resource policy). - Resource policy vs IAM: a resource policy
Denyoverrides an IAMAllowfor the same principal. If a retrieve returnsAccessDeniedExceptiondespite the role havingGetSecretValue, 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'sdefault_regionordefaults.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
--quietor--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
0success2credentials invalid or expired; usage error in retrieval mode3rate-limited (AWS throttling; retry later)4partial (some regions inaccessible; report still written)5config missing — run setup6retrieval 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 theget-secret-valuecall; falls back to the first of--regions, thenconfig.defaults.regions[0], thenconfig.default_region, thenAWS_DEFAULT_REGION/AWS_REGION, thenus-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:
- No findings cache writes. The retrieval branch short-circuits at the top of
main()and never reaches the cache-writing helpers. - No value in
runs.log. The retrieval manifest recordsbyte_sizeandsha256of the artifact, not the value. Operators and auditors can verify which artifact was produced without storing the value. --write-tois 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
0success2usage error (unknown flag,--write-tooutside the permitted root)2auth failure (credentials invalid or expired)2access denied by IAM, KMS key policy, or the secret's resource policy3rate-limited5config missing — run setup6secret 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-tothat 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:
--profileflag (writes it to config)AWS_PROFILEenvironment variableAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYenv vars~/.aws/credentialsdefault profile- 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
-
Check
awsCLI is installed (aws --version). -
Resolve credentials (
aws sts get-caller-identity). -
Resolve default region (from
--region,AWS_REGION, config, or fall back with a warning). -
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 -
Create the cache dir
~/.cache/claude-grc/findings/aws-secrets-inspector/and ensure~/.cache/claude-grc/runs.logexists. -
Create the secrets dir
~/.config/claude-grc/secrets/at mode 0700 (operator-only). -
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 awsclior 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 configureor SSO session. - Region not set: warning; defaults to
us-east-1and 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 runcredentials-expired— STS call fails; refresh SSO or rotate keysstale— last run > 7 daysno-cache— configured but no runs yetaws-not-installed— theawsCLI 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- azure-inspectorv0.1.0
- ch-fadpv0.1.0
- cis-controlsv0.1.0
- cmmcv0.1.0
- compliance-posture-dashboardv0.1.0
- crowdstrike-inspectorv0.1.0
- csa-ccmv0.1.0
- cyber-essentials-plusv0.1.0
- datadog-inspectorv0.1.0
- dorav0.1.0
- drata-inspectorv0.1.0
- essential8v0.1.0
- eu-nis2v0.1.0
- fedramp-20xv0.1.0
- fedramp-rev5v0.1.0
- fedramp-sspv0.1.0
- gcp-docsv0.1.0
- gcp-inspectorv0.1.0
- gcp-secret-metadatav0.1.0
- gdprv0.1.0
- github-inspectorv0.1.0
- glbav0.1.0
- grc-auditorv0.1.0
- grc-diagramsv0.1.0