Metadata-Version: 2.4
Name: cloud-iam-auditor-pb
Version: 0.3.0
Summary: A lightweight CLI that audits AWS, GCP, and Azure IAM JSON policies for zero-trust violations, mapped to NIST 800-53, NIST 800-207, CIS Foundations, and MITRE ATT&CK. Supports live API scanning.
Author-email: Purvansh Bhatt <purvansh95b@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Purvansh Bhatt
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/purvanshbhatt/cloud-iam-auditor
Project-URL: Repository, https://github.com/purvanshbhatt/cloud-iam-auditor
Project-URL: Issues, https://github.com/purvanshbhatt/cloud-iam-auditor/issues
Project-URL: Changelog, https://github.com/purvanshbhatt/cloud-iam-auditor/blob/main/CHANGELOG.md
Keywords: aws,gcp,azure,iam,security,cloud-security,zero-trust,compliance,nist,mitre,cis,audit,cli,sarif,devsecops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: live
Requires-Dist: boto3>=1.28.0; extra == "live"
Requires-Dist: google-cloud-resourcemanager>=1.10.0; extra == "live"
Provides-Extra: azure
Requires-Dist: azure-identity>=1.14.0; extra == "azure"
Requires-Dist: azure-mgmt-authorization>=3.0.0; extra == "azure"
Provides-Extra: all
Requires-Dist: cloud-iam-auditor-pb[azure,dev,live]; extra == "all"
Dynamic: license-file

# cloud-iam-auditor-pb

> A lightweight, offline CLI that audits exported **AWS** and **GCP** IAM JSON policies for zero-trust violations and maps every finding to **NIST 800-53**, **NIST 800-207**, **CIS Foundations (AWS / GCP)**, and **MITRE ATT&CK Enterprise**.

[![PyPI version](https://img.shields.io/pypi/v/cloud-iam-auditor-pb.svg)](https://pypi.org/project/cloud-iam-auditor-pb/)
[![Python](https://img.shields.io/pypi/pyversions/cloud-iam-auditor-pb.svg)](https://pypi.org/project/cloud-iam-auditor-pb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/purvanshbhatt/cloud-iam-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/purvanshbhatt/cloud-iam-auditor/actions/workflows/ci.yml)

`cloud-iam-auditor-pb` is a deterministic, no-credential-required security scanner. It does **not** call AWS or GCP - it parses IAM policy documents you export and flags over-permissive patterns that violate least-privilege and zero-trust principles.

---

## Table of contents

- [Why this exists](#why-this-exists)
- [Install](#install)
- [Quickstart](#quickstart)
  - [AWS](#aws)
  - [GCP](#gcp)
- [CLI reference](#cli-reference)
- [Detection rules](#detection-rules)
  - [AWS rules (10)](#aws-rules-10)
  - [GCP rules (5)](#gcp-rules-5)
- [Framework mappings](#framework-mappings)
- [CI/CD integration](#cicd-integration)
- [Supported inputs](#supported-inputs)
- [What v0.2.0 does **not** do](#what-v020-does-not-do-by-design)
- [Roadmap](#roadmap)
- [Development](#development)
- [License](#license)

---

## Why this exists

Startups scale fast. Developers reach for `AdministratorAccess`, `Action: "*"` or `roles/owner` to ship, creating security debt invisible until a breach. `cloud-iam-auditor-pb` lets an engineer drop a JSON file and answer:

> *Is this IAM role stuck in zero-trust debt? Which NIST / MITRE / CIS controls does it violate, and how do I fix it?*

in under one second, in their terminal or in CI.

Multi-cloud teams benefit further: the same `iam-audit` binary handles both AWS IAM statements and GCP IAM role bindings, so a single CI gate keeps debt out of either cloud.

## Install

```bash
pip install cloud-iam-auditor-pb
```

Requires Python >= 3.8. Works on Linux, macOS, and Windows.

## Quickstart

Provider is **auto-detected** from the JSON shape:

| Top-level JSON key | Detected provider | Rule set used |
|---|---|---|
| `Statement` (or `PolicyDocument`) | AWS | 10 AWS rules |
| `bindings` | GCP | 5 GCP rules |

### AWS

```bash
iam-audit scan examples/sample_aws_policy.json
```

Machine-readable output for CI:

```bash
iam-audit scan iam/release-role.json --json --severity high --exit-code
```

### GCP

Export a project's IAM policy with:

```bash
gcloud projects get-iam-policy PROJECT_ID --format=json > iam/project_bindings.json
```

Then:

```bash
iam-audit scan iam/project_bindings.json
```

The CLI will print `Detected GCP IAM policy...` and run the 5 GCP rules against the bindings array.

## CLI reference

```
iam-audit --version
iam-audit scan PATH [--json] [--severity LEVEL] [--exit-code] [--no-color]
iam-audit rules [--json]
```

| Flag | Purpose |
|---|---|
| `--json` | Emit machine-readable JSON instead of a Rich table. |
| `--severity {low,medium,high,critical}` | Only report findings at or above the threshold. |
| `--exit-code` | Exit non-zero (1) when any finding remains - perfect for CI gates. |
| `--no-color` | Disable ANSI styling (accessibility / logs). |

Status line ("Detected AWS/GCP IAM policy...") is written to **stderr**, so JSON pipes consuming stdout stay clean.

## Detection rules

There are **15 rules** total (10 AWS + 5 GCP). Each is implemented as a single class in its own module, registered with the provider-specific registry, and accompanied by a passing and failing fixture in `tests/fixtures/`.

Run `iam-audit rules` to get the same table in your terminal.

### AWS rules (10)

| ID | Rule | Severity | Map |
|---|---|---|---|
| IAM001 | `Action: "*"` on Allow | Critical | NIST AC-6 / CIS 1.16 / MITRE T1078.004 |
| IAM002 | `Resource: "*"` with broad Action set | High | NIST AC-6 / ZT 3.2.1 / CIS 1.16 |
| IAM003 | AWS-managed `AdministratorAccess` attached | Critical | NIST AC-6(5) / CIS 1.16 / MITRE T1078.004 |
| IAM004 | `iam:PassRole` against `"*"` | High | NIST AC-3 / MITRE T1078.004 |
| IAM005 | Sensitive action with no `Condition` block | Medium | NIST IA-2(1) / CIS 1.4 / MITRE T1098 |
| IAM006 | `NotAction` used with `Allow` | High | NIST AC-6 / CIS 1.16 |
| IAM007 | `NotResource` used with `Allow` | Medium | NIST AC-6 / CIS 1.16 |
| IAM008 | `sts:AssumeRole` against `"*"` (no trust condition) | High | NIST AC-6 / MITRE T1550.001 |
| IAM009 | `kms:Decrypt` against wildcard resource | High | NIST SC-12 / CIS 2.8 |
| IAM010 | `s3:PutObject` against `arn:aws:s3:::*/*` | Medium | NIST SC-28 / CIS 2.1.5 |

### GCP rules (5)

| ID | Rule | Severity | Map |
|---|---|---|---|
| GCP001 | Privileged role (`owner`/`editor`/`*admin*`) granted to `allUsers` / `allAuthenticatedUsers` | Critical | CIS GCP 1.4 / 1.5 / MITRE T1078.004 |
| GCP002 | Any role granted to public members (non-privileged - intentional access check) | High | CIS GCP 1.10 / MITRE T1078.004 |
| GCP003 | `roles/iam.serviceAccountUser` granted to >3 principals (SA impersonation blast radius) | Medium | NIST AC-6 / MITRE T1098 |
| GCP004 | Legacy primitive role (`owner`/`editor`/`viewer`) granted to a principal | High | CIS GCP 1.3 / NIST AC-6(5) / MITRE T1078.004 |
| GCP005 | `roles/iam.serviceAccountTokenCreator` granted to >2 principals (OAuth token-mint blast radius) | High | NIST AC-6 / MITRE T1550.001 / T1098 |

## Framework mappings

Every finding ships with one or more framework references that the reporter renders inline. The full mapping table lives in [`cloud_iam_auditor/frameworks.py`](cloud_iam_auditor/frameworks.py) and covers:

- **NIST SP 800-53 Rev. 5** (e.g. AC-6, AC-6(5), AC-6(7), AC-3, SC-12, SC-28, IA-2, IA-2(1))
- **NIST SP 800-207** Zero Trust Architecture
- **CIS AWS Foundations Benchmark v3.0** (1.4, 1.16, 2.1.5, 2.8)
- **CIS GCP Foundations Benchmark v3.0** (1.3, 1.4, 1.5, 1.10)
- **MITRE ATT&CK Enterprise** (T1078, T1078.004, T1098, T1556, T1550, T1550.001)

## CI/CD integration

Drop this step into any GitHub Actions job after you check out the policy file:

```yaml
- run: pip install cloud-iam-auditor-pb
- run: iam-audit scan iam/release-role.json --json --exit-code --severity high
```

The job will fail (exit 1) if any High or Critical finding exists. The same workflow supports GCP bindings:

```yaml
- run: gcloud projects get-iam-policy ${{ vars.PROJECT_ID }} --format=json > iam/bindings.json
- run: iam-audit scan iam/bindings.json --json --exit-code --severity high
```

## Supported inputs

| Provider | Accepted shapes |
|---|---|
| AWS | Bare policy: `{"Version": "...", "Statement": [...]}` <br> Wrapped `aws iam get-policy-version` response: `{"PolicyDocument": {...}, "PolicyName": "..."}` <br> Single statement or array - both normalized. |
| GCP | `{"bindings": [{"role": "roles/...", "members": [...]}, ...]}` (output of `gcloud projects get-iam-policy`). Each binding must contain `role` and `members`. |

The loader raises a clear `LoaderError` describing the expected shape on any failure with exit code 2.

## What v0.2.0 does **not** do (by design)

- **No cloud credentials.** v0.2.0 is a static JSON audit; it never calls AWS or GCP.
- **Live AWS / GCP mode** (boto3 / google-cloud-iam) is on the v0.3.0 roadmap.
- **Azure RBAC** support is on the v0.3.0 roadmap.
- **SARIF** output (for GitHub Code Scanning) is on the v0.3.0 roadmap.

This scoping keeps v0.2.0 auditable, dependency-light, and CI-friendly.

## Roadmap

See [`CHANGELOG.md`](CHANGELOG.md) for the planned v0.3.0 work.

## Development

```bash
git clone https://github.com/purvanshbhatt/cloud-iam-auditor
cd cloud-iam-auditor
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux
pip install -e ".[dev]"
pytest -q                       # 57 tests across AWS + GCP
ruff check .
python -m build                 # produce wheel + sdist in dist/
```

## License

[MIT](LICENSE) - (c) 2026 Purvansh Bhatt.
