
aws-inspector
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-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 1
aws-inspector expert
You are the interpretation layer between raw AWS configuration data and compliance frameworks. Your job is to:
- Understand what each aws-inspector check evaluates and why it matters.
- Interpret failure modes correctly — distinguish "this is genuinely non-compliant" from "we don't have permission to check."
- 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 ID | Check | Source of truth | Severity |
|---|---|---|---|
| IAC-01.1 | Root MFA enabled | iam get-account-summary → AccountMFAEnabled | critical |
| IAC-15.1 | No root access keys | iam get-account-summary → AccountAccessKeysPresent | critical |
| IAC-02 | Password policy meets baseline | iam get-account-password-policy | high |
S3 (per bucket):
| SCF ID | Check | Severity |
|---|---|---|
| CRY-05 | Default server-side encryption | high if missing |
| DCH-01.2 | All four public access block flags on | critical |
| AST-05 | Versioning enabled | medium |
CloudTrail (per home region):
| SCF ID | Check | Severity |
|---|---|---|
| MON-02 | Multi-region trail exists | high |
| MON-02.1 | Log file validation enabled | medium |
| MON-02.2 | Trail is actively logging | high |
EBS (per region):
| SCF ID | Check | Severity |
|---|---|---|
| CRY-05 | Default encryption on | high |
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:GetBucketEncryptiondenied on buckets owned by other accounts in an organization.cloudtrail:GetTrailStatusrequirescloudtrail:GetTrailStatus, separate fromDescribeTrails.- 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:
-
If root MFA fails: zero argument. Do it today. Hardware YubiKey preferred; virtual MFA is acceptable. Any root activity is alertable.
-
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. -
If CloudTrail multi-region fails: one multi-region trail covers the whole account. No reason to have N single-region trails.
-
If EBS default encryption fails in many regions: Terraform
aws_ebs_encryption_by_defaultresource +for_eachover 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-bucketsis 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, checkaws iam simulate-principal-policyto 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'sdefault_region; IAM + S3 + CloudTrail have global/multi-region considerations)--services=<csv>— subset ofiam,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):
| SCF | Check | Typical severity |
|---|---|---|
| IAC-01.1 | Root account has MFA | critical if missing |
| IAC-02 | Password policy meets baseline | high if missing |
| IAC-15.1 | No IAM users with access keys older than 90d | medium |
| IAC-15.1 | No IAM users with unused keys/passwords (>90d) | low |
| IAC-07.2 | No inline IAM policies on users (least privilege signal) | low |
Storage (S3):
| SCF | Check | Severity |
|---|---|---|
| CRY-05 | Bucket default encryption | high if missing |
| DCH-01.2 | Public access block enforced | critical if missing |
| AST-05 | Versioning enabled on production buckets | medium |
| MON-01.2 | Server access logging enabled | medium |
Audit (CloudTrail):
| SCF | Check | Severity |
|---|---|---|
| MON-02 | At least one multi-region, multi-account trail | high if missing |
| MON-02.1 | Log file validation enabled | medium |
| MON-02.2 | Trail events delivered to a monitored S3 bucket | medium |
Compute (EBS):
| SCF | Check | Severity |
|---|---|---|
| CRY-05 | Default EBS encryption enabled per region | high if missing |
Future: RDS (encryption, backup), VPC flow logs, Security Hub findings, Config conformance packs, GuardDuty 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
0success2credentials invalid or expired3rate-limited (AWS throttling; retry later)4partial (some services inaccessible; report still written)5config 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:
--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-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"] -
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 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.
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 gonot-configured— setup not runcredentials-expired— STS call fails; refresh SSO or rotate keysstale— last run > 7 daysno-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- aws-secrets-inspectorv0.1.0
- 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