GRC connector for AWS: IAM, S3, CloudTrail, EBS compliance checks → v1 finding contract

version
0.1.0
GitHub stars
436

Install

/plugin install aws-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-inspector expert

You are the interpretation layer between raw AWS configuration data and compliance frameworks. Your job is to:

  1. Understand what each aws-inspector check evaluates and why it matters.
  2. Interpret failure modes correctly — distinguish "this is genuinely non-compliant" from "we don't have permission to check."
  3. Translate findings into framework-appropriate language (SOC 2, FedRAMP, PCI DSS, NIST 800-53).

Checks this connector runs (v0.1.0)

IAM (account-scoped):

SCF IDCheckSource of truthSeverity
IAC-01.1Root MFA enablediam get-account-summary → AccountMFAEnabledcritical
IAC-15.1No root access keysiam get-account-summary → AccountAccessKeysPresentcritical
IAC-02Password policy meets baselineiam get-account-password-policyhigh

S3 (per bucket):

SCF IDCheckSeverity
CRY-05Default server-side encryptionhigh if missing
DCH-01.2All four public access block flags oncritical
AST-05Versioning enabledmedium

CloudTrail (per home region):

SCF IDCheckSeverity
MON-02Multi-region trail existshigh
MON-02.1Log file validation enabledmedium
MON-02.2Trail is actively logginghigh

EBS (per region):

SCF IDCheckSeverity
CRY-05Default encryption onhigh

Framework mappings (via SCF crosswalk)

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

  • IAC-01.1 (root MFA) → SOC 2 CC6.1, CC6.2 · NIST 800-53 IA-02(01), IA-05(01) · FedRAMP IA-02(01) (mandatory) · PCI 8.4.2 · CIS 1.13
  • IAC-02 (password policy) → SOC 2 CC6.1 · NIST 800-53 IA-05 · PCI 8.3 · CIS 1.8
  • CRY-05 (encryption at rest) → SOC 2 CC6.1, CC6.7 · NIST 800-53 SC-28 · ISO 27002 A.8.24 · PCI 3.5 · FedRAMP SC-28
  • DCH-01.2 (S3 public access) → SOC 2 CC6.7, CC8.1 · NIST 800-53 SC-7, AC-06 · PCI 1.3.1
  • MON-02 (CloudTrail multi-region) → SOC 2 CC7.2, CC7.3 · NIST 800-53 AU-02, AU-12 · FedRAMP AU-02 · PCI 10.2

Interpreting output

"fail" with critical severity

Treat as blocking. Root MFA missing or S3 public access block missing = you cannot pass an audit. Root access keys = "how is this account still alive?" territory. Prioritize these.

"fail" with high severity

Blocks most audits but isn't a "stop everything" moment. Encryption-at-rest defaults, multi-region CloudTrail, password policy — these need to be fixed before a FedRAMP ATO or SOC 2 Type II.

"inconclusive"

Almost always means the caller lacks the IAM permission. Common culprits:

  • s3:GetBucketEncryption denied on buckets owned by other accounts in an organization.
  • cloudtrail:GetTrailStatus requires cloudtrail:GetTrailStatus, separate from DescribeTrails.
  • Cross-account roles with read-only policies but missing the specific read action.

Remedy: attach SecurityAudit managed policy, or the minimum policy documented in commands/collect.md.

Account-level resources

Some checks are per-account, not per-resource. The Finding resource looks like:

"resource": {
  "type": "aws_account",
  "id": "123456789012",
  "arn": "arn:aws:iam::123456789012:root",
  "region": null,
  "account_id": "123456789012"
}

This is intentional — it lets gap-assessment count the check once per account, not once per bucket.

When a user asks what to do next

After a gap-assessment, guide them to high-leverage remediation:

  1. If root MFA fails: zero argument. Do it today. Hardware YubiKey preferred; virtual MFA is acceptable. Any root activity is alertable.

  2. If S3 public access block fails across many buckets: apply an account-level public access block (single API call) rather than per-bucket: aws s3control put-public-access-block --account-id <id> --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true. Existing public buckets aren't retroactively broken, but new ones are restricted.

  3. If CloudTrail multi-region fails: one multi-region trail covers the whole account. No reason to have N single-region trails.

  4. If EBS default encryption fails in many regions: Terraform aws_ebs_encryption_by_default resource + for_each over regions. Also: AWS Config rule to alert if it ever gets disabled.

Limits of this connector (v0.1.0)

Be honest about coverage gaps:

  • Not checking: VPC flow logs, Security Hub findings, Config conformance pack state, GuardDuty, KMS key rotation, SSM patch compliance, RDS encryption, Lambda permissions, Secrets Manager rotation, WAF rules.
  • Per-user IAM (unused access keys, inactive users, inline policies): planned for v0.2.
  • Cross-account / Organizations: doesn't enumerate member accounts. Run per-account.

When a user asks about these, say "not yet" and point to the relevant AWS-native tool (Security Hub, Config, GuardDuty) as complementary.

Common pitfalls

  • Running as root: don't. Use a dedicated IAM role.
  • Large accounts: S3 list-buckets is flat, but per-bucket checks are 3 API calls × N buckets. 1000-bucket accounts take a few minutes; parallelism is bounded to stay under the 3500 req/min default.
  • Cross-region AWS services: IAM and S3 list are global; CloudTrail, EBS are per-region. Always pass --regions= for a complete picture.
  • SCP / permission boundaries: can silently block read actions. If many checks are inconclusive, check aws iam simulate-principal-policy to see what's blocked.

Commands 3

/aws-inspector:collect

Scans AWS for compliance-relevant resources and configurations. Emits one Finding document per evaluated resource (account-level, per-bucket, per-trail, etc.).

How to run

node plugins/connectors/aws-inspector/scripts/collect.js [options]

Arguments

  • --regions=<csv> — regions to scan (default: the config's default_region; IAM + S3 + CloudTrail have global/multi-region considerations)
  • --services=<csv> — subset of iam,s3,cloudtrail,ebs (default: all)
  • --profile=<name> — override the configured AWS profile
  • --output=<fmt> — silent | summary (default) | json
  • --refresh — ignore cache; re-query AWS
  • --quiet — no stderr progress

What it evaluates

Account-level (IAM):

SCFCheckTypical severity
IAC-01.1Root account has MFAcritical if missing
IAC-02Password policy meets baselinehigh if missing
IAC-15.1No IAM users with access keys older than 90dmedium
IAC-15.1No IAM users with unused keys/passwords (>90d)low
IAC-07.2No inline IAM policies on users (least privilege signal)low

Storage (S3):

SCFCheckSeverity
CRY-05Bucket default encryptionhigh if missing
DCH-01.2Public access block enforcedcritical if missing
AST-05Versioning enabled on production bucketsmedium
MON-01.2Server access logging enabledmedium

Audit (CloudTrail):

SCFCheckSeverity
MON-02At least one multi-region, multi-account trailhigh if missing
MON-02.1Log file validation enabledmedium
MON-02.2Trail events delivered to a monitored S3 bucketmedium

Compute (EBS):

SCFCheckSeverity
CRY-05Default EBS encryption enabled per regionhigh if missing

Future: RDS (encryption, backup), VPC flow logs, Security Hub findings, Config conformance packs, Guard​Duty enablement, SSM patch compliance, KMS key rotation.

Output

  • Writes ~/.cache/claude-grc/findings/aws-inspector/<run_id>.json — array of Findings

  • Appends a run manifest to ~/.cache/claude-grc/runs.log

  • One-line summary unless --quiet:

    aws-inspector: 24 resources, 87 evaluations, 9 failing (2 critical, 4 high, 3 medium).
    

Exit codes

  • 0 success
  • 2 credentials invalid or expired
  • 3 rate-limited (AWS throttling; retry later)
  • 4 partial (some services inaccessible; report still written)
  • 5 config missing — run setup

Permissions

Minimum IAM policy for a read-only scan:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetAccountPasswordPolicy", "iam:GetAccountSummary",
        "iam:ListUsers", "iam:ListAccessKeys", "iam:GetLoginProfile", "iam:GetUser", "iam:ListMFADevices", "iam:ListUserPolicies", "iam:ListAttachedUserPolicies",
        "s3:ListAllMyBuckets", "s3:GetBucketEncryption", "s3:GetBucketPublicAccessBlock", "s3:GetBucketVersioning", "s3:GetBucketLogging", "s3:GetBucketLocation",
        "cloudtrail:DescribeTrails", "cloudtrail:GetTrailStatus", "cloudtrail:GetEventSelectors",
        "ec2:GetEbsEncryptionByDefault"
      ],
      "Resource": "*"
    }
  ]
}

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

Examples

# Default region, all services
/aws-inspector:collect

# Multi-region scan
/aws-inspector:collect --regions=us-east-1,us-west-2,eu-west-1

# Just the storage story
/aws-inspector:collect --services=s3

# Alternate profile
/aws-inspector:collect --profile=audit-role

CI/CD usage

aws sso login --profile=audit
AWS_PROFILE=audit node plugins/connectors/aws-inspector/scripts/collect.js --quiet
node plugins/grc-engineer/scripts/gap-assessment.js FedRAMP-Moderate,SOC2 --sources=aws-inspector --output=sarif --quiet > aws-gap.sarif

/aws-inspector:setup

Prepares the aws-inspector connector. Confirms aws CLI is installed and credentials resolve, writes ~/.config/claude-grc/connectors/aws-inspector.yaml, and runs a read-only health check.

How to run

bash plugins/connectors/aws-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-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"]    # add more with /aws-inspector:collect --regions=...
      services: ["iam", "s3", "cloudtrail", "ebs"]
    
  5. Warn if the caller ARN has administrative privileges (dogfooding: production scans should use a dedicated read-only IAM role like SecurityAudit).

Typical output

aws-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

WARNING: Caller appears to have admin privileges. For production, use a
dedicated read-only role (e.g., AWS-managed SecurityAudit policy).

Next: /aws-inspector:collect

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.

Safe to re-run

Yes. Overwrites the config; preserves cached findings.

/aws-inspector:status

Non-destructive health check. Shows whether the connector is configured, whether credentials still work, and when it last produced findings.

How to run

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

Output

aws-inspector
  status:         ready
  aws:            /opt/homebrew/bin/aws 2.15.1
  account:        123456789012
  caller:         arn:aws:iam::123456789012:role/SecurityAudit
  profile:        audit
  default region: us-east-1
  config:         ~/.config/claude-grc/connectors/aws-inspector.yaml
  last run:       3h ago (run_id 20260413-a1b2c3d4)
  cached:         24 resources, 87 evaluations

Status values

  • ready — all systems go
  • 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

Sponsors

Details

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

More from GRCEngClub/claude-grc-engineering

All 70