cloudmap 1.0.0rc1__tar.gz

cloudmap-1.0.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.9 is the floor the README promises; 3.13 catches what is about to break.
+        python-version: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest
+      # The suite includes tests/test_fixtures_safe.py, which fails if a fixture
+      # ever carries a credential or an unscrubbed GUID. That guard is the reason
+      # CI runs on pull requests too.

cloudmap-1.0.0rc1/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cloudmap
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cloudmap-1.0.0rc1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# generated diagram output
+*.blast.drawio
+*.mmd
+out/
+
+# never commit anything pulled from a live cloud
+live/
+*.live.json
+.team/

cloudmap-1.0.0rc1/ARCHITECTURE.md

@@ -0,0 +1,158 @@
+# Architecture
+
+> Written in English to match the rest of the repo (README, code, comments).
+> `file.py:NN` references are indicative - they drift as the code moves. Trust the
+> function and file names; grep for the symbol rather than jumping to the line.
+
+## Overview
+
+cloudmap is a local-first CLI (Python 3.9+, zero dependencies — `pyproject.toml:14`)
+that takes the **name of one Azure resource** and produces its full **dependency
+graph (blast radius)** as an **editable draw.io diagram** (plus Mermaid and JSON).
+It is a clean four-stage pipeline: **ingest** (fixture or live `az`) → **extract**
+(properties / hostnames / secrets → typed edges) → **graph** (blast-radius BFS with
+hub boundaries) → **render**. The core value is that Azure Resource Graph has no
+"dependencies" table, so `extract/extractors.py` infers dependencies and
+**verifies** each one — anything referenced but not verified becomes an explicit
+`external` node instead of being silently dropped.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    CLI["__main__.py → cli.main()<br/>argparse: trace"] --> TRACE["_cmd_trace (cli.py:49)"]
+
+    TRACE -->|"--from"| FIX["ingest/fixture.py<br/>load_fixture()"]
+    TRACE -->|"--live"| AZ["ingest/azure.py<br/>query_live() :106"]
+
+    AZ --> GUARD["_guard() :50<br/>ALLOW_SUB pin"]
+    AZ --> SUBS["_target_subscriptions() :74<br/>tenant-wide"]
+    AZ --> PAGE["_graph_paged() :88<br/>type-filtered KQL, skip_token"]
+
+    FIX --> BUILD["graph.build_graph() :34"]
+    AZ --> BUILD
+    BUILD --> EXTRACT["extract_edges() :182<br/>Resolver + typed edges"]
+
+    TRACE --> ENRICH["(live, web app)<br/>enrich_webapp() azure.py:144<br/>show+appsettings+RBAC+diag<br/>+ secret resolution :113"]
+    ENRICH --> EXTERNAL["seed_external_dependencies() :279<br/>never-drop → external nodes"]
+
+    BUILD --> BLAST["blast_radius() graph.py<br/>BFS with direction consistency"]
+    EXTERNAL --> BLAST
+    BLAST --> R1["render/drawio.py :44<br/>native Azure icons"]
+    BLAST --> R2["render/mermaid.py"]
+    BLAST --> R3["render/json_out.py"]
+    BLAST --> R4["render/html.py<br/>self-contained viewer"]
+
+    CLI --> ASK["_cmd_ask (cli.py)<br/>argparse: ask"]
+    R3 -.->|"saved map, reloaded"| LOAD["adapters/load_graph()<br/>auto-detect + keep meta"]
+    ASK --> LOAD
+    LOAD --> INTENT["ask/intent.py<br/>rules first, model only as<br/>validated fallback (--llm)"]
+    INTENT --> Q["ask/queries.py<br/>impact / depends / paths /<br/>shared / guesses / summary<br/>COMPUTED from edges"]
+    Q --> NARR["ask/narration.py (--explain)<br/>prose from the computed facts"]
+    INTENT -.-> LM["local_model.py<br/>the only model call, localhost"]
+    NARR -.-> LM
+```
+
+## File Map
+
+| File | Role | Why it's built this way |
+|---|---|---|
+| `cloudmap/model.py` | `Node`/`Edge`/`Graph` dataclasses | Provider-neutral core. The `external`+`note` fields (`model.py:31-32`) exist for the "never silent drop" principle — a referenced-but-unverified target still needs a place in the model. |
+| `cloudmap/ingest/fixture.py` | Load synthetic/captured JSON | Accepts both a bare list and `{"data":[...]}` (`:11-13`) so the same file works as a fixture and as captured `az graph` output. |
+| `cloudmap/ingest/azure.py` | Live `az` ingest + enrichment | The most sensitive file, so it concentrates every guard (`HARD_DENY_HINTS` :20, `_guard` :50). Kept separate from extraction so the dependency logic stays pure and testable without Azure. |
+| `cloudmap/extract/extractors.py` | **The heart**: properties/hosts/secrets → edges | The project's IP. `Resolver` (:97) builds indexes (by_id/by_host/by_principal/kv_by_name/…); `_DOMAIN_KIND` (:27) maps service domains to edge kinds. |
+| `cloudmap/graph.py` | Build graph + blast-radius BFS + the high-level collapse | Direction consistency in `blast_radius` (never reverse once you have stepped) is why a shared VNet/ASP does not pull in unrelated apps — a central design choice. `collapse_high_level` folds instances into one box per type and must carry their kinds AND evidence across, or the default view would show unfalsifiable arrows. |
+| `cloudmap/render/drawio.py` | `.drawio` with Azure2 icons | `AZURE_ICON` (:14) = verified paths; falls back to a box, external nodes render dashed (`:64`) so an icon is never broken. |
+| `cloudmap/render/{mermaid,json_out}.py` | Secondary outputs | Quick preview + machine-readable inventory. |
+| `cloudmap/ask/queries.py` | **The Ask layer's heart**: the six queries, each computed by traversal | An answer must be auditable, so it is derived from edges, never generated. `_trust()` grades a whole path by its weakest hop, and distinguishes *passing through* an unverified node (whole finding becomes a guess) from *ending* at one (the reference is proven; the target is flagged). |
+| `cloudmap/ask/intent.py` | Question → one query | Rules first so the common phrasings need no model at all (including the "rotate / restart / decommission" verbs). The model is a fallback that may only name a query from a fixed list and a resource, both validated against the graph — it routes, it never answers. |
+| `cloudmap/ask/narration.py` | Optional prose (`--explain`) | Handed the computed facts only, and printed *below* them, so drifting prose is visibly a narration disagreeing with the facts, not a wrong answer. |
+| `cloudmap/local_model.py` | The single outbound model call | One module = one auditable promise: the call goes to localhost (ollama) and failure returns an empty value, because cloudmap must be fully useful with no model installed. |
+| `cloudmap/cli.py` | Orchestration + argparse | `_cmd_trace` wires the trace stages together (live enrichment + external merge live here); `_cmd_ask` loads a saved map and prints the computed answer, proof lines included. |
+| `fixtures/contoso.json` | 100% synthetic estate | Fixture-first development → zero cloud contact in tests. |
+| `tests/test_graph.py` | 5 unit tests | Lock in the hub-boundary behaviour + edge-kinds against the fixture. |
+| `.gitignore` | Safety | `live/`, `*.blast.drawio` ignored → nothing from a real cloud ends up in the repo. |
+
+## Execution Flow
+
+**Fixture path** (`cloudmap trace contoso-web --from fixtures/contoso.json`):
+
+1. `__main__.py:6` → `sys.exit(main())`.
+2. `cli.py:15` `main()` — argparse defines the `trace` subcommand and flags
+   (`--from/--live/--resolve-secrets/--single-sub/--direction`).
+3. `cli.py:49` `_cmd_trace` — fixture branch → `load_fixture()` (`fixture.py:9`)
+   returns a list of resource dicts.
+4. `graph.py:34` `build_graph()` → builds `Node`s and calls `extract_edges()`.
+5. `extract_edges()` — constructs a `Resolver` and, per node, derives edges:
+   `serverFarmId`→hosted-on, `virtualNetworkSubnetId`→vnet-integration, private
+   endpoints, role assignments, and for config-bearing workloads →
+   `_config_edges()` matching hostnames/vault refs/IK. Web apps add the
+   `linuxFxVersion` image; container apps add `environmentId`, `registries`,
+   `secrets[].keyVaultUrl` and `template.containers[].image`.
+6. `find_seeds()` — exact name match, else substring; >1 → ambiguity exit.
+7. `blast_radius()` — BFS from the seed in both directions, but **never reversing**
+   once it has stepped one way. That single rule is what stops a shared plan or
+   VNet from bridging the seed into unrelated apps.
+8. `to_drawio()` — layered layout by hop-distance, Azure icon or box/dashed;
+   `_print_summary` prints the edges, plus any blind spot the scan left.
+
+**Live path** (`--live --allow-live --resolve-secrets`) — additionally in `_cmd_trace`:
+
+9. `query_live()` → `_guard()` (`CLOUDMAP_ALLOW_SUBSCRIPTION` ==
+   active sub) → `_target_subscriptions()` (all Enabled) → `_graph_paged()`
+   (type-filtered KQL, `skip_token` paging, warns when it hits the cap).
+10. `_enrich_live()` (`cli.py`) picks which web apps to deep-enrich via
+    `_enrichment_targets()`, then `enrich_webapps()` runs them concurrently:
+    `az webapp show` (identity/vnet/image), appsettings/connection-strings; with
+    `--resolve-secrets`, `_maybe_resolve()` → `_resolve_secret()` substitutes
+    `@Microsoft.KeyVault(...)` **in-memory**; + role assignments + diagnostics.
+11. Rebuild the graph, then `seed_external_dependencies()` adds dashed external
+    nodes for anything the seed references but the scan never resolved, plus
+    diagnostics edges, then `_dedupe`. Whatever was *not* enriched is recorded as
+    a blind spot in `meta` so the artifact — and every `ask` answer drawn from it —
+    repeats it.
+
+## Design Decisions
+
+- **extract vs ingest separation** (`extractors.py` knows nothing about `az`). All
+  dependency logic is pure Python over dicts, so the 5 tests run without Azure.
+- **Direction consistency** (`blast_radius`). Real-world testing showed shared ASP/VNet
+  connect dozens of unrelated apps. The rule "from the seed go both ways, but never
+  reverse afterwards" solves it without a list of which types count as hubs. The most
+  opinionated part, and correctly a single line.
+- **Enrichment is scoped, and the gap is declared** (`_enrichment_targets`). Config-level
+  edges only exist for apps that were deep-enriched, so enriching just the seed makes
+  the graph asymmetric. `auto` enriches every app when the seed is shared infrastructure
+  (the only way to learn its dependents) and just the seed when the seed is itself an
+  app. Whatever is skipped becomes a `blind_spot` in `meta` — an empty upward answer
+  must never be mistaken for "nothing depends on this".
+- **Scrub preserves structure, not identity** (`scrub.py`). The substitution is global
+  and consistent so a reference and its target stay correlated; `tests/test_scrub.py`
+  asserts the graph shape is byte-identical before and after, which is what makes a
+  committed real capture worth anything.
+- **Never silent drop** (`extractors.py:279` + `model.py:31`). `extract_edges` drops
+  unresolved targets (noise at tenant scale), but the seed-scoped pass resurfaces them
+  as external — a clean separation of responsibility across the two functions.
+- **Security-by-design in ingest**: `_guard()` (`azure.py:50`) demands an explicit env
+  var equal to the exact active sub id. Secrets are resolved in-memory only (`_resolve_secret` :113) and `.gitignore`
+  keeps `live/` out of the repo.
+- **Verified icon paths** (`drawio.py:14`) — image shapes over mxgraph stencils, likely
+  because the azure2 SVGs ship inside draw.io (the repo ships no icon assets).
+
+## Open Questions / Risks
+
+- **`az graph --skip-token`** (`azure.py:98`): works here but depends on the
+  resource-graph extension version; another version may require a `--skip` fallback.
+- **Deep-enrich only for `microsoft.web/sites`**: AKS or SQL as a seed still get ARM
+  topology only. Container apps need no enrichment (Resource Graph returns their
+  template), but an AKS workload's real dependencies live in Kubernetes manifests,
+  which nothing here reads.
+- **Cost of `--enrich all`**: one `az` round-trip per app, eight at a time. On a
+  tenant with hundreds of apps the default `auto` keeps this off the common path, but
+  tracing a shared Key Vault in a large tenant is genuinely slow.
+- **No icons for Container Apps**: `AZURE_ICON` / `AZURE_SVG` entries are only added
+  once the asset path is verified against the azure2 set, so container apps currently
+  render as a labelled box rather than a wrong icon.
+- **Secret resolution reachability**: `_resolve_secret` calls `az keyvault secret show`;
+  if the vault is behind a private endpoint without connectivity it fails silently
+  (try/except) and the data-plane dependency shows as external rather than resolved.

cloudmap-1.0.0rc1/FORMAT.md

@@ -0,0 +1,89 @@
+# The neutral graph format
+
+cloudmap's core does not know about any specific cloud. Everything flows through
+one **neutral** shape: `Node` / `Edge` / `Graph` (see `cloudmap/model.py`). An
+*adapter* turns a raw cloud export into this shape; every renderer reads it.
+
+```
+raw export  --(adapter)-->  neutral Graph  --(renderer)-->  drawio | mermaid | json
+```
+
+Adding a cloud = adding one adapter. That is the whole anti-vendor-lock story:
+the value (graph, blast-radius, trust, AI) lives in the cloud-agnostic core.
+
+## Inputs cloudmap can read (`--from`, auto-detected)
+
+The loader (`cloudmap/adapters/load_graph`) sniffs the file - no flags:
+
+1. **Raw Azure Resource Graph** - a JSON list of resources, or the `az`
+   shape `{"data": [ ... ]}`. Each item has `id`, `type`, `properties`, etc.
+   Handled by the **Azure adapter**, which runs the extraction rules.
+2. **A neutral cloudmap graph** - a file cloudmap itself wrote with `--json`
+   (has top-level `nodes` and `edges`). Loaded straight back into a `Graph`, no
+   re-extraction. This is what makes a saved map re-openable (the viewer and
+   `cloudmap ask` build on it).
+
+`seed` and `meta` survive the round-trip too (`Graph.meta`), which is what lets a
+question answered from a saved map carry the same caveats the map itself carries -
+an incomplete artifact cannot quietly become a confident answer.
+
+## Output shape (`--json`)
+
+```jsonc
+{
+  "seed": "<node id the trace started from>",
+  "meta": {
+    "complete": true,            // false if truncated OR a live read failed
+    "truncated": false,          // scan hit the pagination cap -> missing data
+    "read_gaps": [],             // human-readable list of things we could not read
+    "external_unverified": 0,    // nodes referenced but not found in scanned scope
+    "model_edges": 0             // edges proposed by the LLM (guesses), not rules
+  },
+  "nodes": [
+    {
+      "id": "<stable id>",       // ARM id for Azure; group key at high level
+      "name": "webapp-orders-dev",
+      "type": "microsoft.web/sites",
+      "resourceGroup": "rg-orders-dev",
+      "location": "westeurope",
+      "hops": 0,                 // distance from the seed
+      "external": false,         // true = referenced but unverified (dashed box)
+      "note": ""                 // why it is external / how it was discovered
+    }
+  ],
+  "edges": [
+    {
+      "source": "<node id>",
+      "target": "<node id>",
+      "kind": "hosted-on",       // relationship label(s), "; "-joined if merged
+      "origin": "extracted",     // "extracted" = verified by a rule | "model" = LLM guess
+      "evidence": "properties.serverFarmId"   // the proof behind this edge
+    }
+  ]
+}
+```
+
+## Trust fields (the point of the format)
+
+- **`origin`** - the single most important field. `extracted` means a
+  deterministic rule found concrete proof. `model` means the local LLM proposed
+  it; renderers draw it dashed so a guess never looks like a fact. A model edge
+  can only ADD a new target - it never overrides an extracted edge.
+- **`evidence`** - *why* the edge exists (which property / setting / rule). Lets a
+  reviewer audit the map instead of trusting it.
+- **`meta.complete`** - the artifact admits when it is partial (truncated scan or
+  a read that failed for lack of permission).
+
+## The adapter contract
+
+An adapter is anything that turns raw input into a `Graph`:
+
+```python
+raw (list | dict)  ->  cloudmap.model.Graph
+```
+
+- `adapters/` — `AzureAdapter` (raw Azure Resource Graph → Graph, via the
+  extraction rules) and the neutral loader (cloudmap graph JSON → Graph).
+- The Azure specifics live in `ingest/azure.py` (live pull) and
+  `extract/extractors.py` (property rules). A future `TerraformAdapter` /
+  `AwsAdapter` slots in beside them without touching the core.

cloudmap-1.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thanasis Katsaounis
+
+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.

cloudmap-1.0.0rc1/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.5
+Name: cloudmap
+Version: 1.0.0rc1
+Summary: Trace the blast radius of your Azure resources with style.
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# cloudmap
+
+[![CI](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml/badge.svg)](https://github.com/KatsaounisThanasis/cloudmap/actions/workflows/ci.yml) [![PyPI version](https://badge.fury.io/py/cloudmap.svg)](https://badge.fury.io/py/cloudmap)
+
+
+Give it the name of one Azure resource. Get back its **full dependency graph**
+(the blast radius) as an **editable draw.io diagram with native Azure icons** -
+plus Mermaid and JSON.
+
+Azure Resource Graph has no "dependencies" table. The relationships that matter
+- what an App Service is hosted on, which Key Vault it reads, which subnet it
+integrates with, which managed identity has which role where, what a Private
+Endpoint fronts, which App Gateway routes to it - are buried inside each
+resource's `properties`. cloudmap reads them out, correlates them into one
+graph, and draws it.
+
+```
+cloudmap trace contoso-web --from fixtures/contoso.json -o contoso-web.drawio
+```
+
+```
+Seed: contoso-web (microsoft.web/sites)
+Blast radius: 9 resources (0 external/unverified), 9 dependencies
+draw.io: contoso-web.drawio
+
+  contoso-web  --hosted-on-->  App Service Plan
+  contoso-web  --vnet-integration-->  Virtual Network
+  contoso-web  --reads-secret; role: Key Vault Secrets User-->  Key Vault
+  contoso-web  --connects-to-->  SQL Server
+  contoso-web  --connects-to-->  Storage
+  contoso-web  --sends-telemetry-->  App Insights
+  App Insights  --uses-workspace-->  Log Analytics
+  App Gateway  --in-subnet-->  Virtual Network
+  App Gateway  --routes-to-->  contoso-web
+```
+
+And here is the rich dependency tree generated directly in your terminal:
+
+```text
+Blast radius: 15 resources (0 external), 14 dependencies
+╭────────────────────────────── Dependency Graph ──────────────────────────────╮
+│ 🌐 app-spa-frontend                                                          │
+│ ├── --calls--> 🌐 app-auth-service                                           │
+│ │   ├── --reads-secret--> 🔐 kv-core-prod                                    │
+│ │   └── --connects-to--> 🗄️ cosmos-auth                                      │
+│ └── --calls--> 🌐 app-api-gateway                                            │
+│     ├── --calls--> 📦 capp-payment-service                                   │
+│     │   └── --reads-secret--> 🔐 kv-payments-prod                            │
+│     ├── --calls--> 🌐 app-inventory-api                                      │
+│     │   ├── --connects-to--> 🗄️ pg-inventory-prod                            │
+│     │   └── --connects-to--> 📦 stinventoryprod                              │
+│     ├── --connects-to--> 🗄️ redis-gateway                                    │
+│     └── --calls--> 🌐 app-orders-api                                         │
+│         ├── --connects-to--> 🗄️ redis-orders                                 │
+│         ├── --connects-to--> 📦 sb-enterprise                                │
+│         └── --connects-to--> 🗄️ sql-orders-prod                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+(That is the default **high-level** view - resources grouped by type. Add
+`--level detail` to see every instance with its real name.)
+
+Open the `.drawio` file in [draw.io](https://app.diagrams.net) / the desktop app
+/ the VS Code extension and edit it like any hand-drawn diagram - or open the
+self-contained `--html` viewer straight from disk (no server, no install) and
+click a resource to focus its blast radius:
+
+
+### Interactive HTML Viewer 🎨
+The `--html` output generates a **single, self-contained HTML file** (no server, no CDN, no internet required) that includes:
+- **Dark Mode Toggle** for better readability.
+- **Color-Coded Edges** by relationship type (e.g., 🟡 *Security*, 🟢 *Data*, 🔵 *Network*).
+- **Export to SVG / PNG** buttons for high-resolution snapshots.
+- **Resource Group Filters** & Smart Search.
+- **Direct Azure Portal Links** to jump straight to the resource in your cloud.
+
+![The interactive HTML viewer: the seed at the centre, dependencies fanned out with native Azure icons, each edge carrying its relationship and proof](estate-viewer.png)
+
+
+## Why
+
+- **Live-cloud tools upload your data.** cloudmap runs locally and reads only
+  what you point it at. Nothing leaves your machine.
+- **Existing OSS is siloed** - Terraform-only or Kubernetes-only. cloudmap works
+  from Azure's own inventory (Resource Graph) and correlates across services.
+- **Impact analysis, onboarding, change reviews.** "What breaks if I touch this?"
+  in one diagram instead of ten portal blades.
+
+## Real-World Scenarios (Why you need this)
+
+### 1. The "Safe to Delete?" Scenario (FinOps / Cloud Cost Cleanup)
+A developer spots an expensive Azure SQL Database (`sql-orders-dev`) that looks orphaned in the portal. They want to delete it to save $500/month. 
+By running `cloudmap trace sql-orders-dev --direction up`, the tool deep-enriches the connection strings of all Web Apps in the subscription. The map instantly reveals that a *production* Web App is mistakenly pointing to this dev database! The engineer just avoided a catastrophic outage.
+
+### 2. The "Incident Response / Root Cause" Scenario (SRE)
+At 3:00 AM, alerts fire because `payment-api` (an AKS cluster) is failing. The team is blind.
+Running the CloudMap interactive wizard on `payment-api` generates an HTML dependency graph in 5 seconds. It shows the cluster depends on a Key Vault (`kv-pay`). Checking the vault reveals someone changed its firewall rules 10 minutes ago. Cloudmap provides the exact *Evidence* ("found in Kubernetes secret X"), identifying the root cause instantly.
+
+### 3. The "Compliance & Auditor Review" Scenario (Security)
+An auditor asks: *"Which systems have access to the Storage Account containing PII customer data?"*
+Instead of manually clicking through 50 IAM screens in the Azure Portal, you run `cloudmap trace pii-storage --direction up --csv pii-audit.csv`. In seconds, you hand the auditor a clean spreadsheet showing exactly which Web Apps and AKS clusters have Managed Identity RBAC access to the storage, complete with the exact Role Assignments as proof.
+
+## How it works
+
+1. **Ingest** - a JSON fixture (default) or live `az graph query` (opt-in, guarded).
+2. **Extract** - per-type rules turn `properties` into typed edges
+   (`hosted-on`, `reads-secret`, `private-link-to`, `role: ...`, `routes-to`, ...).
+3. **Blast radius** - walk the graph from your seed with *direction consistency*:
+   from the seed it goes both ways (what it depends on **and** what depends on
+   it), but once it steps in one direction it never reverses. That single rule
+   keeps a shared resource (App Service Plan, VNet, Key Vault) from bridging your
+   seed to unrelated apps sitting on the same thing.
+4. **Render** - draw.io (Azure icons) + Mermaid + JSON + a self-contained HTML viewer.
+5. **Ask** - query the saved map in plain language (`cloudmap ask`); the answers are
+   computed from the graph, and a local model may only route the question or narrate
+   the result.
+
+## Usage
+
+```
+cloudmap trace <name> --from <fixture.json> [options]
+
+  --level high|detail        high = architecture view grouped by type (default);
+                             one box per type, so instance names are not in the map
+                             detail = every instance with its real name
+  --direction both|down|up   both = full blast radius (default)
+                             down = only what it depends on
+                             up   = only what depends on it
+  --max-hops N               limit traversal depth
+  -o FILE                    draw.io output (default: <name>.blast.drawio)
+  --mermaid FILE             also write Mermaid
+  --json FILE                also write the graph as JSON
+  --html FILE                also write a self-contained interactive HTML viewer
+```
+
+Try it with the bundled synthetic estate:
+
+```
+cloudmap trace contoso-web --from fixtures/contoso.json --mermaid out.mmd --json out.json
+```
+
+### Ask a map questions
+
+```
+cloudmap ask <map.json> "<question>"
+
+  --explain      also narrate the answer with a LOCAL model (ollama)
+  --llm          if no built-in rule understands the phrasing, let a LOCAL model
+                 pick the query (its choice is validated against the map)
+  --max-hops N   limit traversal depth
+  --json         print the answer as JSON (for scripting)
+```
+
+Instance names only exist in a `--level detail` map; the default high-level map
+groups by type, so ask it about a group (`"what breaks if I touch Key Vault"`) or
+trace with `--level detail` first:
+
+```
+$ cloudmap trace contoso-web --from fixtures/contoso.json --level detail --json out.json
+$ cloudmap ask out.json "what breaks if I touch contoso-kv"
+Query: impact  ·  subject: contoso-kv
+2 resource(s) depend on contoso-kv - changing it can break them.
+
+  contoso-web  (Web App)  1 hop(s)
+      contoso-web --reads-secret; role: Key Vault Secrets User--> contoso-kv
+          proof: app config references host contoso-kv.vault.azure.net; Key Vault
+                 reference to vault contoso-kv; RBAC role assignment
+  contoso-agw  (App Gateway)  2 hop(s)
+      ...
+```
+
+Questions it answers: what breaks if I touch X · what does X depend on · how does
+X reach Y · what is shared in this map · what should I not trust · explain this map.
+
+**The answers are computed, not generated.** "What breaks if I touch X" is a graph
+traversal, so that is how it is answered - the numbers and names come from the
+edges. A local model is optional and can only do two things: pick which query an
+unusual phrasing meant (`--llm`, and its pick is validated against the map), or put
+the already-computed facts into prose (`--explain`). It never supplies a fact, so it
+cannot promote a guess to one. Every finding shows the hops behind it and the proof
+of each hop, and a finding that leans on a model-proposed edge is marked `[GUESS]`.
+If the map itself says it is incomplete, every answer from it repeats that warning.
+
+### Capture a real export (so the tests can be wrong)
+
+A fixture you wrote yourself can only confirm what you already believe. `capture`
+saves what Azure actually returned, scrubs it, and gives you something that can
+contradict the extractors.
+
+```
+cloudmap capture --allow-live --single-sub -o fixtures/captured_real.json
+cloudmap scrub  raw-export.json -o fixtures/captured_real.json   # for a file you already have
+```
+
+The scrub is a **global, consistent** pseudonymisation, not a field-by-field
+blanking: `kv-payments` becomes `kv-1` everywhere at once, so the app setting that
+references `kv-payments.vault.azure.net` still points at the same vault
+afterwards. What survives on purpose: service domain suffixes (the rules read them
+to decide what an edge means), built-in role GUIDs (public Azure constants) and
+private IP ranges (that is the topology). What does not: names, resource groups,
+subscription and principal GUIDs, e-mails, public IPs, and any
+password / key / SAS fragment, which is redacted rather than renamed.
+
+The mapping is never written to disk - it is the re-identification key. Counts are
+printed, the mapping is not. **A scrubber is not a proof: read the file before you
+commit it.** `--no-scrub` exists for local debugging and writes credentials to
+disk; keep those files named `*.live.json` so `.gitignore` catches them.
+
+### Live Azure (opt-in)
+
+```
+cloudmap trace my-app --live --allow-live
+
+  --single-sub          query only the active subscription (default: every enabled
+                        subscription in the tenant)
+  --enrich MODE         which web apps to deep-enrich for the dependencies that only
+                        exist in app config. auto (default) = the seed alone when the
+                        seed is a web app, every app in scope when it is not;
+                        all | seed | none
+  --resolve-secrets     read KV secret values in-memory to see through KV-backed
+                        connection strings (never printed or written)
+  --llm                 let a LOCAL model (ollama) propose extra edges, each
+                        verified against scanned resources before it is trusted
+```
+
+**Why `--enrich` matters.** A Key Vault reference or a connection string lives in an
+app's settings, which Resource Graph does not return - so that edge exists only once
+that app has been deep-enriched. Enriching only the seed would make the graph
+asymmetric: tracing an app finds the vault it reads, but tracing the vault would never
+find the app. Since "what breaks if I touch this" is usually asked about shared
+infrastructure, `auto` enriches every app in scope whenever the seed is *not* an app.
+Anything left un-enriched is reported as a **blind spot** on the map and repeated by
+every `ask` answer drawn from it, so an empty result never passes for "nothing depends
+on this".
+
+Live mode is opt-in, not sandboxed: `--allow-live` is the deliberate switch, and
+cloudmap reads whatever subscription `az` is pointed at. The read is read-only, but
+it is a read of live infrastructure, so point it on purpose. As an optional guard
+against a stale `az` context silently redirecting a scan, pin the subscription you
+mean - if set, cloudmap refuses to run against any other active subscription:
+
+```
+export CLOUDMAP_ALLOW_SUBSCRIPTION=<subscription-id>   # optional
+```
+
+If a live read fails (e.g. missing RBAC), cloudmap **reports the gap** instead of
+silently dropping edges, and warns when a scan is truncated - so you know when the
+picture is incomplete. Fixtures are always the default.
+**Do not point this at data you are not authorized to read.**
+
+## Install
+
+```
+git clone https://github.com/KatsaounisThanasis/cloudmap && cd cloudmap
+pip install -e .          # or just: python -m cloudmap trace ...
+```
+
+No third-party dependencies - Python 3.9+ standard library only.
+
+Supported today: App Service / Functions, Container Apps (+ environments), AKS,
+App Gateway, API Management, Key Vault, Storage, SQL / PostgreSQL / MySQL / Cosmos,
+Redis, Service Bus, Event Hub, Cognitive Search, Azure OpenAI, Container Registry,
+Log Analytics, App Insights, VNets, Private Endpoints and managed identities.
+
+## Roadmap
+
+- Slice 2: Terraform state ingestor + drift overlay (desired vs actual).
+- Slice 3: AKS / Kubernetes workload correlation.
+- Resource-group and application (tag-based) seeds.
+- More edge extractors and Azure icon mappings (Container Apps still render as a
+  labelled box - an icon is only added once its azure2 asset path is verified).
+
+## License
+
+MIT