cloudmap 1.3.4

Install · Demo · Wizard · Why · What you'll see · How it works · Ask

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.

Install

pip install cloudmap

Python 3.9+, on Linux, macOS or Windows (CI runs all three). Two runtime dependencies (rich and questionary, both for the terminal UI). Live mode additionally needs the Azure CLI on your PATH. The optional AI passes need a local model server - ollama works out of the box, and any OpenAI-compatible server (LM Studio, llama.cpp, vLLM, LocalAI) works via two env vars:

export CLOUDMAP_LLM_URL=http://localhost:1234/v1/chat/completions   # your server
export CLOUDMAP_LLM_MODEL=<model name>                              # default: qwen2.5-coder:3b

git clone https://github.com/KatsaounisThanasis/cloudmap && cd cloudmap
pip install -e ".[dev]" && pytest

60-second demo

No Azure account needed - a synthetic estate ships inside the package:

cloudmap trace contoso-web --from demo -o contoso-web.drawio

Blast radius: 9 resources (0 external), 9 dependencies
╭─────────────────────────────── Depends on (6) ───────────────────────────────╮
│ 🌐 contoso-web                                                               │
│ ├── --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

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:

Blast radius: 16 resources (0 external), 15 dependencies
╭─────────────────────────────── Depends on (2) ───────────────────────────────╮
│ 🌐 app-spa-frontend                                                          │
│ ├── --calls--> 🌐 app-auth-service                                           │
│ │   ├── --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                            │
│     │   └── --connects-to--> 📦 eh-transactions                              │
│     ├── --calls--> 🌐 app-inventory-api                                      │
│     │   ├── --connects-to--> 🗄️ pg-inventory-prod                            │
│     │   └── --connects-to--> 📦 stinventoryprod                              │
│     └── --calls--> 🌐 app-orders-api                                         │
│         ├── --connects-to--> 📦 sb-enterprise                                │
│         ├── --connects-to--> 🗄️ redis-orders                                 │
│         └── --connects-to--> 🗄️ sql-orders-prod                              │
╰──────────────────────────────────────────────────────────────────────────────╯

What you get out

The --html viewer has a dark mode, edges colour-coded by relationship type (security / data / network), resource-group filters and search, SVG and PNG export, and direct links into the Azure portal.

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: 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?" 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 --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 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 --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 - 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:

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

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.

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):

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".

Types cloudmap cannot map honestly, and says so

Five types keep their dependencies somewhere Resource Graph does not return, and have no reader: Data Factory and Synapse (linked services are child resources Resource Graph does not index), Automation accounts (runbooks, variables, connections), Stream Analytics (inputs and outputs) and Databricks (secret scopes live in the workspace's own data plane).

Tracing one of these still works - it appears on maps, RBAC and ARM references resolve normally - but a blind spot is written on the map, because an empty result for a Data Factory is not evidence that the factory depends on nothing.

This list is short because it was checked rather than assumed. Logic Apps (definition), Container Apps (configuration), ML workspaces, Cognitive Services and API Management all return their config in properties, so the four generic channels find their dependencies with no special handling. App Service and AKS hide config too - they are the two that have readers.

Government, China and the other sovereign clouds

Supported, with nothing to configure. The DNS suffixes differ per cloud (vault.usgovcloudapi.net, vault.azure.cn, database.chinacloudapi.cn), but cloudmap does not read the service off the suffix: once a hostname resolves to a scanned resource, that resource's ARM type is what decides the edge kind. The HTML viewer's portal deep-links follow the cloud your account is in (portal.azure.us, portal.azure.cn, ...), taken from az account show.

The one place a suffix still matters is a host that resolves to nothing scanned: with no resource to consult, only the public-cloud suffixes are recognised by name, so an unresolved sovereign host is surfaced as a generic external reference rather than a categorised one. It is never dropped.

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).
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 trace contoso-web --from demo --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.

cloudmap ask <map.json> "<question>"

  --explain      also narrate the answer with a LOCAL model
  --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)

Live Azure

Fixtures are the default. Live mode is opt-in and 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. Do not point this at data you are not authorized to read.

One asterisk on "read-only": AKS manifests are read through az aks command invoke, which Azure implements by starting a short-lived pod in the cluster to 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. 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

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. What that means in practice, per permission level, is in What you will see - and what you won't.

  --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 workload; every app in scope when the seed is a data
                        service whose dependents hide in app config (Key Vault,
                        storage, SQL, Redis, ...); the seed alone for compute and
                        network resources, whose relationships ARM already returns;
                        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 propose extra edges, each
                        verified against scanned resources before it is trusted

export CLOUDMAP_ALLOW_SUBSCRIPTION=<subscription-id>   # optional

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

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

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