cloudmap 1.0.0rc1__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.0rc1.dist-info/METADATA

@@ -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

cloudmap-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,31 @@
+cloudmap/__init__.py,sha256=bG7QoXvuxTK968OssC3_VJvinwGyKGNxX_5W5z8RuNA,103
+cloudmap/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+cloudmap/cli.py,sha256=_KZ_I1a8WEEo5dNVLZSkALgmrgtpUgKNXzntb_unWYY,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=mc0Mkll9y4GURZlQy6_jw-TD5Dam3oc55kFmcUhZiUE,30598
+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.0rc1.dist-info/METADATA,sha256=8jG_bw7iVFf1blEMXkjyllfAgqbdiuQqBXo6VMymLhU,15565
+cloudmap-1.0.0rc1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cloudmap-1.0.0rc1.dist-info/entry_points.txt,sha256=ZUuIWqdDKuI5ByXzgguh-nfMG60JJw8eDQmCaGVq4YA,47
+cloudmap-1.0.0rc1.dist-info/licenses/LICENSE,sha256=Wy9D6_gdsGVBxkAiEFWggtrs5LzTxr1wTtA_vg4VV4A,1076
+cloudmap-1.0.0rc1.dist-info/RECORD,,

cloudmap-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudmap-1.0.0rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cloudmap = cloudmap.cli:main

cloudmap-1.0.0rc1.dist-info/licenses/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.