cloudwire 0.1.0__tar.gz

cloudwire-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: cloudwire
+Version: 0.1.0
+Summary: Scan and visualize your AWS infrastructure as an interactive graph
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hisingh_gwre/cloudwire
+Project-URL: Issues, https://github.com/hisingh_gwre/cloudwire/issues
+Keywords: aws,cloud,visualization,graph,infrastructure
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+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
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: boto3>=1.37
+Requires-Dist: botocore>=1.37
+Requires-Dist: networkx>=3.4
+Requires-Dist: pydantic>=2.11
+Requires-Dist: click>=8.1
+
+# cloudwire
+
+Scan your AWS account and visualize resource dependencies as an interactive graph — directly in your browser, running entirely on your local machine.
+
+No data leaves your system. AWS credentials never leave your terminal. The graph is built locally using your existing credential chain (`~/.aws/credentials`, `aws sso login`, `saml2aws`, `aws-vault` — all work out of the box).
+
+---
+
+## Install
+
+```bash
+pip install cloudwire
+cloudwire
+```
+
+That's it. The browser opens automatically at `http://localhost:8080`.
+
+> **Requirements:** Python 3.9+ and valid AWS credentials configured locally.
+
+---
+
+## What it looks like
+
+- Dark hacker-aesthetic graph canvas
+- Nodes represent AWS resources — Lambda functions, SQS queues, API Gateways, RDS instances, S3 buckets, and more
+- Edges represent relationships and data flow between resources
+- Click any node to inspect its attributes and connected resources
+- Search, filter by service, highlight upstream/downstream blast radius
+
+---
+
+## Supported services
+
+| Service | Scanner |
+|---------|---------|
+| API Gateway | Dedicated |
+| Lambda | Dedicated (with state) |
+| SQS | Dedicated |
+| SNS | Dedicated |
+| EventBridge | Dedicated |
+| DynamoDB | Dedicated (with state) |
+| EC2 | Dedicated (with state) |
+| ECS | Dedicated |
+| S3 | Dedicated |
+| RDS | Dedicated (with state) |
+| Step Functions | Dedicated |
+| Kinesis | Dedicated |
+| IAM | Dedicated |
+| Cognito | Dedicated |
+| CloudFront | Dedicated (with state) |
+| ElastiCache | Dedicated (with state) |
+| Glue | Dedicated |
+| AppSync | Dedicated |
+| Everything else | Generic (tagged resources only) |
+
+---
+
+## Project structure
+
+```
+cloudwire/                        # Python package (the distributable unit)
+├── __init__.py                 # Package version
+├── cli.py                      # `cloudwire` CLI entry point (click)
+├── static/                     # Built React app (populated by `make build`)
+│   ├── index.html
+│   └── assets/
+└── app/                        # FastAPI backend
+    ├── main.py                 # App factory, API routes (/api/*), static serving
+    ├── models.py               # Pydantic request/response models
+    ├── scanner.py              # boto3 AWS scanner — one function per service
+    ├── scan_jobs.py            # Async job store with progress tracking
+    └── graph_store.py          # networkx graph with thread-safe mutations
+
+frontend/                       # React + Vite source (compiled into cloudwire/static/)
+├── src/
+│   ├── pages/CloudWirePage.jsx # Main page — orchestrates all state
+│   ├── components/
+│   │   ├── graph/              # GraphCanvas, GraphNode, GraphEdge, Minimap, Legend
+│   │   └── layout/             # TopBar, ServiceSidebar, InspectorPanel
+│   ├── hooks/
+│   │   ├── useScanPolling.js   # Scan lifecycle, polling, graph data state
+│   │   └── useGraphViewport.js # Pan/zoom viewport state
+│   ├── lib/
+│   │   ├── graphTransforms.js  # Layout algorithms (circular, flow, swimlane)
+│   │   ├── serviceVisuals.jsx  # Service icon + color map
+│   │   └── awsRegions.js       # AWS region list
+│   └── styles/graph.css        # All UI styles
+├── vite.config.js              # base: "./", outDir: ../cloudwire/static, dev proxy
+└── package.json
+
+.github/workflows/publish.yml   # CI: build + publish to PyPI on version tag push
+pyproject.toml                  # Package metadata, dependencies, entry point
+Makefile                        # make build / make dev / make clean
+.python-version                 # Pins Python 3.11 for consistent builds
+```
+
+---
+
+## Contributing
+
+### Prerequisites
+
+- Python 3.9+ (3.11 recommended)
+- Node.js 18+
+- AWS credentials configured (any method)
+
+### Set up the dev environment
+
+```bash
+git clone https://github.com/hisingh_gwre/cloudwire
+cd cloudwire
+
+# Python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Frontend
+cd frontend && npm install
+```
+
+### Run in development mode
+
+```bash
+make dev
+```
+
+This starts the FastAPI backend on `:8000` (with `--reload`) and the Vite dev server on `:5173` concurrently. The Vite dev server proxies all `/api/*` requests to the backend — no CORS config needed.
+
+### Making changes
+
+| Area | Where to edit |
+|------|--------------|
+| Add a new AWS service scanner | `cloudwire/app/scanner.py` → add a `_scan_<service>` method and register it in `self.service_scanners` |
+| Change graph layout | `frontend/src/lib/graphTransforms.js` |
+| Add a new UI component | `frontend/src/components/` |
+| Change API routes | `cloudwire/app/main.py` — all routes are under the `/api` prefix |
+| Change CLI options | `cloudwire/cli.py` |
+
+### Before opening a PR
+
+- Run a scan against a real (or mocked) AWS account and confirm the graph renders
+- Make sure `make build` completes without errors
+- Keep PRs focused — one feature or fix per PR
+
+### Code style
+
+- Python: standard library imports first, then third-party, then local. No formatter enforced yet.
+- JavaScript: no linter enforced yet. Match the style of the surrounding file.
+
+---
+
+## Links
+
+- [Usage & setup guide](docs/USAGE.md)
+- [Release guide for maintainers](docs/RELEASING.md)

cloudwire-0.1.0/README.md

@@ -0,0 +1,156 @@
+# cloudwire
+
+Scan your AWS account and visualize resource dependencies as an interactive graph — directly in your browser, running entirely on your local machine.
+
+No data leaves your system. AWS credentials never leave your terminal. The graph is built locally using your existing credential chain (`~/.aws/credentials`, `aws sso login`, `saml2aws`, `aws-vault` — all work out of the box).
+
+---
+
+## Install
+
+```bash
+pip install cloudwire
+cloudwire
+```
+
+That's it. The browser opens automatically at `http://localhost:8080`.
+
+> **Requirements:** Python 3.9+ and valid AWS credentials configured locally.
+
+---
+
+## What it looks like
+
+- Dark hacker-aesthetic graph canvas
+- Nodes represent AWS resources — Lambda functions, SQS queues, API Gateways, RDS instances, S3 buckets, and more
+- Edges represent relationships and data flow between resources
+- Click any node to inspect its attributes and connected resources
+- Search, filter by service, highlight upstream/downstream blast radius
+
+---
+
+## Supported services
+
+| Service | Scanner |
+|---------|---------|
+| API Gateway | Dedicated |
+| Lambda | Dedicated (with state) |
+| SQS | Dedicated |
+| SNS | Dedicated |
+| EventBridge | Dedicated |
+| DynamoDB | Dedicated (with state) |
+| EC2 | Dedicated (with state) |
+| ECS | Dedicated |
+| S3 | Dedicated |
+| RDS | Dedicated (with state) |
+| Step Functions | Dedicated |
+| Kinesis | Dedicated |
+| IAM | Dedicated |
+| Cognito | Dedicated |
+| CloudFront | Dedicated (with state) |
+| ElastiCache | Dedicated (with state) |
+| Glue | Dedicated |
+| AppSync | Dedicated |
+| Everything else | Generic (tagged resources only) |
+
+---
+
+## Project structure
+
+```
+cloudwire/                        # Python package (the distributable unit)
+├── __init__.py                 # Package version
+├── cli.py                      # `cloudwire` CLI entry point (click)
+├── static/                     # Built React app (populated by `make build`)
+│   ├── index.html
+│   └── assets/
+└── app/                        # FastAPI backend
+    ├── main.py                 # App factory, API routes (/api/*), static serving
+    ├── models.py               # Pydantic request/response models
+    ├── scanner.py              # boto3 AWS scanner — one function per service
+    ├── scan_jobs.py            # Async job store with progress tracking
+    └── graph_store.py          # networkx graph with thread-safe mutations
+
+frontend/                       # React + Vite source (compiled into cloudwire/static/)
+├── src/
+│   ├── pages/CloudWirePage.jsx # Main page — orchestrates all state
+│   ├── components/
+│   │   ├── graph/              # GraphCanvas, GraphNode, GraphEdge, Minimap, Legend
+│   │   └── layout/             # TopBar, ServiceSidebar, InspectorPanel
+│   ├── hooks/
+│   │   ├── useScanPolling.js   # Scan lifecycle, polling, graph data state
+│   │   └── useGraphViewport.js # Pan/zoom viewport state
+│   ├── lib/
+│   │   ├── graphTransforms.js  # Layout algorithms (circular, flow, swimlane)
+│   │   ├── serviceVisuals.jsx  # Service icon + color map
+│   │   └── awsRegions.js       # AWS region list
+│   └── styles/graph.css        # All UI styles
+├── vite.config.js              # base: "./", outDir: ../cloudwire/static, dev proxy
+└── package.json
+
+.github/workflows/publish.yml   # CI: build + publish to PyPI on version tag push
+pyproject.toml                  # Package metadata, dependencies, entry point
+Makefile                        # make build / make dev / make clean
+.python-version                 # Pins Python 3.11 for consistent builds
+```
+
+---
+
+## Contributing
+
+### Prerequisites
+
+- Python 3.9+ (3.11 recommended)
+- Node.js 18+
+- AWS credentials configured (any method)
+
+### Set up the dev environment
+
+```bash
+git clone https://github.com/hisingh_gwre/cloudwire
+cd cloudwire
+
+# Python
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Frontend
+cd frontend && npm install
+```
+
+### Run in development mode
+
+```bash
+make dev
+```
+
+This starts the FastAPI backend on `:8000` (with `--reload`) and the Vite dev server on `:5173` concurrently. The Vite dev server proxies all `/api/*` requests to the backend — no CORS config needed.
+
+### Making changes
+
+| Area | Where to edit |
+|------|--------------|
+| Add a new AWS service scanner | `cloudwire/app/scanner.py` → add a `_scan_<service>` method and register it in `self.service_scanners` |
+| Change graph layout | `frontend/src/lib/graphTransforms.js` |
+| Add a new UI component | `frontend/src/components/` |
+| Change API routes | `cloudwire/app/main.py` — all routes are under the `/api` prefix |
+| Change CLI options | `cloudwire/cli.py` |
+
+### Before opening a PR
+
+- Run a scan against a real (or mocked) AWS account and confirm the graph renders
+- Make sure `make build` completes without errors
+- Keep PRs focused — one feature or fix per PR
+
+### Code style
+
+- Python: standard library imports first, then third-party, then local. No formatter enforced yet.
+- JavaScript: no linter enforced yet. Match the style of the surrounding file.
+
+---
+
+## Links
+
+- [Usage & setup guide](docs/USAGE.md)
+- [Release guide for maintainers](docs/RELEASING.md)

cloudwire-0.1.0/cloudwire/__init__.py

@@ -0,0 +1,3 @@
+"""CloudWire — scan and visualize your AWS infrastructure."""
+
+__version__ = "0.1.0"

cloudwire-0.1.0/cloudwire/app/__init__.py

@@ -0,0 +1 @@
+"""CloudWire backend package."""

cloudwire-0.1.0/cloudwire/app/graph_store.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from threading import Lock
+from typing import Any, Dict, List
+
+import networkx as nx
+
+
+class GraphStore:
+    def __init__(self) -> None:
+        self.graph = nx.DiGraph()
+        self.metadata: Dict[str, Any] = {
+            "last_scan_at": None,
+            "region": None,
+            "scanned_services": [],
+            "warnings": [],
+        }
+        self._lock = Lock()
+
+    def reset(self, *, region: str, services: List[str]) -> None:
+        with self._lock:
+            self.graph = nx.DiGraph()
+            self.metadata = {
+                "last_scan_at": datetime.now(timezone.utc).isoformat(),
+                "region": region,
+                "scanned_services": services,
+                "warnings": [],
+            }
+
+    def add_warning(self, warning: str) -> None:
+        with self._lock:
+            self.metadata.setdefault("warnings", []).append(warning)
+
+    def update_metadata(self, **kwargs: Any) -> None:
+        with self._lock:
+            self.metadata.update(kwargs)
+
+    def add_node(self, node_id: str, **attrs: Any) -> None:
+        with self._lock:
+            current = self.graph.nodes[node_id] if self.graph.has_node(node_id) else {}
+            merged = {**current, **attrs}
+            merged["id"] = node_id
+            self.graph.add_node(node_id, **merged)
+
+    def add_edge(self, source: str, target: str, **attrs: Any) -> None:
+        with self._lock:
+            current = self.graph.get_edge_data(source, target, default={})
+            merged = {**current, **attrs}
+            self.graph.add_edge(source, target, **merged)
+
+    def _serialize_node(self, node_id: str, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        payload = {"id": node_id}
+        payload.update(attrs)
+        return payload
+
+    def _serialize_edge(self, source: str, target: str, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        payload = {"id": f"{source}__{target}", "source": source, "target": target}
+        payload.update(attrs)
+        return payload
+
+    def get_graph_payload(self) -> Dict[str, Any]:
+        with self._lock:
+            nodes = [self._serialize_node(node_id, attrs) for node_id, attrs in self.graph.nodes(data=True)]
+            edges = [
+                self._serialize_edge(source, target, attrs)
+                for source, target, attrs in self.graph.edges(data=True)
+            ]
+            metadata = dict(self.metadata)
+            metadata["node_count"] = len(nodes)
+            metadata["edge_count"] = len(edges)
+            return {"nodes": nodes, "edges": edges, "metadata": metadata}
+
+    def get_resource_payload(self, resource_id: str) -> Dict[str, Any]:
+        with self._lock:
+            if not self.graph.has_node(resource_id):
+                raise KeyError(resource_id)
+
+            node = self._serialize_node(resource_id, dict(self.graph.nodes[resource_id]))
+            incoming = [
+                self._serialize_edge(source, resource_id, dict(attrs))
+                for source, _, attrs in self.graph.in_edges(resource_id, data=True)
+            ]
+            outgoing = [
+                self._serialize_edge(resource_id, target, dict(attrs))
+                for _, target, attrs in self.graph.out_edges(resource_id, data=True)
+            ]
+            return {"node": node, "incoming": incoming, "outgoing": outgoing}