azure-subscription-snapshot

# Azure Subscription Snapshot > Deterministic, exhaustive snapshot of an Azure subscription — JSON, Mermaid > diagrams, HTML report, and a Copilot/MCP-ready knowledge base. [](https://github.com/jmfloreszazo/azure-subscription-snapshot/actions/workflows/ci.yml) [](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) [](https://learn.microsoft.com/cli/azure/install-azure-cli) [](LICENSE) [](CONTRIBUTING.md) Built for the *"I just inherited an Azure subscription, tell me everything"* moment: resources, configuration, RBAC, identities, policies, locks, deployments, networking, diagnostics, per-service deep dives. Output is **deterministic** (sorted-key JSON, alphabetical iteration) so two snapshots of an unchanged subscription produce **identical files** — drop them in git and diff over time. ## Table of contents - [Azure Subscription Snapshot](#azure-subscription-snapshot) - [Table of contents](#table-of-contents) - [What you get](#what-you-get) - [Why another inventory tool?](#why-another-inventory-tool) - [Requirements](#requirements) - [Quickstart](#quickstart) - [Common parameters](#common-parameters) - [Try it on a representative demo workload](#try-it-on-a-representative-demo-workload) - [Output layout](#output-layout) - [Determinism](#determinism) - [Use it from Copilot Chat (Azure MCP Server)](#use-it-from-copilot-chat-azure-mcp-server) - [Specialized chat modes \& prompts](#specialized-chat-modes--prompts) - [Drift detection](#drift-detection) - [Security \& privacy](#security--privacy) - [Limitations](#limitations) - [Troubleshooting](#troubleshooting) - [FAQ](#faq) - [Project layout](#project-layout) - [Contributing](#contributing) - [Roadmap](#roadmap) - [License](#license) ## What you get After a single run you have: - A **full JSON snapshot** under [`out/`](#output-layout) — inventory, per-resource detail, RBAC by principal, network topology, policies, locks, diagnostics, ARM exports, last 90 days of activity. - A **relationship graph** (`out/10-graph/`) with stable `nodes.json` / `edges.json` for blast-radius / orphan analysis. - **Mermaid diagrams** (`out/11-diagrams/`) for architecture, network, identity and resource types — render them in any Markdown viewer. - A **self-contained HTML report** (`out/12-report/report.html`) with embedded diagrams and tables — no external assets. - A **Copilot/MCP knowledge base**: pre-wired Azure MCP server, four specialized chat modes, and ready-made prompts so any LLM-powered IDE (VS Code, Cursor, Claude Desktop, Continue.dev) can answer questions grounded in the dump with citations. - A **drift differ** that compares two snapshots and risk-tags every change. ## Why another inventory tool? Azure already has excellent inventory, governance, compliance, query and IaC export tools. **Azure Subscription Snapshot** is intentionally narrower: it creates a deterministic, git-friendly snapshot that is easy for humans and AI agents to review, diff and cite. | Need | Azure Subscription Snapshot | [ARI][ari] | [AzGovViz][azgov] | [Steampipe][steampipe] | [azqr][azqr] | [CloudQuery][cloudquery] | [aztfexport][aztfexport] | | --- | :--: | :--: | :--: | :--: | :--: | :--: | :--: | | Full subscription inventory | ✅ | ✅ | ✅ | ✅ (queries) | partial | ✅ (to DB) | partial | | **Deterministic** sorted-key JSON for git diffs | ✅ | ❌ | ❌ | n/a | ❌ | n/a | ❌ | | Relationship graph (`nodes.json`/`edges.json`) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Mermaid diagrams (architecture, network, RBAC) | ✅ | draw.io | ❌ | ❌ | ❌ | ❌ | ❌ | | Self-contained HTML report | ✅ | Excel | ✅ | ❌ | Excel | ❌ | ❌ | | **Copilot Chat / MCP integration** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Specialized agent chat modes | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Drift differ between snapshots | ✅ | ❌ | partial | query-it-yourself | ❌ | query-it-yourself | Terraform plan | | Per-service deep dives (AKS/KV/SQL/ACA…) | ✅ | partial | partial | ✅ | ❌ | ✅ | partial | | ARM export per RG | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | **Bicep reconstruction from the dump** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Terraform export | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Single-file dependency-light entrypoint | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | [ari]: https://github.com/microsoft/ARI [azgov]: https://github.com/JulianHayward/AzGovViz [steampipe]: https://github.com/turbot/steampipe-plugin-azure [azqr]: https://github.com/Azure/azure-quick-review [cloudquery]: https://github.com/cloudquery/cloudquery [aztfexport]: https://github.com/Azure/aztfexport ## Requirements - [PowerShell 7+](https://learn.microsoft.com/powershell/scripting/install/installing-powershell) (`pwsh`) - [Azure CLI 2.60+](https://learn.microsoft.com/cli/azure/install-azure-cli) (`az`) - The `resource-graph` extension (auto-installed on first run). - Subscription-level **`Reader`** role (the dump is read-only). - For complete RBAC visibility: `Microsoft.Authorization/*/read`. - Optional: [Bicep CLI](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) if you intend to run the demo or use the `reconstruct-iac` prompt locally. ## Quickstart ```pwsh # 1. Sign in az login az account set --subscription "<sub-id-or-name>" # 2. Dump the whole subscription with diagrams + HTML report ./Invoke-AzureSnapshot.ps1 -OutputDir .\out -GenerateReport # 3. Or scope it to a single resource group ./Invoke-AzureSnapshot.ps1 -ResourceGroup rg-prod -OutputDir .\out -GenerateReport # 4. Include app settings & connection strings (controlled environments only) ./Invoke-AzureSnapshot.ps1 -OutputDir .\out -IncludeSensitive ``` Open `out/12-report/report.html` when it finishes. ### Common parameters | Parameter | Default | Description | | ------------------- | ---------------- | ------------------------------------------------------------ | | `-OutputDir` | `.\out` | Folder where the snapshot is written. | | `-ResourceGroup` | *(all)* | Limit the dump to one resource group. | | `-GenerateReport` | *off* | Build `out/12-report/report.html` after the JSON layer. | | `-IncludeSensitive` | *off* | Capture app settings, connection strings, function keys. | | `-MaxParallel` | `4` | Concurrent `az` calls. Increase for large subscriptions. | Run `./Invoke-AzureSnapshot.ps1 -?` for the full surface. ## Try it on a representative demo workload The [`demo/`](demo/) folder ships a Bicep-based, multi-service deployment (VNet + private endpoints, App Service, SQL serverless, Container Apps, ACR, Key Vault, Storage, Service Bus, Log Analytics, App Insights, RG lock, policy assignment) so you can see every diagram light up. ```pwsh $me = az ad signed-in-user show --query id -o tsv $upn = az ad signed-in-user show --query userPrincipalName -o tsv ./demo/Deploy-Demo.ps1 -SqlAdminObjectId $me -SqlAdminLogin $upn ./Invoke-AzureSnapshot.ps1 -ResourceGroup rg-azure-snapshot-demo -OutputDir .\out -GenerateReport ./demo/Remove-Demo.ps1 -Force # tear down (removes lock, deletes RG, purges KV) ``` See [`demo/README.md`](demo/README.md) for cost estimates and parameter details. ## Output layout ```text out/ ├─ 00-context/ # account, tenant, providers, tool versions ├─ 01-subscription/ # subscription-level RBAC, policies, locks, budgets ├─ 02-resource-groups/ ├─ 03-inventory/ # resources.json (full Resource Graph) + type-summary ├─ 04-resources/ # per-resource detail, diagnostics, RBAC ├─ 05-services/ # AKS, KV, Storage, Web, SQL, Cosmos, APIM, ACA, SB, EH… ├─ 06-network/ # topology, peerings, NSG, route tables, private endpoints ├─ 07-identity/ # managed identities, role assignments by principal ├─ 08-activity-log/ # last 90 days ├─ 09-deployments/ # ARM/Bicep export per RG + deployment history ├─ 10-graph/ # relationship graph (nodes.json, edges.json) ├─ 11-diagrams/ # Mermaid: architecture, network, identity, types ├─ 12-report/ # report.html (self-contained) ├─ _manifest.json # generation metadata ├─ _errors.log # non-fatal failures (insufficient RBAC, throttling…) └─ _run.log # every az invocation ``` JSON Schemas for the most-consumed files live in [`schemas/`](schemas/) — point any LLM/validator at them before reasoning over the dump. ## Determinism - JSON serialized with **sorted keys** (`ConvertTo-DeterministicJson`). - Stable iteration order (alphabetical by id). - Fixed retry backoff (no jitter). - Timestamps confined to `_manifest.json` and logs. Two dumps of an unchanged subscription produce **identical files** (modulo timestamps), so you can `git diff` to track drift. ## Use it from Copilot Chat (Azure MCP Server) [`.vscode/mcp.json`](.vscode/mcp.json) registers the official [`@azure/mcp`](https://github.com/Azure/azure-mcp) server. Combined with [`.github/copilot-instructions.md`](.github/copilot-instructions.md) and the files in [`prompts/`](prompts/), Copilot will: - Read facts from `out/` first (the source of truth). - Use the Azure MCP server to verify or extend when data is stale. - Cite which file (or MCP tool) it relied on. Try prompts like: - *"Which resources expose a public IP and what NSGs protect them?"* - *"Who has Owner on the Key Vault?"* - *"Render the dependency graph for the App Service."* - *"What changed in the last 90 days?"* ## Specialized chat modes & prompts This is what makes Azure Subscription Snapshot more than a dumper. The repo ships with ready-made Copilot **chat modes** and **prompts** so any LLM-powered IDE can work the dump without prompt engineering on your side. | Chat mode (`.github/chatmodes/`) | When to pick it | | -------------------------------- | -------------------------------------------------------------- | | `inheritance-auditor` | You inherited a subscription and need a tour. | | `security-reviewer` | Prioritized security findings with citations. | | `cost-hunter` | Find waste; never deploys. | | `drift-detective` | Diff two dumps, classify changes by risk. | | Prompt (`prompts/`) | What it does | | --- | --- | | `azure-snapshot-analyze` | Generic Q&A grounded in `out/`. | | `find-orphans` | Inventory ⨉ edges ⨉ activity-log to detect abandoned resources. | | `blast-radius` | Impact graph for a single resource. | | `reconstruct-iac` | Starter **Bicep** from `out/09-deployments/`. | See [`AGENTS.md`](AGENTS.md) for the agent contract and [`docs/PLAYBOOK.md`](docs/PLAYBOOK.md) for ready-made questions. ## Drift detection ```pwsh ./scripts/Compare-AzureSnapshots.ps1 -Old .\out-baseline -New .\out -OutFile .\drift.json ``` `drift.json` is deterministic and ignores volatile fields (`etag`, `lastModifiedTime`, `provisioningState`). Each change is risk-tagged (`breaking` / `risky` / `safe` / `review`) and feeds the **Drift Detective** chat mode for a human-readable report. ## Security & privacy - **Read-only by design.** No mutating Azure call is made — even with `-IncludeSensitive`. The script never writes to Azure. - **Secrets stay in Key Vault.** The dump captures Key Vault metadata and RBAC, but **never** secret values. Even `-IncludeSensitive` only adds what Azure already returns through `az` (App Settings, function keys, connection strings as displayed by the platform). - Files matching `*.SENSITIVE.json` are written **only** when `-IncludeSensitive` is passed and are added to [`.gitignore`](.gitignore) by default. - Threat model and detailed handling: [`SECURITY.md`](SECURITY.md). ## Limitations - `az group export` (ARM) caps at ~200 resources per RG and is not guaranteed to be redeployable. - Some services need extra calls beyond what the dump covers (historical logs, runtime state). PRs welcome. - If you lack permissions on a resource, the failure is captured in `_errors.log` and the dump continues. - Tenants with thousands of resources may need `-MaxParallel` tuning and a long-running shell. - Cross-tenant Lighthouse delegations are not modelled in the graph. ## Troubleshooting | Symptom | Fix | | --- | --- | | `az` not on PATH after `winget install` | Restart the shell, or prepend the Azure CLI `wbin` folder to `PATH`. | | `az login` MFA loop | `az logout` then `az login --tenant <tenantId>`. | | `az graph query` hangs | Run `az extension add -n resource-graph` once. | | Demo region has no SQL capacity | Pass `-SqlLocation northeurope` or another available region. | | SQL re-deploy hits a soft-deleted server | The demo uses a hashed name to avoid this; otherwise wait or recover the server. | | `_errors.log` non-empty | Open the file; usually missing RBAC. Add `Reader` and re-run. | | HTML report won't open | Ensure `-GenerateReport` was passed, then re-run. | ## FAQ **Is this safe to run in production?** Yes. It only reads. Without `-IncludeSensitive` the dump never even asks for app settings or connection strings. **How long does a full dump take?** A subscription with ~200 resources typically completes in **2–4 minutes** on a developer laptop. Per-resource calls are parallelised (`-MaxParallel`). **Why PowerShell instead of Python/Go?** `az` already requires Python. PowerShell 7 is cross-platform, ships with sorted-key JSON support out of the box, and lets the script stay dependency-free. **Can I run it from CI?** Yes. Use a federated identity / service principal with `Reader`. The included [GitHub Actions workflow](.github/workflows/ci.yml) lints the code and validates schemas; an example "snapshot on schedule" workflow is on the [roadmap](#roadmap). **Can it dump multiple subscriptions?** Run it once per subscription with different `-OutputDir`. Aggregating the graph across subs is on the [roadmap](#roadmap). **How do I customise what gets collected?** [`lib/Collectors.ps1`](lib/Collectors.ps1) has one `Invoke-Phase-*` function per phase. Add or skip phases by editing [`Invoke-AzureSnapshot.ps1`](Invoke-AzureSnapshot.ps1)'s phase list. See [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-per-service-extractor). **Does it support Azure Government / China?** The dump uses whichever endpoint `az` is configured for, so yes — but it hasn't been tested there. Reports welcome. ## Project layout ```text . ├─ Invoke-AzureSnapshot.ps1 # entry point (13 phases) ├─ lib/ │ ├─ Common.ps1 # az wrapper, deterministic JSON, helpers │ ├─ Collectors.ps1 # one Invoke-Phase-* per phase │ ├─ Graph.ps1 # relationship graph + Mermaid generators │ └─ Report.ps1 # self-contained HTML report ├─ demo/ # Bicep workload to validate the tool ├─ prompts/ # Copilot/MCP prompt files ├─ scripts/ │ └─ Compare-AzureSnapshots.ps1 # deterministic drift differ ├─ schemas/ # JSON Schemas for manifest, inventory, edges ├─ docs/ │ └─ PLAYBOOK.md # ready-made questions and workflows ├─ AGENTS.md # agent contract for any LLM-powered IDE ├─ .github/ │ ├─ chatmodes/ # specialized Copilot chat modes │ ├─ ISSUE_TEMPLATE/ # bug + feature request forms │ ├─ copilot-instructions.md │ ├─ dependabot.yml │ ├─ pull_request_template.md │ └─ workflows/ci.yml └─ .vscode/mcp.json # Azure MCP server registration ``` ## Contributing PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The dump is intentionally small and dependency-free; please preserve that. By contributing you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Security issues → see [SECURITY.md](SECURITY.md). Do not open public issues for vulnerabilities. Release notes → [CHANGELOG.md](CHANGELOG.md). ## Roadmap - Multi-subscription / management-group aggregation. - Resource Graph KQL query catalogue exposed as MCP tools. - Optional cost roll-up driven by `azure_mcp.pricing`. - "Snapshot on schedule" GitHub Action template. - Optional Terraform reconstruction prompt (Bicep is the default). ## License [MIT](LICENSE) © José María Flores Zazo.