cloudmap 1.2.0

Install · Demo · Wizard · Why · 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+. 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 - the repo ships a synthetic estate:

cloudmap trace contoso-web --from fixtures/contoso.json -o contoso-web.drawio

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

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:

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                              │
╰──────────────────────────────────────────────────────────────────────────────╯

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

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.

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

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