OmarMokraniG/azure-estate-exporter
GitHub: OmarMokraniG/azure-estate-exporter
一个 PowerShell 模块，用于对现有 Azure 资产进行自动化清点、架构图绘制和 Terraform 基准导出，帮助团队快速记录和逆向工程云环境。
Stars: 0 | Forks: 0
# azure-estate-exporter
`azure-estate-exporter` 是一个 PowerShell 7 模块，可连接到您已有读取权限的 Azure 租户或订阅，并生成：
1. **一份清单**，包含您的身份可见的每个资源，格式为 JSON 和易于阅读的 Markdown。
2. **架构图**（默认为 Mermaid，按需提供 Excalidraw）。
3. **一个单文件 HTML 仪表板**，可通过电子邮件发送给客户。
4. **一份现有基础设施的 Terraform HCL 基准**，通过 Microsoft 官方的 Azure 到 Terraform 导出工具 [`aztfexport`](https://github.com/Azure/aztfexport) 实现。
5. **任意两次运行之间的差异对比**，因此您可以将其用作持续的审计日志。
它专为需要快速且可重复地**记录、共享或逆向工程**现有 Azure 资产环境的 Microsoft 工程师、架构师、合作伙伴和客户而设计。
## 快速开始
```
# 1. 前提条件 — 完整列表请参见 docs/installation.md
# - PowerShell 7+
# - Azure CLI 2.60+（已执行 `az login`）
# - Terraform 1.5+
# - aztfexport（可选，仅在进行 Terraform 导出时需要）
# winget install Microsoft.Azure.aztfexport
# # 或者： go install github.com/Azure/aztfexport@latest
# 2. 克隆并导入
git clone https://github.com/OmarMokraniG/azure-estate-exporter.git
cd azure-estate-exporter
Import-Module ./src/AzureEstateExporter
# 3. 针对当前选定的 subscription 运行
Export-AzureEstate -OutputPath ./out
# 4. 或者针对特定的 scope
Export-AzureEstate -SubscriptionId -ResourceGroup my-rg
# 5. 仅 Discovery（成本较低，不进行 Terraform 导出）
Export-AzureEstate -SubscriptionId -InventoryOnly
```
输出结果将存放在 `./out//` 中：
```
out/2026-05-25T13-00-00/
├── README.md # index of everything produced
├── index.html # ⭐ self-contained HTML dashboard (Mermaid embedded)
├── inventory.json # full normalized inventory
├── graph.json # nodes + inferred edges (relation + sourceProperty)
├── manifest.json # run metadata, collection confidence, per-resource SHA-256 hashes
├── errors.json # any per-resource failures
├── report/
│ └── report.md # human-friendly Markdown
├── diagrams/
│ ├── estate.mmd # Mermaid (default)
│ └── estate.excalidraw # Excalidraw (if -Diagram Excalidraw|Both)
├── terraform/
│ └── // # raw aztfexport output, one HCL folder per resource group
│ ├── main.tf
│ ├── provider.tf
│ └── ...
└── terraform-repo/ # ⭐ NEW in v0.3.1 — deployable Terraform baseline repo
├── README.md # how to use; baseline-not-clone warnings
├── .gitignore
├── backend.tf.example # Azure Storage backend stub
├── docs/
│ └── coverage.md # aggregated skipped resources across all RGs
└── infra/
└── / # self-contained Terraform working dir
├── main.tf
├── provider.tf # subscription_id = var.subscription_id
├── variables.tf
├── terraform.tfvars.example
├── bootstrap-import.ps1 # imports every resource into state
├── imports.md # raw `terraform import` list (bash users)
└── README.md
```
### 部署生成的基准
```
cd out//terraform-repo/infra/
Copy-Item terraform.tfvars.example terraform.tfvars # edit subscription_id
terraform init
./bootstrap-import.ps1 -WhatIf # dry run
./bootstrap-import.ps1 # imports every resource into local state
terraform plan # should say: No changes.
```
生成的代码库是一个**基准，而不是完美的克隆**。`aztfexport`
不会捕获机密、数据平面内容、运行时配置或不支持
的资源类型 —— 请参阅生成的代码库中的 `docs/coverage.md`。
您也可以重新打包任何现有的导出，而无需重新运行
`aztfexport`：
```
New-AzureEstateTerraformRepo -InputPath ./out/ -InitGit -Force
```
## 对比两次运行
```
Compare-AzureEstateRun -Previous out/2026-05-20T10-00-00 -Current out/2026-05-25T13-00-00
# 写入 out/2026-05-25T13-00-00/diff/changelog.{md,json}
```
仅输出发生更改的**属性路径** —— 绝不会复制值，
以避免泄露本应隐藏的脱敏内容。
## 无需 Azure 订阅即可试用
[`samples/`](samples/) 文件夹包含已脱敏的输出，您可以用它来测试
渲染器、编写下游工具或离线演示该项目。
## 🌐 Web UI (v0.3, 预览版)
更喜欢点击操作而不是编写脚本？[`web/`](web/) 文件夹包含一个 Vite + React
SPA，允许您使用 Entra 登录、浏览订阅和资源组，
并以可视化的方式探索您的资产环境：
- 交互式**资源映射图**（React Flow + 启发式连线 + Azure 风格的分类图标）
- 可排序、可筛选的**资源表格**，带有 JSON 侧边面板
- 一键式 **Terraform CLI 交接**，在本地运行 PowerShell 模块
```
# 1. 创建你自己的 Entra app registration（一次性操作，在你的 tenant 中）
pwsh -File scripts/create-app-reg.ps1
# 2. 配置 web app
cd web
cp .env.example .env.local
# 将打印出的 appId 粘贴到 VITE_AZURE_CLIENT_ID 中
# 3. 运行它
npm install
npm run dev
# 打开 http://localhost:5173
```
有关部署到 Azure Static Web Apps 的信息以及
关于 Microsoft 的 Azure 架构图标的说明（我们提供通用的开源
占位符；官方图标可选择下载），请参阅 [`web/README.md`](web/README.md)。
## 功能 (v0.4)
- ✅ **客户级评估** — 开箱即用地提供成本、Defender 安全得分、
策略合规性、公共暴露和 RBAC 发现结果。
- ✅ **可部署的 Terraform 基准代码库** (v0.3.1) — 克隆生成的
`terraform-repo/` 文件夹，运行 `bootstrap-import.ps1`，然后 `terraform plan`
会对现有资产环境显示 _No changes_。
### v0.4.0 的新特性
| 新产物 | 来源 |
|---|---|
| `cost.json` | Cost Management API (本月至今，按 RG + 服务分组) |
| `security.json` | Defender for Cloud 安全得分 + 最不健康的评估 |
| `policy.json` | ARG `policyresources` + Policy Insights 不合规行 |
| `exposure.json` | 源自清单 (NSG 0.0.0.0/0、公共存储/Key Vault、无 IP 限制的 App Service、公共 IP) |
| `access.json` | 源自收集的角色分配 (顶级特权主体、广泛范围授权、孤立分配) |
所有五个部分也会被渲染到 Markdown 报告和 HTML
仪表板中，并带有严重性标签和颜色编码的标题卡片。
退出开关：`-SkipCost`、`-SkipSecurity`、`-SkipPolicy`。
## 功能 (v0.2)
- ✅ **基于 Resource Graph** 的发现，涵盖一个订阅或您的身份可见的所有订阅。
- ✅ **自包含的 HTML 仪表板**，内嵌 Mermaid（可离线工作）。
- ✅ **`Compare-AzureEstateRun`** 将该工具转变为持续的审计日志。
- ✅ **可插拔的收集器**：以 ARG 为主 + 用于诊断设置、角色分配、锁的补充 ARM 收集器（扩展模型 —— 易于添加更多）。
- ✅ **可插拔的渲染器**：Markdown 报告、Mermaid 图表、Excalidraw 图表、HTML 仪表板、通过 `aztfexport` 生成的 Terraform。
- ✅ **丰富的连线**：每个推断出的连线都带有 `relation`（例如 `hosted-on`、`in-subnet`、`managed-by`）以及它所来源的 `sourceProperty` 路径。
- ✅ **收集置信度**：每个 `manifest.json` 都包含所使用的工具版本、查询范围以及各区域的错误计数。
- ✅ **模式**：`-InventoryOnly`、`-DiagramOnly`、`-TerraformOnly`，以及用于试运行的 `-WhatIf`。
- ✅ **默认对机密进行脱敏**，针对已知敏感的键（`password`、`secret`、`connectionString`、`key`、`sas`、`token`、`certificate`）。使用 `-NoRedact` 可禁用 *（不推荐）*。
- ✅ **确定性输出**，带有将资源 ID 映射到 Terraform 地址 + SHA-256 哈希的 `manifest.json`，以便重新运行产生稳定的差异。
- ✅ **容错能力**：单个损坏的资源组不会中止运行。
- ✅ **Devcontainer / Codespaces** 就绪 —— 请参阅 `.devcontainer/devcontainer.json`。
## 尚未包含在范围内的内容
请参阅 [`docs/coverage.md`](docs/coverage.md)。总体说明：
- **Entra ID** / Azure AD 对象 —— 不导出。
- **Management Groups** 和订阅/策略层级 —— 不导出。
- 用于虚拟机内配置的 **Ansible** playbook —— 在路线图中。
- 超出预算元数据的 **成本/计费数据** —— 超出范围。
- **`aztfexport` 不支持的资源类型** —— 在覆盖文档中列出。
## 存在的原因
一个经典问题：客户拥有一个无人拥有其 IaC 的 Azure 订阅。为了迁移、记录或交接它，您需要：
- 一份您可以信任的准确清单。
- 一张您可以放在演示文稿中的图片。
- 您可以开始进行迭代而不是从头编写的 Terraform。
对于非平凡的资产环境，手动执行此操作需要几天时间。该工具可在几分钟内为您提供一个坚实的基础，然后让人类审查并强化结果。
## 安全性
请阅读 [`SECURITY.md`](SECURITY.md)。TL;DR：
- 该工具需要您目标范围内的至少 **Reader** 权限。
- 生成的产物可能包含某些组织视为机密的资源元数据 —— **在共享或推送到公共代码库之前请进行审查**。默认的 `.gitignore` 已经排除了 `out/`。
- 切勿提交 `terraform.tfstate*`、`*.tfvars` 或未脱敏的导出内容。
## 相关工作
- [`Azure/aztfexport`](https://github.com/Azure/aztfexport) — 为我们的 Terraform 后端提供支持的官方 Azure 到 Terraform 导出工具。
- [Azure Resource Graph](https://learn.microsoft.com/azure/governance/resource-graph/) — 主要的清单引擎。
- [Excalidraw](https://excalidraw.com/) — 图表。
- [Terraformer](https://github.com/GoogleCloudPlatform/terraformer) — 替代导出工具；未来可作为后端插入。
## 许可证
[MIT](LICENSE)。
标签：AI合规, Azure, ECS, Libemu, Terraform, 占用监测, 基础设施管理, 架构图, 资产管理, 运维工具