cloudmap 1.3.2__tar.gz → 1.3.3__tar.gz

cloudmap-1.3.3/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,43 @@
+name: Bug report
+description: Something broke, or the map is wrong
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: cloudmap version
+      description: "`pip show cloudmap` or `cloudmap --help` header"
+      placeholder: "1.3.2"
+    validations:
+      required: true
+  - type: input
+    id: command
+    attributes:
+      label: The exact command you ran
+      placeholder: "cloudmap trace my-app --live --allow-live --single-sub"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what did you expect
+      description: Paste the output. If the map itself is wrong (a missing or bogus edge), say which edge.
+    validations:
+      required: true
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Minimal synthetic fixture (for wrong-map bugs)
+      description: >
+        The perfect report reproduces the wrong edge with a minimal synthetic
+        fixture - see fixtures/contoso.json for the shape. NEVER paste a real
+        capture; run `cloudmap scrub` on it first and read the file before
+        posting.
+      render: json
+  - type: checkboxes
+    id: scrubbed
+    attributes:
+      label: Safety check
+      options:
+        - label: Anything I pasted above contains no real resource names, subscription ids or credentials.
+          required: true

cloudmap-1.3.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/KatsaounisThanasis/cloudmap/security/advisories/new
+    about: Anything that could expose a user's infrastructure data - report it privately, never as a public issue.

cloudmap-1.3.3/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: A resource type mapped poorly, a missing edge kind, a workflow that needs a flag
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The situation
+      description: What were you trying to learn from the map, and what did it give you instead?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you would expect
+      description: >
+        If it is a missing dependency for a resource type: which property of
+        which type expresses it? (That is usually a small extractor rule plus a
+        fixture test.) Keep in mind the rules in CONTRIBUTING.md - read-only,
+        local-first, every edge carries evidence.

cloudmap-1.3.3/.gitignore

@@ -0,0 +1,30 @@
+__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/
+
+# A live trace writes artifacts named after the resource it traced, so their
+# names cannot be known in advance. Point --out-dir at live/ or out/ above.
+# These root-anchored rules are the belt-and-braces for the ones that land in
+# the repo root anyway - no tracked file at the root has these extensions, and
+# the committed sample artifacts live under tests/ and docs/, which are unaffected.
+/*.drawio
+/*.json
+/*.html
+/*.csv
+/*.mmd

cloudmap-1.3.3/ARCHITECTURE.md

@@ -0,0 +1,168 @@
+# 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+; two runtime deps, `rich` and
+`questionary`, both for the terminal UI) that takes the **name of one Azure
+resource** and produces its full **dependency graph (blast radius)** as an
+**editable draw.io diagram**, plus an interactive HTML viewer, Mermaid, JSON and
+CSV. It is a clean four-stage pipeline: **ingest** (fixture or live `az`) →
+**extract** (properties / hostnames / RBAC / secrets → typed edges) → **graph**
+(direction-consistent blast-radius BFS) → **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 / capture / scrub / ask"] --> TRACE["_cmd_trace"]
+    CLI -->|"no args, tty"| WIZ["interactive.py<br/>wizard: sub → rg → resource"]
+    WIZ --> TRACE
+
+    TRACE -->|"--from (or 'demo')"| FIX["adapters/load_graph()<br/>raw export or neutral map"]
+    TRACE -->|"--live"| AZ["ingest/azure.py<br/>query_live()"]
+
+    AZ --> GUARD["_guard()<br/>optional ALLOW_SUB pin"]
+    AZ --> SUBS["_target_subscriptions()<br/>tenant-wide by default"]
+    AZ --> PAGE["_graph_paged()<br/>ALL types, skip_token paging"]
+
+    FIX --> BUILD["graph.build_graph()"]
+    AZ --> BUILD
+    BUILD --> EXTRACT["extract_edges()<br/>typed rules + 4 generic passes"]
+
+    TRACE --> ENRICH["_enrich_live() per seed type<br/>enrich_webapps() / enrich_aks_clusters()<br/>appsettings+RBAC+diag, secrets in-memory"]
+    ENRICH --> EXTERNAL["seed_external_dependencies()<br/>never-drop → external nodes"]
+
+    BUILD --> BLAST["blast_radius() graph.py<br/>BFS, direction consistency"]
+    EXTERNAL --> BLAST
+    BLAST --> COLLAPSE["collapse_high_level()<br/>singletons keep their name"]
+    COLLAPSE --> R1["render/drawio.py<br/>native Azure icons"]
+    COLLAPSE --> R2["render/mermaid.py"]
+    COLLAPSE --> R3["render/json_out.py<br/>meta: truncated/gaps/blind spots"]
+    COLLAPSE --> R4["render/html.py<br/>self-contained viewer"]
+    COLLAPSE --> R5["render/csv_export.py<br/>edge list + evidence"]
+
+    CLI --> ASK["_cmd_ask"]
+    R3 -.->|"saved map, reloaded"| FIX
+    ASK --> 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 outbound call:<br/>ollama or OpenAI-compatible, local"]
+    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 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":[...]}` 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: the single `subprocess.run` boundary with timeouts, the optional `CLOUDMAP_ALLOW_SUBSCRIPTION` pin (never injected into `az account` commands, so a mismatch is reported as a mismatch), `classify_gap()` so artifacts carry categories instead of raw stderr, and the rule that Kubernetes secret text never reaches an export. |
+| `cloudmap/extract/extractors.py` | **The heart**: properties/hosts/RBAC/secrets → edges | Typed rules for ~17 services plus four generic passes that make "any type" true: ARM-id references (with containment property paths excluded, not whole types), host mentions, nested child-of, and generic host indexing (a host counts as identity only when it carries the resource's own name - two apps on one App Service scale unit share `ftpsHostName`). Observers (alert rules, dashboards) emit `observes` instead of vanishing. |
+| `cloudmap/graph.py` | Build graph + blast-radius BFS + the high-level collapse | Direction consistency in `blast_radius` (never reverse once you have stepped, tracked per direction) is why a shared VNet/plan does not pull in unrelated apps. `collapse_high_level` folds instances into one box per type, keeps a singleton's real name, and carries kinds AND evidence across. |
+| `cloudmap/interactive.py` | The zero-argument wizard | Offers every resource in the subscription (no type allowlist - the engine has none), delegates all `az` I/O to `ingest.azure`, and pins the chosen subscription before handing off to `_cmd_trace`. |
+| `cloudmap/scrub.py` | Global consistent pseudonymisation for captures | Identifier positions are renamed consistently (a reference and its target stay correlated); credentials are redacted, and its docstrings carry the postmortems of the two leak classes that shipped and were caught. |
+| `cloudmap/render/drawio.py` | `.drawio` with Azure2 icons | Verified icon paths; falls back to a box, external nodes render dashed, so an icon is never broken. |
+| `cloudmap/render/html.py` | One self-contained interactive viewer | No server, no CDN; the INCOMPLETE badge opens its "why" in the side panel, grouped ×N boxes list their instances on click. |
+| `cloudmap/render/{mermaid,json_out,csv_export}.py` | Secondary outputs | Preview, machine-readable inventory (with the honesty meta), and a flat evidence-bearing edge list for auditors. |
+| `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. |
+| `cloudmap/ask/intent.py` | Question → one query | Rules first; 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, printed *below* them. |
+| `cloudmap/local_model.py` | The single outbound model call | One module = one auditable promise: localhost (ollama's API by default, any OpenAI-compatible server via `CLOUDMAP_LLM_URL`), and failure returns an empty value. |
+| `cloudmap/cli.py` | Orchestration + argparse | `_cmd_trace` wires the stages; `_cmd_capture`/`_cmd_scrub` produce committable fixtures; `_cmd_ask` loads a saved map and prints the computed answer, proof lines included. |
+| `cloudmap/data/contoso.json` | The packaged demo estate | `--from demo` must work for a pip-only install - the first command a stranger runs cannot depend on cloning the repo. |
+| `fixtures/` | Synthetic + scrubbed-golden estates | Fixture-first development → zero cloud contact in tests. |
+| `tests/` | 468 tests | Behaviour-named; includes a conformance sweep of all 4,687 published Azure resource types (`tests/data/azure_resource_types.txt`) through every dependency channel, a realistic-estate suite with the property names Azure genuinely returns, and `test_fixtures_safe.py`, which fails CI if a fixture ever carries a credential. |
+| `.gitignore` | Safety | `live/`, `*.live.json`, `*.blast.drawio` and every artifact extension at the repo root are ignored → output from a real tenant cannot be committed by accident. |
+
+## Execution Flow
+
+**Fixture path** (`cloudmap trace contoso-web --from demo`):
+
+1. `__main__.py` → `cli.main()` - argparse, or the wizard when run bare on a tty.
+2. `_cmd_trace` - fixture branch → `adapters.load_graph()` (raw export or neutral
+   map, auto-detected; a reloaded capture keeps its truncated/gaps meta).
+3. `graph.build_graph()` → builds `Node`s and calls `extract_edges()`.
+4. `extract_edges()` - constructs a `Resolver` and derives edges: typed rules
+   (`serverFarmId`→hosted-on, VM `has-nic`/`uses-disk`, NIC `in-subnet`, config
+   hostnames/vault refs/IK, RBAC via system AND user-assigned identity
+   principals, `managedBy`), then the generic passes for every other shape.
+5. `find_seeds()` - exact id, exact name, else substring; >1 → each match is
+   printed with its resource group and full id.
+6. `blast_radius()` - BFS from the seed in both directions, never reversing.
+7. Render: draw.io / HTML / Mermaid / JSON / CSV, `_print_summary` shows
+   "Depends on" and "What depends on it" as separate panels.
+
+**Live path** (`--live --allow-live [--resolve-secrets]`) - additionally:
+
+8. `query_live()` → `_guard()` (optional pin check) → `_target_subscriptions()`
+   → `_graph_paged()` (ALL resource types + tenant-wide role assignments,
+   `skip_token` paging, loud warning at the page cap).
+9. `_enrich_live()` picks targets by seed type: a workload seed enriches itself;
+   a config-referenced data service (Key Vault, SQL, storage, Redis, ...)
+   enriches every app in scope, because only their config reveals its
+   dependents; compute/network seeds stay seed-only - ARM already has their
+   relationships. `enrich_webapps()`/`enrich_aks_clusters()` run concurrently
+   (`CLOUDMAP_ENRICH_WORKERS`, default 12). Secrets resolve **in-memory** only.
+10. Rebuild, `seed_external_dependencies()` resurfaces unresolved references as
+    dashed external nodes, and 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 full suite runs in ~2s
+  without Azure.
+- **Direction consistency** (`blast_radius`). Real-world testing showed shared
+  plan/VNet connect dozens of unrelated apps. "From the seed go both ways, but
+  never reverse afterwards" solves it without a hub-type list; the visited set
+  is tracked per direction so a node reachable both ways loses neither cone.
+- **Containment is not dependency** (`_CONTAINMENT_PATHS`). A VNet's
+  `subnets[].ipConfigurations` enumerate what is plugged INTO it; following them
+  made a shared VNet a hub. But its DDoS plan and peerings are real
+  dependencies, so the exclusion is on property paths, not on types - an
+  earlier type-wide exclusion silently lost all of those edges.
+- **Generic before hand-written, resolver as the safety net.** A type with no
+  rule still maps through ARM ids, advertised hosts, child ids and RBAC; a
+  reference that names nothing scanned yields no edge, so the generic passes
+  cannot invent a dependency. This is what a 4,687-type conformance sweep pins.
+- **Enrichment is scoped by seed type, and the gap is declared**
+  (`_enrichment_targets`). Tracing a VM must not deep-read 289 web apps to
+  learn what ARM already says; tracing a vault must, because config is the only
+  place its dependents exist. Whatever is skipped becomes a `blind_spot`.
+- **Scrub preserves structure, not identity** (`scrub.py`), and a capture never
+  carries Kubernetes secret text at all - the field is stripped before any
+  export, under every flag combination.
+- **Never silent drop** (`seed_external_dependencies` + `model.py`).
+- **The model proposes, code verifies** (`extract/llm.py`): only proposals that
+  resolve to a scanned resource survive, drawn dashed and marked; `ask` may use
+  the model to route a phrasing or narrate a computed answer, never to state a
+  fact.
+
+## Open Questions / Risks
+
+- **Live validation breadth**: the engine is conformance-tested against every
+  published type, but has been exercised against one real tenant. Property
+  shapes in other tenants/clouds may surface new false-positive classes like
+  the shared `ftpsHostName` one (found live, fixed, regression-pinned).
+- **Deep config readers exist for App Service and AKS only.** Other types'
+  runtime config (Logic Apps run history, Data Factory linked-service secrets)
+  needs per-type API calls; today those dependencies appear only if expressed
+  in ARM properties, and the blind spot says so.
+- **Cost of `--enrich all`** on large tenants: one `az` round-trip per app,
+  `CLOUDMAP_ENRICH_WORKERS` (default 12) at a time. No cache between runs yet -
+  every trace pays the scan again.
+- **`az graph --skip-token`** depends on the resource-graph extension version.
+- **`az aks command invoke`** starts a short-lived pod in the cluster to run
+  its read-only kubectl - documented in the README as the one asterisk on
+  "read-only".
+- **Secret resolution reachability**: a vault behind an unreachable private
+  endpoint fails the in-memory resolve and the dependency shows as external
+  rather than resolved.

{cloudmap-1.3.2 → cloudmap-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudmap
-Version: 1.3.2
+Version: 1.3.3
 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
@@ -48,6 +48,7 @@ Description-Content-Type: text/markdown
   <a href="#60-second-demo"><b>Demo</b></a> ·
   <a href="#interactive-wizard"><b>Wizard</b></a> ·
   <a href="#why"><b>Why</b></a> ·
+  <a href="#what-you-will-see---and-what-you-wont"><b>What you'll see</b></a> ·
   <a href="#how-it-works"><b>How it works</b></a> ·
   <a href="#ask-a-map-questions"><b>Ask</b></a>
 </p>
@@ -100,43 +101,57 @@ cloudmap trace contoso-web --from demo -o contoso-web.drawio
 
 ```text
 Blast radius: 9 resources (0 external), 9 dependencies
-╭────────────────────────────── Dependency Graph ──────────────────────────────╮
+╭─────────────────────────────── Depends on (6) ───────────────────────────────╮
 │ 🌐 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                                              │
+│ ├── --hosted-on--> 📦 contoso-plan                                           │
+│ ├── --vnet-integration--> 📦 contoso-vnet                                    │
+│ ├── --sends-telemetry--> 📦 contoso-appi                                     │
+│ │   └── --uses-workspace--> 📦 contoso-law                                   │
+│ ├── --connects-to--> 🗄️ contoso-sql                                          │
+│ ├── --connects-to--> 📦 contosostg                                           │
+│ └── --reads-secret; role: Key Vault Secrets User--> 🔐 contoso-kv            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────── What depends on it (1) ───────────────────────────╮
+│ 🌐 contoso-web                                                               │
+│ └── <--routes-to-- 📦 contoso-agw                                            │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 🔗 draw.io: contoso-web.drawio
 ```
 
-That is the default **high-level** view - resources grouped by type. Add
-`--level detail` to see every instance with its real name, and on a real estate
-it goes several layers deep:
+The two panels are the two halves of a blast radius: what the seed needs, and
+what needs the seed. Arrows in the second panel are drawn backwards (`<--`)
+because that is the direction the dependency actually runs.
+
+That is the default **high-level** view - one box per resource type. Here every
+type happens to have a single instance, so each box keeps its real name; where a
+type has several, the box becomes `Web App ×4` and lists its members. Add
+`--level detail` to always get every instance by name. On a larger estate the
+map goes several layers deep:
 
 <details>
 <summary>A deeper map</summary>
 
+Against the enterprise fixture in the repo
+(`tests/complex_mock_demo/10_input_enterprise_architecture.json`):
+
 ```text
-Blast radius: 15 resources (0 external), 14 dependencies
-╭────────────────────────────── Dependency Graph ──────────────────────────────╮
+Blast radius: 16 resources (0 external), 15 dependencies
+╭─────────────────────────────── Depends on (2) ───────────────────────────────╮
 │ 🌐 app-spa-frontend                                                          │
 │ ├── --calls--> 🌐 app-auth-service                                           │
-│ │   ├── --reads-secret--> 🔐 kv-core-prod                                    │
-│ │   └── --connects-to--> 🗄️ cosmos-auth                                      │
+│ │   ├── --connects-to--> 🗄️ cosmos-auth                                      │
+│ │   └── --reads-secret--> 🔐 kv-core-prod                                    │
 │ └── --calls--> 🌐 app-api-gateway                                            │
+│     ├── --connects-to--> 🗄️ redis-gateway                                    │
 │     ├── --calls--> 📦 capp-payment-service                                   │
-│     │   └── --reads-secret--> 🔐 kv-payments-prod                            │
+│     │   ├── --reads-secret--> 🔐 kv-payments-prod                            │
+│     │   └── --connects-to--> 📦 eh-transactions                              │
 │     ├── --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--> 🗄️ redis-orders                                 │
 │         └── --connects-to--> 🗄️ sql-orders-prod                              │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
@@ -175,8 +190,10 @@ 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.
+- **Live-cloud tools upload your data.** cloudmap runs locally: the only traffic
+  it generates is the `az` calls to Azure's own API that fetch your inventory.
+  Nothing is uploaded anywhere else - no SaaS backend, no telemetry, no model API.
+  The graph, the diagrams and the raw properties stay on disk, on 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?"
@@ -186,8 +203,8 @@ the results. It reads live Azure, so `az login` first.
 
 **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
+--live --allow-live --direction up` deep-enriches the connection strings of the
+web apps in scope 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
@@ -196,33 +213,129 @@ 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
+account holding customer data. `cloudmap trace pii-storage --live --allow-live
+--direction up --csv pii-audit.csv` hands back a spreadsheet of the apps and clusters with managed
 identity RBAC on it, with the role assignments as proof.
 
 ## What it maps
 
-**Any Azure resource type can be a seed.** The scan is not filtered by type, and
-resources are mapped at two levels:
-
-- **Typed rules** for the services where the relationship has a specific meaning:
-  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, ML workspaces,
-  Log Analytics, App Insights, VNets, Private Endpoints and managed identities.
-  These produce edges like `hosted-on`, `reads-secret`, `pulls-image`, `routes-to`.
-- **A generic ARM-reference pass** for everything else: any resolvable resource id
-  found in a resource's properties becomes a `references` edge, with the property
-  path as proof. So a type cloudmap has never heard of is still mapped, still
-  deterministically, still with evidence.
-
-RBAC edges (`role: Key Vault Secrets User`) are extracted tenant-wide, so
-"who has access to this" works for any resource that can be a role scope.
+**Any Azure resource type can be a seed.** The scan is not filtered by type - the
+KQL is `resources | project ...` with no type filter, and the same is true of the
+wizard's picker. What differs between types is not *whether* they are mapped but
+*how precisely*, and that comes from four channels every resource goes through:
+
+| Channel | What it finds | Evidence it records |
+|---|---|---|
+| **ARM ids in properties** | any resolvable resource id anywhere in the blob, plus `managedBy` and assigned identities | the property path (`properties.serverFarmId`) |
+| **Advertised hostnames** | free text naming a scanned resource's own endpoint (`kv-x.vault.azure.net`, `acr.azurecr.io`) | the host and where it was found |
+| **Nested child ids** | a child that cannot exist without its parent (a SQL database, a Service Bus queue) | `child-of`, derived from the id's shape |
+| **RBAC role assignments** | which identity holds which role on which scope | `role: <name>`, principal → scope |
+
+On top of those, ~17 services have **typed rules** that give the edge its real
+meaning instead of a generic `references`: App Service / Functions, Container Apps
+(+ managed environments), AKS, VMs, NICs, Key Vault, Storage, SQL, PostgreSQL,
+MySQL, Cosmos, Redis, Service Bus, Cognitive Search, Cognitive Services / Azure
+OpenAI, Container Registry, ML workspaces, Log Analytics, App Insights and public
+IPs - producing `hosted-on`, `reads-secret`, `pulls-image`, `vnet-integration`,
+`uses-workspace`. A few more rules key off a **property shape** rather than a type
+name, so they fire wherever that shape appears: `privateLinkServiceConnections` →
+`private-link-to` (Private Endpoints), `backendAddressPools[].fqdn` → `routes-to`
+and `gatewayIPConfigurations` → `in-subnet` (Application Gateway), `subnet.id` →
+`in-subnet`.
+
+Everything else - API Management, Data Factory, Front Door, a type published last
+week - still lands on the map through the four channels above, as a `references`
+edge carrying the property path that produced it. That is the claim a conformance
+sweep over all **4,687 published Azure resource types** pins
+(`tests/test_type_agnostic.py`): every one of them can be a seed and can be found.
+Deliberately excluded as *sources*: alert rules and dashboards, which reference
+half the estate without depending on it - they emit `observes` instead, so they
+are still visible without turning into hubs.
+
+RBAC edges are extracted **tenant-wide by default** (`--single-sub` narrows this to
+the active subscription), so "who has access to this" works for any resource that
+can be a role scope.
 
 Depth is honest about itself: apps and clusters have rich outbound edges because
 their config names other resources. Infrastructure resources are usually leaves
 going outward, and their value is the reverse view (`--direction up`).
 
+## What you will see - and what you won't
+
+cloudmap has **no credentials of its own**. Every read is a subprocess call to the
+Azure CLI using your `az login` token, so the map is bounded by your own RBAC. If
+you are about to try this on a tenant and want to know what to expect, this
+section is the whole answer.
+
+### The two ways a resource can be missing
+
+**Invisible.** Azure Resource Graph filters by RBAC *server-side*. A resource you
+have no role on is not returned and **no error is raised** - it simply is not in
+the data. cloudmap cannot tell the difference between "does not exist" and "you
+cannot see it", and neither can you from the output alone. This is the failure
+mode to keep in mind: a thin map on a narrow account is not evidence of a small
+blast radius.
+
+**Denied.** The deep reads (app settings, Key Vault values, AKS manifests) are
+ordinary API calls that fail loudly when your role is short. cloudmap catches
+each one, classifies it, and writes it on the map as a **read gap** rather than
+dropping the edges it would have produced. You get told.
+
+### What each level of access buys you
+
+| To get this on the map | cloudmap runs | You need |
+|---|---|---|
+| The resources themselves, and every role assignment | `az graph query` | **Reader** on the subscriptions in scope. Reader is literally `*/read`, and ARG returns only what that covers. |
+| A workload's identity, VNet integration, runtime | `az webapp show` | Reader |
+| Where a resource sends its diagnostics | `az monitor diagnostic-settings list` | Reader |
+| The RBAC an app's managed identity holds elsewhere | `az role assignment list --assignee --all` | Reader at the scopes you want counted |
+| **Key Vault references and connection strings** (`--enrich`) | `az webapp config appsettings list`, `az webapp config connection-string list` | `Microsoft.Web/sites/config/list/Action`. **Reader is not enough** - this is a POST, not a read. *Website Contributor* or *Contributor* on the app have it. |
+| **What a KV-backed connection string actually points at** (`--resolve-secrets`) | `az keyvault secret show` | Key Vault **data-plane** access: *Key Vault Secrets User* (or an equivalent access policy). Values are used in memory and never printed or written. |
+| **AKS workload edges** - images, configmaps, optionally secrets | `az aks command invoke` | `Microsoft.ContainerService/managedClusters/runCommand/action`. *Azure Kubernetes Service Contributor* has it; *Cluster User* does not. |
+
+That is the complete list of `az` commands cloudmap can run. All of them are
+`show` / `list` / `query` verbs; `aks command invoke` is the one asterisk, and it
+is explained under [Live Azure](#live-azure).
+
+The practical consequence: **on a plain Reader account, tracing a Key Vault will
+usually come back nearly empty**, because the apps that read it declare that only
+in their app settings, and app settings need more than Reader. The map will say so
+as a read gap - it will not quietly show you an unused vault.
+
+### How the map tells you it is incomplete
+
+Three separate signals, all written into the artifact (`--json` `meta`, the HTML
+viewer's `INCOMPLETE ⓘ` badge, and repeated by every `cloudmap ask` answer drawn
+from that map):
+
+| Signal | Means | Fix |
+|---|---|---|
+| `truncated` | the Resource Graph scan hit the pagination cap, so the inventory itself is partial | narrow the scope: `--single-sub` |
+| `read_gaps` | a specific deep read failed - permission, network, or the resource refusing | grant the action in the table above, or accept the gap knowingly |
+| `blind_spots` | a whole class of edge was never attempted, because those workloads were not deep-enriched | `--enrich all` |
+
+`complete: false` in the JSON is set if any of the three is non-empty. An empty
+answer from an incomplete map is never allowed to read as "nothing depends on
+this".
+
+### My map came back empty or thinner than expected
+
+In order:
+
+1. **Did it find the right resource?** Matching is case-insensitive substring; on
+   more than one match cloudmap prints each candidate with its resource group and
+   full id instead of guessing.
+2. **Is the scope right?** By default cloudmap scans **every enabled subscription
+   in the tenant**. If the terminal reports fewer subscriptions than you expect,
+   your account has no role on the rest - they are invisible, not excluded.
+3. **Read the meta.** `truncated` / `read_gaps` / `blind_spots` name what is
+   missing, in that order of severity.
+4. **Was it the right direction?** Infrastructure (a vault, a subnet, a plan) has
+   few outbound edges by nature. `--direction up` is the view that matters for it.
+5. **Was it enriched?** If the seed is a data service and you did not enrich, the
+   dependents that live in app config were never looked for. Re-run with
+   `--enrich all`.
+
 ## How it works
 
 1. **Ingest** - a JSON fixture (default) or live `az graph query` (opt-in, guarded).
@@ -298,7 +411,10 @@ run the (read-only) `kubectl get` commands. Nothing of yours is modified, but an
 audit of the cluster's control plane will see that ephemeral pod.
 
 Tenant-wide enrichment runs its `az` reads concurrently; `CLOUDMAP_ENRICH_WORKERS`
-(default 12) tunes how many at once.
+(default 12) tunes how many at once. Measured on a real subscription: tracing a
+Key Vault's dependents with `--enrich` fanning out over 287 web apps and 2 AKS
+clusters took 6m08s wall-clock at the default concurrency, peaking at ~100 MB
+of memory. Seed-only traces (a web app, a VM) come back in seconds.
 
 ```
 cloudmap trace my-app --live --allow-live
@@ -306,13 +422,8 @@ cloudmap trace my-app --live --allow-live
 
 **cloudmap runs as you.** It has no credentials of its own - every read goes through
 the Azure CLI with your `az login` token, so it sees exactly what your account can
-see and nothing more. Resource Graph filters by RBAC, so resources you cannot read
-simply do not appear (Azure raises no error for them - they are invisible, not
-denied). Deep reads your role does not allow (app settings, Key Vault values, AKS
-manifests) fail visibly instead: cloudmap **reports the gap** on the map rather than
-silently dropping edges, and warns when a scan is truncated - so a small graph on a
-low-privilege account reads as "this is what I was allowed to see", not "this is
-everything".
+see and nothing more. What that means in practice, per permission level, is in
+[What you will see - and what you won't](#what-you-will-see---and-what-you-wont).
 
 <details>
 <summary><b>Flags, enrichment and the subscription pin</b></summary>