Metadata-Version: 2.4
Name: aws-finops-auditor
Version: 1.0.0
Summary: Read-only AWS FinOps CLI auditor for identifying idle compute, orphaned storage, and unattached network waste.
Author: Aisser Rodriguez
License-Expression: MIT
Project-URL: Homepage, https://github.com/Ace-FinOps-Enterprise/aws-finops-auditor
Project-URL: Repository, https://github.com/Ace-FinOps-Enterprise/aws-finops-auditor
Project-URL: Practitioner & Enterprise Tiers, https://aisser.gumroad.com/l/krgac
Keywords: aws,finops,cloud-cost,cost-optimization,devops,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.28.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: enterprise
Requires-Dist: fpdf>=1.7.2; extra == "enterprise"
Requires-Dist: requests>=2.31.0; extra == "enterprise"

# AWS Cloud Cost Auditor & FinOps Toolkit

A zero-agent, production-grade CLI suite designed to audit AWS infrastructure for orphaned resources, calculate monthly financial drag, synthesize remediation bash scripts, and generate branded executive PDF showbacks.

---

## Prerequisites

- **Python 3.10+**
- **AWS CLI** configured with appropriate permissions (`aws configure` or standard AWS environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).

---

## Installation

Extract your purchased archive, navigate into the directory, and install dependencies:

```bash
pip install -r requirements.txt
```

---

## 1. Practitioner Quickstart (Single-Account Audits)

> *Included in Practitioner & Agency tiers (`infrastructure_auditor.py`)*

Audit the active AWS account configured in your local environment.

### Run Audit Against Live AWS Infrastructure
```bash
python infrastructure_auditor.py --compliance --remediate
```

### Run in Demo / Offline Mode (Using Sample Dataset)
```bash
python infrastructure_auditor.py --file sample_aws_data.csv --compliance --remediate
```

### Outputs Generated:
- **Terminal Summary:** Categorized breakdown of orphaned EBS volumes, low-utilization compute, and unassociated Elastic IPs.
- **`compliance_audit_export.csv`:** Full resource inventory with showback cost tags and compliance control mappings (SOC2 CC6.6, ISO27001 A.10.1.1).
- **`remediate_anomalies.sh`:** Ready-to-review bash script with safe CLI commands to purge waste.

---

## 2. Enterprise & Agency Quickstart (Multi-Account AWS Organizations)

> *Included in the Consultancy & Agency Pack (`enterprise_audit.py`)*

Scan multiple member accounts across an entire AWS Organization via STS role assumption and generate executive PDF reports.

### Cross-Account IAM Role Setup
Deploy `org-access-role.yaml` via **AWS CloudFormation StackSets** across your target member accounts:
- Default Role Name: `OrganizationAccountAccessRole`
- Trust Relationship: Your primary management/auditing account ID.

### Run Full Multi-Account Audit & Executive PDF Generation
```bash
python enterprise_audit.py --license-key YOUR_GUMROAD_KEY --report --remediate
```

### Advanced Enterprise CLI Flags
| Flag | Description | Default |
| :--- | :--- | :--- |
| `--license-key` | Gumroad enterprise license key for verification | *Required* |
| `--report` | Compiles client-ready executive PDF report | `False` |
| `--report-out` | Custom output file path for the PDF deliverable | `AWS_FinOps_Executive_Report.pdf` |
| `--remediate` | Generates `remediate_anomalies.sh` purge script | `False` |
| `--org-id` | Custom company/client name for PDF header branding | `AWS Organization Root` |
| `--regions` | Comma-separated list of AWS regions to scan | `us-east-1,us-east-2,us-west-2` |
| `--role-name` | Cross-account IAM role to assume via STS | `OrganizationAccountAccessRole` |
| `--demo` | Populates report from `sample_aws_data.csv` if live accounts show $0 waste | `False` |

### Example: Multi-Region Scan with Custom Client Branding
```bash
python enterprise_audit.py \
  --license-key YOUR_GUMROAD_KEY \
  --org-id "Acme Corp Infrastructure" \
  --regions "us-east-1,us-west-2,eu-west-1" \
  --report \
  --report-out "Acme_FinOps_Q4_Audit.pdf" \
  --remediate
```

---

## 3. Executing Remediation Safely

Every audit that includes `--remediate` generates an idempotent bash script (`remediate_anomalies.sh`) with `set -euo pipefail` safety controls:

1. **Inspect before executing:**
   ```bash
   cat remediate_anomalies.sh
   # On Windows PowerShell:
   Get-Content remediate_anomalies.sh
   ```
2. **Execute remediation purge:**
   ```bash
   chmod +x remediate_anomalies.sh
   ./remediate_anomalies.sh
   ```

*Non-destructive actions (like upgrading deprecated RDS engines) are prefixed with `#` as operational warnings and require manual review.*

---

## Support & Upgrades

- **Commercial Licenses & Add-ons:** [Gumroad Product Portal](https://aisser.gumroad.com/l/krgac)
- **Issues & Support:** Contact support via your Gumroad receipt portal or primary vendor email.
