aws-guardrails

aws-guardrails is a small Python package for catching broken AWS infrastructure documents before they reach review or deployment.

Current scope:

• IAM JSON policy syntax and structure validation
• CloudFormation JSON/YAML syntax validation
• Duplicate-key detection for JSON and YAML mappings
• CloudFormation-aware YAML parsing for intrinsic tags such as !Ref and !Sub
• invalid IAM action detection with typo and wrong-service suggestions
• IAM security best-practice checks for public access and risky policy constructs
• IAM least-privilege checks for wildcard actions, wildcard resources, and iam:PassRole
• CloudFormation checks for sensitive parameters and embedded IAM policies

Planned next scope:

• more AWS service-specific privilege-escalation patterns
• deeper CloudFormation resource configuration checks
• optional policy packs and CI fail thresholds

Install

pip install .

Usage

Validate a single IAM policy:

aws-guardrails validate examples/policy.json --kind iam

Validate a single CloudFormation template:

aws-guardrails validate examples/template.yaml --kind cloudformation

Validate a whole folder recursively:

aws-guardrails validate ./infra/

Validate a mixed set of files and folders in one run:

aws-guardrails validate ./iam/policy.json ./cfn ./shared/templates

Auto-detect document type:

aws-guardrails validate path/to/file-or-directory

Emit machine-readable output:

aws-guardrails validate templates/ --format json

What it flags

• syntax errors in IAM JSON and CloudFormation JSON/YAML
• duplicate keys in JSON and YAML mappings
• invalid IAM action names such as ec2:CreateRole
• probable IAM action typos such as s3:GetObejct
• Allow statements with Action: "*" or broad service wildcards
• Allow statements using NotAction, NotResource, or NotPrincipal
• public resource policies using Principal: "*"
• risky iam:PassRole permissions
• CloudFormation sensitive parameters without NoEcho
• literal default secrets in CloudFormation parameters
• IAM policy misuse inside CloudFormation role, managed policy, and policy resources

Example

aws-guardrails validate bad-policy.json --kind iam

Example output:

FAIL bad-policy.json [iam]
  - ERROR IAM033 Statement[0].Action uses unknown action 'ec2:CreateRole'.
    Fix: Did you mean 'iam:CreateRole'?

Summary: scanned 1 file(s), clean 0, warning-only 0, failed 1.

Exit codes

• 0: all files passed validation
• 1: one or more validation errors were found
• 2: CLI usage or runtime error

ERROR and SECURITY findings fail validation. WARNING findings are advisory.