Metadata-Version: 2.4
Name: sudiviz
Version: 0.4.0
Summary: Sufficient visibility into cloud infrastructure failures — live AWS topology + Terraform drift in one CLI.
Author: Sudipto Ghosh
License: MIT
Project-URL: Homepage, https://github.com/pydevsg/sudiviz
Project-URL: Issues, https://github.com/pydevsg/sudiviz/issues
Keywords: aws,terraform,observability,networking,diagnose,alb,vpc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.15.0
Requires-Dist: boto3>=1.35.0
Requires-Dist: botocore>=1.35.0
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: graphviz>=0.20
Requires-Dist: jinja2>=3.1
Provides-Extra: tui
Requires-Dist: textual>=0.50.0; extra == "tui"
Provides-Extra: web
Requires-Dist: fastapi>=0.115.0; extra == "web"
Requires-Dist: uvicorn>=0.30.0; extra == "web"
Requires-Dist: websockets>=13.0; extra == "web"
Provides-Extra: diagrams
Requires-Dist: diagrams>=0.23; extra == "diagrams"
Provides-Extra: terraform
Requires-Dist: python-terraform>=0.10; extra == "terraform"
Provides-Extra: all
Requires-Dist: textual>=0.50.0; extra == "all"
Requires-Dist: fastapi>=0.115.0; extra == "all"
Requires-Dist: uvicorn>=0.30.0; extra == "all"
Requires-Dist: websockets>=13.0; extra == "all"
Requires-Dist: diagrams>=0.23; extra == "all"
Requires-Dist: python-terraform>=0.10; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# 🔬 sudiviz

> *X-ray vision for your cloud infrastructure*

**sudiviz** visualizes your live AWS infrastructure as an interactive graph. Auto-detects misconfigurations, unhealthy targets, and orphan resources — then fixes them with one command.

🚀 Zero AI tokens | 💸 Zero cost | 🐍 Pure Python

![Web Graph](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_dark_mode.png)

---

## 📦 Quick Start

```bash
pip install 'sudiviz[all]'

# Diagnose your infrastructure
sudiviz diagnose

# Interactive web visualization
sudiviz graph --output web --open

# Auto-fix issues
sudiviz fix --apply
```

> **Auth:** Uses standard boto3 credentials (`~/.aws/credentials`, env vars, SSO, or instance profile)

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| **Live Topology** | Real-time graph of ALB → Target Groups → EC2 → Security Groups |
| **Health Detection** | Unhealthy targets, failing health checks, orphan resources |
| **Auto-Fix** | One-click remediation with `sudiviz fix --apply` |
| **Traffic Animation** | Visualize request flow with animated pulses |
| **Health Heatmaps** | Color-code infrastructure by health status |
| **Dark/Light Mode** | Toggle theme in web UI |
| **Terraform Drift** | Compare live AWS vs Terraform state |
| **Multi-Service** | ALB, EC2, ECS, EKS, RDS, Lambda, S3, Security Groups |

---

## 🎨 Visualization Modes

### Terminal
```bash
sudiviz diagnose --region us-east-1
```

### TUI (Interactive Terminal)
```bash
sudiviz tui
```

### Web (Cytoscape.js)
```bash
sudiviz graph --output web --port 8000 --open
```

### PNG Export
```bash
sudiviz graph --output png --file topology.png
```

---

## 🔧 Auto-Fix

```bash
sudiviz fix                    # Preview fixes (dry-run)
sudiviz fix --apply            # Apply all fixes
sudiviz fix 1 --apply          # Apply specific fix
sudiviz fix --apply --force    # Include destructive operations
```

**Supported fixes:**
- Security group missing ingress rules
- S3 public access / encryption
- RDS public accessibility
- Orphan target groups (with `--force`)
- Unused security groups (with `--force`)

---

## 🔄 Terraform Drift

```bash
terraform show -json > tfstate.json
sudiviz drift --tfstate tfstate.json
```

---

## 📊 CI Integration

```bash
# Fail CI on critical issues
sudiviz diagnose --json | jq '.diagnosis.fixes[] | select(.severity=="critical")'

# Drift detection gate
sudiviz drift --tfstate tfstate.json --json
```

| Exit Code | Meaning |
|-----------|---------|
| `0` | No issues |
| `1` | Drift detected |
| `2` | Critical issues found |

---

## 📸 More Screenshots

<details>
<summary>Click to expand</summary>

### Terminal TUI
![TUI](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_tui.png)

### Diagnose Output
![Diagnose](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_diagnose_before_lb.png)

### Auto-Fix Preview
![Fix](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_fix.png)

### Traffic Flow Animation
![Traffic](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_healthy_traffic_flow.png)

### Health Heatmap
![Heatmap](https://raw.githubusercontent.com/pydevsg/sudiviz/main/docs/images/sudiviz_health_status.png)

</details>

---

## 🆚 Comparison

| Feature | sudiviz | Hava.io | Cloudcraft |
|---------|:-------:|:-------:|:----------:|
| Live data | ✅ | ❌ | ❌ |
| Auto-fix | ✅ | ❌ | ❌ |
| Traffic animation | ✅ | ❌ | ❌ |
| Health heatmaps | ✅ | ❌ | ❌ |
| Terraform drift | ✅ | ❌ | ❌ |
| Orphan detection | ✅ | ❌ | ❌ |
| Free & open source | ✅ MIT | $29/mo | $49/mo |

---

## 🔐 IAM Permissions

**Read-only** (`sudiviz diagnose`):
- `ReadOnlyAccess` AWS managed policy

**Write** (`sudiviz fix --apply`):
- `AmazonEC2FullAccess`
- `ElasticLoadBalancingFullAccess`
- `AmazonS3FullAccess`
- `AmazonRDSFullAccess`

---

## 📖 Documentation

<details>
<summary>AWS Services Discovered</summary>

| Service | What's collected |
|---------|-----------------|
| **ALB / NLB** | Load balancers, listeners, rules |
| **Target Groups** | Health status per target |
| **EC2** | State, IPs, security groups |
| **Security Groups** | Ingress/egress rules |
| **ECS** | Clusters, services, task counts |
| **EKS** | Clusters, node groups |
| **RDS** | Instances, encryption, public access |
| **Lambda** | Functions, VPC config |
| **S3** | Buckets, encryption, public access |

</details>

<details>
<summary>Diagnostic Rules</summary>

| Check | Severity |
|-------|----------|
| Unhealthy targets | critical |
| SG missing port from ALB | critical |
| S3 public access open | critical |
| RDS publicly accessible | warning |
| Storage not encrypted | warning |
| Orphan target group | warning |
| Unused security group | info |

</details>

<details>
<summary>Architecture</summary>

```
sudiviz/
├── cli.py           # Typer commands
├── tui.py           # Textual TUI
├── web.py           # FastAPI + WebSocket
├── discovery/       # AWS discovery (boto3)
├── graph/           # NetworkX + analyzers
├── remediation/     # Auto-fix engine
└── web_templates/   # Cytoscape.js UI
```

</details>

---

## 📝 License

MIT — see [LICENSE](LICENSE)

---

<p align="center">
  <b>Built by <a href="https://github.com/pydevsg">@pydevsg</a></b>
</p>
