wesmac37/project-b-vm-baseline-compliance

# Azure VM 基线与合规性工具包 [](https://github.com/example/project-b-vm-baseline-compliance/actions/workflows/powershell-ci.yml)     一款 PowerShell 工具包，用于根据安全/运营基线审计 Azure VM — 包括标记、网络安全组 (NSG) 关联、备份状态、监控状态、磁盘设置和身份设置 — 并生成包含修复指导的专业 Markdown/CSV 合规报告。通过 `-SimulationMode` 可完全离线运行，实现 **零 Azure 成本或凭据**。 ## 业务问题 企业需要可重复、可审计的证据来证明 VM 满足安全/运营基线。在少量 VM 之外，手动查看 Azure 门户无法扩展，而且临时脚本几乎无法生成安全或合规审查实际可用的产物。该工具包将“此 VM 是否合规？”转化为一个结构化、版本化、可测试的规则引擎，每次都生成相同的报告 —— 这是基础设施即代码的基础。 ## 架构概述 `Get-VmBaselineTarget` 将目标 VM 对象（来自实时 Azure 或模拟数据）解析为统一的格式。六个独立的规则函数分别针对一个 VM 评估一条基线规则。`Invoke-VmBaselineAudit` 编排所有规则对所有 VM 的评估，而 `Export-VmBaselineReport` 将结果渲染为 Markdown/CSV。有关完整的分解说明，请参阅 [docs/architecture.md](docs/architecture.md) 及下方的图表。 ``` flowchart TD A[audit-vm-baseline.ps1] --> B{-SimulationMode?} B -- true --> C[sample-vm-inventory.json] B -- false --> D[Get-AzVM + NIC/NSG/Extension enrichment] C --> E[Invoke-VmBaselineAudit] D --> E E --> F[6 baseline rules x N VMs] F --> G[Export-VmBaselineReport] G --> H[.md + .csv reports] F --> I{High-severity Fail?} I -- Yes --> J[Exit code 1] I -- No --> K[Exit code 0] ``` ## 前置条件 - PowerShell 7.0 或更高版本 (`pwsh`)。 - [Pester](https://pester.dev/) 5.0+（仅在运行测试套件时需要）。 - **模拟模式：** 无需其他条件。不需要 Azure 账户、订阅或凭据。 - **仅限实时模式：** 需要 [Az PowerShell module](https://learn.microsoft.com/powershell/azure/)、经过身份验证的会话 (`Connect-AzAccount`) 以及对目标订阅/资源组至少具有 **Reader** 角色。 ## 基线规则 每条规则的完整细节、检查逻辑和修复指南位于 [docs/baseline-rules.md](docs/baseline-rules.md) 中。摘要： | 规则 | 严重性 | |---|---| | 标记 (`Environment`, `Owner`, `CostCenter`, `Application`) | Medium | | NSG 关联 | High | | 备份状态 | High | | 监控状态 | Medium | | 磁盘设置 (SKU + encryption at host) | Medium | | 身份设置 (Managed Identity) | High | ## 运行前必须修改的内容（仅限实时模式） 模拟模式完全无需修改。对于实时模式，请替换以下占位符： - `-SubscriptionId` — 您真实的 Azure 订阅 ID（特意未提供默认值）。 - `-ResourceGroupName` — 作为审计范围的资源组。 - `config/baseline.config.psd1` — 调整 `RequiredTags`、`AllowedOsDiskSkus`、`AllowedIdentityTypes` 等，以匹配您组织的实际策略（自带的值是合理的默认值，而非强制要求）。 ## 示例命令 ### 模拟模式（推荐的默认设置 — $0 成本，无需凭据） ``` # 审计全部 5 个样本 VM；退出代码为 1，因为有一个 VM 故意未通过 High-severity 规则 pwsh ./scripts/audit-vm-baseline.ps1 # 从样本数据中审计单个 VM pwsh ./scripts/audit-vm-baseline.ps1 -VMName 'vm-web01-prod' # 以零风险预览 safe tag remediation pwsh ./scripts/remediate-vm-baseline.ps1 -SimulationMode -WhatIf ``` ### 实时模式 ``` Connect-AzAccount pwsh ./scripts/audit-vm-baseline.ps1 -SimulationMode:$false ` -SubscriptionId '00000000-0000-0000-0000-000000000000' ` -ResourceGroupName 'rg-contoso-prod-web' pwsh ./scripts/remediate-vm-baseline.ps1 ` -SubscriptionId '00000000-0000-0000-0000-000000000000' ` -ResourceGroupName 'rg-contoso-prod-web' -WhatIf ``` ## 验证工作流 ``` Install-Module -Name Pester -MinimumVersion 5.0.0 -Scope CurrentUser -Force Invoke-Pester -Path ./tests -Output Detailed ``` 有关完整的端到端验证清单（模块导入、PSScriptAnalyzer、模拟运行、测试套件、CI），请参阅 [docs/validation-checklist.md](docs/validation-checklist.md)。 ## 清理工作流（可选的实时测试 VM） 如果您使用了 `scripts/deploy-test-vm.ps1` 来部署可选的 `vm-baseline-test01` 演示 VM，请在完成后将其销毁： ``` pwsh ./scripts/cleanup-test-vm.ps1 -SubscriptionId '' -ResourceGroupName 'rg-baseline-demo' -WhatIf pwsh ./scripts/cleanup-test-vm.ps1 -SubscriptionId '' -ResourceGroupName 'rg-baseline-demo' -Confirm ``` ## 成本说明 - **模拟模式始终为 $0**。它读取 `sample-data/sample-vm-inventory.json` 且绝不调用 Azure。 - 可选的 `scripts/deploy-test-vm.ps1` 演示 VM 使用 `Standard_B1s`（规模小，通常在免费层适用时长内），没有公共 IP，使用受 IP 限制的 NSG，并标记有自动关机计划 — 映射了配套家庭实验室参考构建中使用的相同成本安全模式。它完全是可选的；此工具包中的任何内容都不需要它。 - 在实时演示之后，请务必运行 `cleanup-test-vm.ps1`，以避免持续产生费用。 ## 安全说明 - **审计** (`audit-vm-baseline.ps1`) 仅执行 *读取* 资源操作 — 在实时模式下，内置的 **Reader** 角色即已足够。它永远不会修改任何内容。 - **修复** (`remediate-vm-baseline.ps1`) 需要提升的权限（默认标记修复至少需要 **Tag Contributor**；若使用 `-IncludeIdentityRemediation` 则需要 **Virtual Machine Contributor**）。它默认采用 `-WhatIf` 安全且仅限追加的标记更改方式，并要求使用显式的启用的开关（`-IncludeIdentityRemediation`、`-Force`）来执行其他操作 — 请参阅 [docs/baseline-rules.md](docs/baseline-rules.md) 以确切了解哪些规则可以安全地自动化执行。 - 任何凭据、连接字符串或密钥都不会被嵌入到任何脚本中 — Identity Settings 规则的存在正是为了阻止在受审计的 VM 上出现这种模式。 ## 故障排除 有关常见问题（模块导入路径问题、缺少 Az 模块、意外退出代码、PSScriptAnalyzer 警告等），请参阅 [docs/troubleshooting.md](docs/troubleshooting.md)。 ## 如何演示此项目 **您可以在面试中完全离线运行此项目，无需实际的 Azure 订阅、无需凭据，也无需任何成本。** `-SimulationMode` 是默认设置，并使用与实时模式完全相同的规则引擎代码 — 它只是从 `sample-data/sample-vm-inventory.json` 而不是 `Get-AzVM` 获取 VM 数据。有关完整的演练脚本，请参阅 [docs/demo-guide.md](docs/demo-guide.md)，包括当被问及为什么存在模拟模式时该如何回答。 ``` pwsh ./scripts/audit-vm-baseline.ps1 # zero-cost, zero-credential demo ``` ## 这向雇主证明了什么 治理/合规即代码思维、报告纪律、安全/分层的修复模式，以及对基础设施工具的真正测试覆盖率。完整论述见 [docs/employer-value.md](docs/employer-value.md)。 ## 展现的技能 - PowerShell 模块设计（公共/私有分离、清单驱动导出、基于注释的帮助） - 熟练掌握 Azure Resource Manager 对象模型（VM、NIC、NSG、Managed Identity、Recovery Services vault） - 具有外部化配置的规则引擎 / 策略即代码架构 - Pester v5 测试编写（合规/不合规夹具、退出代码锁定） - GitHub Actions CI（PSScriptAnalyzer 把关、NUnit 产物上传、离线冒烟测试） - 技术写作（Mermaid 图表、规则表、Runbook 风格的指南） - 注重安全的自动化设计（最小权限、`-WhatIf` 默认设置、分层修复风险） ## 未来增强功能 - 将发现的问题直接导出为 Azure Policy initiative 定义，以进行原生强制执行。 - 具有合并报告的多订阅 / management-group 范围扫描。 - HTML 报告输出（除 Markdown/CSV 之外），用于仪表板嵌入。 - 将结果推送到 Log Analytics / Azure Monitor 以进行随时间变化的趋势跟踪。 - 使用现有的 `AllowedVmSizes` 配置值添加大小合规性规则。 ## 建议的仓库描述 ## 建议的仓库主题 `azure`, `powershell`, `compliance`, `security-baseline`, `governance`, `pester`, `devops`, `cloud-security`, `az-104`, `reporting` ## 面向招聘者的摘要 本项目是一个基于 PowerShell 的 Azure 虚拟机合规性审计工具。它根据六项真实的安全/治理规则（标记、网络安全、备份、监控、磁盘加密和身份）检查 VM，生成安全或审计团队实际可用的专业报告 — 并且它包含自己的自动化测试套件和 CI 流水线。关键是，它可以在无需访问实际 Azure 订阅的情况下进行完整演示，这使得在面试环境中进行讲解变得非常容易。 ## 许可证 [MIT](LICENSE)

标签：AI合规, Azure, DevSecOps, IPv6, Libemu, PowerShell, 上游代理, 云安全审计, 基线配置