Metadata-Version: 2.4
Name: aws-guardrails
Version: 0.1.0
Summary: Syntax validation for IAM JSON policies and AWS CloudFormation templates.
Author: Codex
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"

# 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

```bash
pip install .
```

## Usage

Validate a single IAM policy:

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

Validate a single CloudFormation template:

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

Validate a whole folder recursively:

```bash
aws-guardrails validate ./infra/
```

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

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

Auto-detect document type:

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

Emit machine-readable output:

```bash
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

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

Example output:

```text
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.
