cloudmap 1.0.0__py3-none-any.whl

cloudmap/scrub.py

@@ -0,0 +1,300 @@
+"""Turn a captured raw export into a fixture that can be committed.
+
+Why this exists: every test in this repo runs on data we wrote ourselves, which
+only proves the extractors agree with our imagination. A *real* export, scrubbed,
+turns "given this real input the map MUST contain these edges" into a test that
+can actually fail. That is the difference between trust-by-design and
+trust-by-evidence, and PLAN.md names it as the weakest link.
+
+The hard part is that scrubbing must not destroy the very thing under test. An
+app setting says `https://kv-payments.vault.azure.net/`; the vault resource is
+named `kv-payments`; connecting those two IS the extractor's job. So this is a
+GLOBAL, consistent substitution: one pseudonym per real token, applied to every
+string in the document. Rename the vault and the app setting follows it.
+
+Two things are deliberately preserved because the rules depend on them:
+  - service domain suffixes (`.vault.azure.net`, `.database.windows.net`, ...),
+    which is how `_DOMAIN_KIND` decides what an edge means;
+  - instrumentation-key GUIDs, which correlate an app to its App Insights - they
+    are pseudonymised consistently rather than redacted, so the link survives.
+
+Credentials get the opposite treatment: they carry no structure worth keeping, so
+password / key / SAS fragments are REDACTED in place while the host and database
+around them survive, pseudonymised.
+
+The mapping is never written to disk. It is the re-identification key; keeping it
+would undo the point of the exercise.
+
+This is a scrubber, not a proof. READ THE OUTPUT before you commit it.
+"""
+
+import json
+import re
+
+from .extract.extractors import ROLE_NAMES
+
+# Built-in role definition GUIDs are public Azure constants, identical in every
+# tenant, and the extractor resolves role NAMES from them. Pseudonymising them
+# would turn "AcrPull" into "custom role" and quietly degrade the fixture.
+KEEP_GUIDS = {g.lower() for g in ROLE_NAMES}
+
+# Pseudonym prefixes: a fixture is easier to reason about when the fake name
+# still says what the resource is.
+ABBREV = {
+    "microsoft.web/sites": "app",
+    "microsoft.web/serverfarms": "plan",
+    "microsoft.keyvault/vaults": "kv",
+    "microsoft.storage/storageaccounts": "st",
+    "microsoft.sql/servers": "sql",
+    "microsoft.dbforpostgresql/flexibleservers": "pg",
+    "microsoft.dbforpostgresql/servers": "pg",
+    "microsoft.dbformysql/flexibleservers": "mysql",
+    "microsoft.dbformysql/servers": "mysql",
+    "microsoft.documentdb/databaseaccounts": "cosmos",
+    "microsoft.cache/redis": "redis",
+    "microsoft.servicebus/namespaces": "sb",
+    "microsoft.eventhub/namespaces": "eh",
+    "microsoft.search/searchservices": "srch",
+    "microsoft.cognitiveservices/accounts": "ai",
+    "microsoft.containerregistry/registries": "acr",
+    "microsoft.containerservice/managedclusters": "aks",
+    "microsoft.operationalinsights/workspaces": "law",
+    "microsoft.insights/components": "appi",
+    "microsoft.network/virtualnetworks": "vnet",
+    "microsoft.network/privateendpoints": "pe",
+    "microsoft.network/applicationgateways": "agw",
+    "microsoft.apimanagement/service": "apim",
+    "microsoft.managedidentity/userassignedidentities": "mi",
+    "microsoft.app/containerapps": "ca",
+    "microsoft.app/managedenvironments": "cae",
+    "microsoft.authorization/roleassignments": "ra",
+}
+
+# Host suffixes that must survive verbatim: the extractor reads the suffix to
+# decide what kind of dependency a hostname is.
+AZURE_SUFFIXES = (
+    "vault.azure.net", "core.windows.net", "database.windows.net",
+    "postgres.database.azure.com", "mysql.database.azure.com",
+    "documents.azure.com", "redis.cache.windows.net", "servicebus.windows.net",
+    "search.windows.net", "openai.azure.com", "cognitiveservices.azure.com",
+    "azurecr.io", "azurewebsites.net", "azure-api.net", "azureedge.net",
+    "azurecontainerapps.io", "monitor.azure.com", "applicationinsights.azure.com",
+)
+
+_GUID = re.compile(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I)
+_EMAIL = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
+_IPV4 = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+# Hosts are only hunted where a host can legitimately appear. A bare
+# "looks like a hostname" regex also matches `properties.serverFarmId` and
+# `microsoft.web/sites`, and pseudonymising those would shred the document.
+_AZURE_HOST = re.compile(r"\b(?:[a-z0-9-]+\.)+(?:" +
+                         "|".join(re.escape(s) for s in AZURE_SUFFIXES) + r")\b", re.I)
+_URL_HOST = re.compile(r"(?i)\bhttps?://([a-z0-9.-]+\.[a-z]{2,})")
+_CONN_HOST = re.compile(r"(?i)\b(?:server|host|hostname|data source)\s*=\s*"
+                        r"([a-z0-9.-]+\.[a-z]{2,})")
+
+# Credential shapes. `instrumentationkey` is excluded on purpose: it is a
+# correlation id the extractor needs, and the GUID pass pseudonymises it.
+_SECRET_PATTERNS = [
+    re.compile(r"(?i)\b(password|pwd)\s*=\s*[^;,\"'\s]+"),
+    re.compile(r"(?i)\b(accountkey|sharedaccesskey|primarykey|secondarykey|"
+               r"apikey|api[-_]?key|client[-_]?secret|access[-_]?key)\s*=\s*[^;,\"'\s]+"),
+    re.compile(r"(?i)\b(sig)=[^&;,\"'\s]+"),
+    re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/-]{20,}=*"),
+    # Long opaque blobs: base64-ish keys that carry no structure worth keeping.
+    # `/` is deliberately NOT in the class even though it is a base64 character:
+    # with it, `.../providers/Microsoft.ContainerService/managedClusters/x` reads
+    # as one 40-char blob and the scrubber shreds ARM ids. A real key still has a
+    # 40+ run between its slashes. The digit lookahead keeps long words out.
+    re.compile(r"(?<![A-Za-z0-9+/])(?=[A-Za-z0-9+]*\d)[A-Za-z0-9+]{40,}={0,2}"
+               r"(?![A-Za-z0-9+])"),
+]
+
+# A token shorter than this substitutes inside unrelated words more often than it
+# hides anything, so it is reported instead of applied.
+MIN_TOKEN = 3
+
+# ARM path segments. A resource unluckily named "sites" would otherwise rewrite
+# every `providers/Microsoft.Web/sites/...` id in the document and corrupt it.
+RESERVED = {
+    "sites", "servers", "vaults", "providers", "subscriptions", "resourcegroups",
+    "components", "accounts", "service", "services", "registries", "namespaces",
+    "workspaces", "serverfarms", "redis", "virtualnetworks", "subnets",
+    "privateendpoints", "applicationgateways", "managedclusters", "databaseaccounts",
+    "flexibleservers", "searchservices", "roleassignments", "containerapps",
+    "userassignedidentities", "managedenvironments", "storageaccounts",
+}
+
+# Values that describe the schema rather than the tenant: substituting inside
+# them can only do damage.
+PROTECTED_KEYS = {"type", "location"}
+
+
+def _private_ip(ip):
+    """Private ranges are topology, not identity - keep them, they are the whole
+    point of a network diagram."""
+    p = ip.split(".")
+    if len(p) != 4 or not all(x.isdigit() for x in p):
+        return False
+    a, b = int(p[0]), int(p[1])
+    return a == 10 or (a == 172 and 16 <= b <= 31) or (a == 192 and b == 168) or a == 127
+
+
+class _Namer:
+    """Hands out stable pseudonyms, one per distinct real value. Stability is the
+    whole trick: the same real token always becomes the same fake one, wherever
+    it appears, which is what keeps a reference and its target correlated."""
+
+    def __init__(self):
+        self.map = {}
+        self._counts = {}
+
+    def custom(self, real, counter, template):
+        key = str(real).lower()
+        if key not in self.map:
+            self._counts[counter] = self._counts.get(counter, 0) + 1
+            self.map[key] = template.format(n=self._counts[counter])
+        return self.map[key]
+
+    def get(self, real, prefix):
+        return self.custom(real, prefix, prefix + "{n}")
+
+    def guid(self, real):
+        return self.custom(real, "guid", "{n:08d}-0000-0000-0000-000000000000")
+
+
+def redact_credentials(text):
+    """Blank out credential fragments in place. Returns (text, n_redactions).
+
+    Only a NAMED key keeps its head: `AccountKey=<secret>` stays readable as
+    `AccountKey=REDACTED`, which is what makes a scrubbed export still legible.
+    A bare blob is replaced whole - splitting it on `=` would treat base64
+    PADDING as if it were a key name and write the secret back out verbatim
+    (`<secret>==` -> `<secret>=REDACTED`). That bug shipped a live storage key
+    into a capture; the head is now taken from the pattern's own group, never
+    guessed from the text.
+    """
+    total = 0
+    for pat in _SECRET_PATTERNS:
+        named = pat.groups > 0
+
+        def repl(m, named=named):
+            return f"{m.group(1)}=REDACTED" if named else "REDACTED"
+
+        text, n = pat.subn(repl, text)
+        total += n
+    return text, total
+
+
+def _walk(obj, fn):
+    """Apply fn to every string in a nested structure, keys included - except the
+    values of PROTECTED_KEYS, which describe the schema, not the tenant."""
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            nk = fn(k) if isinstance(k, str) else k
+            out[nk] = v if (isinstance(k, str) and k in PROTECTED_KEYS
+                            and isinstance(v, str)) else _walk(v, fn)
+        return out
+    if isinstance(obj, list):
+        return [_walk(v, fn) for v in obj]
+    if isinstance(obj, str):
+        return fn(obj)
+    return obj
+
+
+def collect_tokens(resources, namer):
+    """Build the real -> pseudonym map from the structured fields, where we know
+    what a value *is*, rather than guessing from free text."""
+    hosts = {}
+    for r in resources:
+        if not isinstance(r, dict):
+            continue
+        rtype = str(r.get("type") or "").lower()
+        prefix = ABBREV.get(rtype) or (rtype.rsplit("/", 1)[-1][:6] or "res")
+        name = r.get("name")
+        pseudo = namer.get(name, prefix + "-") if name else None
+        if r.get("resourceGroup"):
+            namer.get(r["resourceGroup"], "rg-")
+        if r.get("subscriptionId"):
+            namer.guid(r["subscriptionId"])
+
+        # Host fields: keep the service suffix, replace the identifying label.
+        props = r.get("properties") if isinstance(r.get("properties"), dict) else {}
+        candidates = [props.get("defaultHostName"), props.get("fullyQualifiedDomainName"),
+                      props.get("vaultUri"), props.get("loginServer"),
+                      props.get("documentEndpoint"), props.get("hostName")]
+        candidates.extend(props.get("hostNames") or [])       # custom domains
+        for host in candidates:
+            if not isinstance(host, str) or "." not in host:
+                continue
+            host = host.replace("https://", "").replace("http://", "").strip("/").lower()
+            if host in hosts:
+                continue
+            label, suffix = host.split(".", 1)
+            if suffix.endswith(AZURE_SUFFIXES) and pseudo:
+                hosts[host] = f"{pseudo}.{suffix}"
+            else:
+                hosts[host] = namer.custom(host, "host", "host{n}.example.invalid")
+    namer.map.update(hosts)
+    return namer.map
+
+
+def scrub(resources):
+    """Pseudonymise a raw export. Returns (resources, stats).
+
+    Order matters: redact first so a secret never enters the mapping, then map
+    the identifiers that survive, then substitute everywhere at once."""
+    for r in resources:
+        if isinstance(r, dict) and "kubernetes_text" in r:
+            del r["kubernetes_text"]
+            
+    text = json.dumps(resources)
+    text, redactions = redact_credentials(text)
+    resources = json.loads(text)
+
+    namer = _Namer()
+    collect_tokens(resources, namer)
+
+    # Free-text sweep for identifiers the structured pass cannot see: references
+    # to resources outside the scan, GUIDs, people, endpoints.
+    for m in _GUID.findall(text):
+        if m.lower() not in KEEP_GUIDS:
+            namer.guid(m)
+    for m in _EMAIL.findall(text):
+        namer.custom(m, "user", "user{n}@example.invalid")
+    for m in _IPV4.findall(text):
+        if not _private_ip(m):                      # private ranges are topology, keep them
+            namer.custom(m, "ip", "203.0.113.{n}")
+    for m in _AZURE_HOST.findall(text):
+        h = m.lower()
+        if h not in namer.map:
+            # Outside the scanned set, so no resource lends it a name - but the
+            # service suffix must survive, it is what the edge kind is read from.
+            namer.custom(h, "ext", "ext{n}." + h.split(".", 1)[1])
+    for m in _URL_HOST.findall(text) + _CONN_HOST.findall(text):
+        h = m.lower()
+        if h not in namer.map and not h.endswith(AZURE_SUFFIXES):
+            namer.custom(h, "host", "host{n}.example.invalid")
+
+    mapping, skipped = {}, []
+    for real, pseudo in namer.map.items():
+        if len(real) < MIN_TOKEN or real in RESERVED:
+            skipped.append(real)       # unsafe to replace - reported, never hidden
+            continue
+        mapping[real] = pseudo
+
+    if mapping:
+        # Longest first: a full hostname must win over the bare resource name
+        # inside it. The lookarounds stop a name matching inside a longer word.
+        alt = "|".join(re.escape(t) for t in sorted(mapping, key=len, reverse=True))
+        rx = re.compile(r"(?<![A-Za-z0-9])(?:" + alt + r")(?![A-Za-z0-9])", re.I)
+        resources = _walk(resources, lambda s: rx.sub(lambda m: mapping[m.group(0).lower()], s))
+
+    stats = {
+        "resources": len(resources) if isinstance(resources, list) else 0,
+        "tokens": len(mapping),
+        "redactions": redactions,
+        "short_tokens_left_alone": sorted(set(skipped)),
+    }
+    return resources, stats

cloudmap-1.0.0.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.5
+Name: cloudmap
+Version: 1.0.0
+Summary: Trace the blast radius of an Azure resource: one name in, a verified dependency graph out.
+Project-URL: Homepage, https://github.com/KatsaounisThanasis/cloudmap
+Project-URL: Repository, https://github.com/KatsaounisThanasis/cloudmap
+Project-URL: Issues, https://github.com/KatsaounisThanasis/cloudmap/issues
+Project-URL: Changelog, https://github.com/KatsaounisThanasis/cloudmap/releases
+Author: Thanos Katsaounis
+License: MIT
+License-File: LICENSE
+Keywords: azure,azure-resource-graph,blast-radius,dependency-graph,devops,drawio,incident-response,mermaid,sre
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+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](https://img.shields.io/pypi/v/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
+[![Python](https://img.shields.io/pypi/pyversions/cloudmap?color=1f7a8c)](https://pypi.org/project/cloudmap/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**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
+an interactive HTML viewer, Mermaid, JSON and CSV.**
+
+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.
+
+![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)
+
+**Contents** · [Install](#install) · [60-second demo](#60-second-demo) ·
+[Interactive wizard](#interactive-wizard) · [Why](#why) ·
+[What it maps](#what-it-maps) · [How it works](#how-it-works) ·
+[Ask a map questions](#ask-a-map-questions) · [Live Azure](#live-azure-opt-in) ·
+[Capture and scrub](#capture-a-real-export-so-the-tests-can-be-wrong) ·
+[Usage reference](#usage-reference)
+
+## Install
+
+```
+pip install cloudmap
+```
+
+Python 3.9+. Two runtime dependencies (`rich` and `questionary`, both for the
+terminal UI). Live mode additionally needs the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
+on your PATH, and the optional AI passes need a local [ollama](https://ollama.com).
+
+To work on it instead:
+
+```
+git clone https://github.com/KatsaounisThanasis/cloudmap && cd cloudmap
+pip install -e ".[dev]" && pytest
+```
+
+## 60-second demo
+
+No Azure account needed - the repo ships a synthetic estate:
+
+```
+cloudmap trace contoso-web --from fixtures/contoso.json -o contoso-web.drawio
+```
+
+```text
+Blast radius: 9 resources (0 external), 9 dependencies
+╭────────────────────────────── Dependency Graph ──────────────────────────────╮
+│ 🌐 contoso-web                                                               │
+│ ├── --hosted-on--> 📦 App Service Plan                                       │
+│ ├── --vnet-integration--> 📦 Virtual Network                                 │
+│ ├── --connects-to--> 🗄️ SQL Server                                           │
+│ ├── --sends-telemetry--> 📦 App Insights                                     │
+│ │   └── --uses-workspace--> 📦 Log Analytics                                 │
+│ ├── --reads-secret; role: Key Vault Secrets User--> 🔐 Key Vault             │
+│ └── --connects-to--> 📦 Storage                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
+🔗 draw.io: contoso-web.drawio
+```
+
+On a real estate it goes several layers deep:
+
+```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.)
+
+### Output formats
+
+| Flag | You get |
+|---|---|
+| `-o FILE` | **draw.io** diagram with native Azure icons - open it in [draw.io](https://app.diagrams.net), the desktop app or the VS Code extension and edit it like any hand-drawn diagram |
+| `--html FILE` | **Interactive viewer**: one self-contained file, no server and no CDN. Dark mode, edges colour-coded by relationship type (security / data / network), resource-group filters and search, SVG + PNG export, and direct links into the Azure portal |
+| `--mermaid FILE` | Mermaid source, for embedding in Markdown docs |
+| `--json FILE` | The graph itself - this is what `cloudmap ask` reads |
+| `--csv FILE` | Flat edge list with evidence, for a spreadsheet or an auditor |
+
+## Interactive wizard
+
+Run it with no arguments and it walks you through the whole thing:
+
+```
+cloudmap
+```
+
+It asks for a subscription (yours is marked as the default), then a resource
+group, then the resource to trace, then how deeply to enrich, and where to write
+the results. It reads live Azure, so `az login` first.
+
+## 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.
+
+### Three things people use it for
+
+**Is this safe to delete?** An Azure SQL database looks orphaned in the portal and
+someone wants it gone to save the monthly bill. `cloudmap trace sql-orders-dev
+--direction up` deep-enriches the connection strings of the web apps in the
+subscription and shows what still points at it - including, occasionally, a
+production app that was never supposed to.
+
+**What is actually broken?** An AKS cluster starts failing at 3am. Tracing it
+produces a dependency graph with the Key Vault it reads, and the map carries the
+evidence for that edge ("found in Kubernetes secret X"), so the next question -
+did anything change on that vault - has a place to start.
+
+**Who has access to this?** An auditor asks which systems can reach the storage
+account holding customer data. `cloudmap trace pii-storage --direction up --csv
+pii-audit.csv` hands back a spreadsheet of the web apps and clusters with managed
+identity RBAC on it, with the role assignments as proof.
+
+## What it maps
+
+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.
+
+## 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 + CSV + 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.
+
+## 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.
+
+## 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.**
+
+## 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.
+
+## Usage reference
+
+```
+cloudmap trace <name> (--from <fixture.json> | --live) [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
+  --csv FILE                 also write the edge list as CSV
+  -d, --out-dir DIR          write every artifact into DIR, named after the seed
+```
+
+Other subcommands: `cloudmap capture`, `cloudmap scrub`, `cloudmap ask` (see above).
+
+## Roadmap
+
+- Terraform state ingestor + drift overlay (desired vs actual).
+- Deeper 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

cloudmap-1.0.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+cloudmap/__init__.py,sha256=69NbQSVnApWgYso7YuGNb7hhUNhl1mMgO71Ah-kUr9I,103
+cloudmap/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+cloudmap/cli.py,sha256=0S4axVH3RT4TtkOKgl5uDtbl8kg8ikY-QhMx02oNyZk,24699
+cloudmap/graph.py,sha256=Q-oFvzUvISmmmzvO3VVGzxQZXs3WT2ILVwmM9Aptl4A,8850
+cloudmap/interactive.py,sha256=zi6OEWdWltlro5vmxGPZ1hZVO4IkcWWMB_oT71h4Uhs,8562
+cloudmap/local_model.py,sha256=h8-f_UJt7b-fNQScA5-GK9Ms0hnNyU1XEG__wiliL3Q,1988
+cloudmap/model.py,sha256=aGH9XLiLzkOUd5VzB4VxXvG-xMW5__bV9bywQJykPe8,1856
+cloudmap/scrub.py,sha256=HdCFN0sLqM_cwQrFRWK7B-yVoVejpMth4sR6FLoEAKs,13593
+cloudmap/adapters/__init__.py,sha256=Z-1S89QVo8aWgo8nrzJ4Sej84T7XlzIpxv2O7ltZnTo,3185
+cloudmap/ask/__init__.py,sha256=Jx45UovITygdgqrhEbqZpawpXFDPRy9hoFXLAwXM3so,5040
+cloudmap/ask/intent.py,sha256=Z4ndkYnwGghSZYe0bUzVZr-WnKA-joZNNh5KLveJcrQ,5558
+cloudmap/ask/narration.py,sha256=zm9xksPGAUNYwe4LfvpCt05GAxNbb1kwwjZ4Da0QiwM,1934
+cloudmap/ask/queries.py,sha256=KGwaspXU1JIEAub6hw6V92iVa2Ko8BN4avA3soLEbns,12803
+cloudmap/extract/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cloudmap/extract/extractors.py,sha256=v5GnfFK1Z4pTZ-YRP4FEluPqiVVFlBz_FTXp3xAhODk,30599
+cloudmap/extract/llm.py,sha256=I9g0OjYHHqLdqGBwr3PXlk0XpYekWIfgRLVr0vuapXE,4578
+cloudmap/ingest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cloudmap/ingest/azure.py,sha256=YOlezJVTU9bhOdazEenQvgabuKaVcPrw5UGimaT-mnc,17219
+cloudmap/ingest/fixture.py,sha256=89wWoNgSyXN_eR81dqfD_3YNwuLLps_6ZRQEeqwwyTM,460
+cloudmap/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cloudmap/render/azure_icons.py,sha256=7h9ig2rAxC98BL9yyY6nxIJyCu7BVmD2Zz4Kd99I26I,72340
+cloudmap/render/csv_export.py,sha256=vX3fkZGTeJunK6Stp5mJE2sY0mlG06ksd7sixHVJ_zg,1315
+cloudmap/render/drawio.py,sha256=9MEGRjfI4whYXf71sEOixx7RfUBGPbVXrHRVQlNmH00,6192
+cloudmap/render/html.py,sha256=ZaGLVHUdOBWnu-CvVhTxNKXM-XOSufD1TdeOcmUr7TU,28980
+cloudmap/render/json_out.py,sha256=3WxetnmkjZoaeRIT1sAfGl-jduQsCJkclx5kGKmEiks,2103
+cloudmap/render/mermaid.py,sha256=KtypnIITMu71ZE37iuT2GIigBTt8mxBv_dhBifZXOjY,1081
+cloudmap-1.0.0.dist-info/METADATA,sha256=zCie97x2f9DED5pLHZAK-0TXzZ2RXjyQa-UIxKG5fDI,17942
+cloudmap-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cloudmap-1.0.0.dist-info/entry_points.txt,sha256=ZUuIWqdDKuI5ByXzgguh-nfMG60JJw8eDQmCaGVq4YA,47
+cloudmap-1.0.0.dist-info/licenses/LICENSE,sha256=Wy9D6_gdsGVBxkAiEFWggtrs5LzTxr1wTtA_vg4VV4A,1076
+cloudmap-1.0.0.dist-info/RECORD,,