Metadata-Version: 2.4
Name: iamx
Version: 0.1.0
Summary: IAM Policy Explainer - Local-first IAM policy analyzer with deterministic risk detection
Project-URL: Homepage, https://github.com/iamsteve0/iamx
Project-URL: Documentation, https://github.com/iamsteve0/iamx#readme
Project-URL: Repository, https://github.com/iamsteve0/iamx
Project-URL: Issues, https://github.com/iamsteve0/iamx/issues
Author-email: iamsteve0 <sefthuko28.projects@gmail.com>
License: MIT
License-File: LICENSE
Keywords: analyzer,aws,devops,iam,policy,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Requires-Dist: boto3>=1.26.0
Requires-Dist: botocore>=1.29.0
Requires-Dist: click>=8.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: uvicorn[standard]>=0.20.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: tox>=4.0.0; extra == 'dev'
Provides-Extra: web
Requires-Dist: fastapi>=0.100.0; extra == 'web'
Requires-Dist: jinja2>=3.0.0; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.20.0; extra == 'web'
Description-Content-Type: text/markdown

# iamx - IAM Policy Explainer

A local-first IAM policy analyzer that scans AWS IAM JSON policies, detects risky patterns deterministically, explains them in plain English, assigns severity levels, and suggests least-privilege fixes.

## 🎯 Why iamx?

Copy-pasting IAM policies into ChatGPT is unsafe, inaccurate, and doesn't scale for bulk analysis. Manual policy review is time-consuming and error-prone.

**iamx solves these problems:**
- ✅ **Accuracy first** - Static parser + deterministic rules (no hallucinations)
- ✅ **Human-readable explanations** - Plain English descriptions of risks
- ✅ **Bulk scanning** - Process multiple policies efficiently
- ✅ **CI/CD integration** - GitHub Actions with configurable thresholds
- ✅ **Privacy-first** - Local by default, optional AI summaries
- ✅ **Multiple outputs** - Markdown, JSON, and interactive web reports

## 🚀 Features

### Core Analysis
- **Deterministic pattern detection** - No AI hallucinations, consistent results
- **Risk severity classification** - Critical/High/Medium/Low based on impact
- **Plain English explanations** - Understandable descriptions of each finding
- **Least-privilege suggestions** - Specific recommendations for policy improvements

### Supported Patterns
- Overly permissive actions (`*` permissions)
- Wildcard resources without restrictions
- Cross-account access patterns
- Administrative actions detection
- Data access actions analysis
- Missing resource restrictions
- Sensitive service permissions

### Output Formats
- **CLI** - Terminal output with color-coded results
- **Web UI** - Interactive local web interface
- **Markdown** - Detailed reports for documentation
- **JSON** - Machine-readable output for CI/CD
- **GitHub Actions** - Automated policy reviews in PRs

## 🛠️ Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/iamx.git
cd iamx

# Install dependencies
pip install -e .

# Or install directly from PyPI (when published)
pip install iamx
```

## 📖 Quick Start

### CLI Usage

```bash
# Analyze a single policy file
iamx analyze policy.json

# Analyze multiple policies
iamx analyze policies/*.json

# Generate detailed report
iamx analyze policy.json --output report.md --format markdown

# Set severity threshold for CI
iamx analyze policy.json --fail-on high
```

### Web UI

```bash
# Start the local web interface
iamx web

# Open http://localhost:8080 in your browser
```

### GitHub Actions Integration

```yaml
name: IAM Policy Review
on: [pull_request]
jobs:
  iamx:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run iamx
        uses: yourusername/iamx-action@v1
        with:
          path: 'policies/'
          fail-on: 'high'
          output: 'iamx-report.md'
```

## 📊 Example Output

```
🔍 Analyzing IAM Policy: admin-policy.json

❌ CRITICAL: Overly Permissive Actions
   The policy grants '*' permissions on all resources for ec2:* actions.
   This allows full EC2 control including instance termination and data access.
   
   Recommendation: Replace with specific actions like:
   - ec2:DescribeInstances
   - ec2:StartInstances
   - ec2:StopInstances

⚠️  HIGH: Missing Resource Restrictions
   The policy allows s3:GetObject on any S3 bucket without restrictions.
   This could expose sensitive data across all buckets.
   
   Recommendation: Add resource ARN restrictions:
   "Resource": "arn:aws:s3:::my-bucket/*"

✅ LOW: Consider Adding Conditions
   The policy doesn't require MFA for administrative actions.
   
   Recommendation: Add MFA condition for sensitive operations.
```

## 🏗️ Architecture

```
iamx/
├── core/           # Core analysis engine
├── cli/            # Command-line interface
├── web/            # Web UI components
├── rules/          # Policy analysis rules
├── reports/        # Report generators
├── github/         # GitHub Actions integration
└── tests/          # Test suite
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone and setup development environment
git clone https://github.com/yourusername/iamx.git
cd iamx
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black .
flake8 .
```

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- Built with modern Python tooling and best practices
- Designed for the security and DevOps community
- Inspired by the need for better IAM policy analysis tools
