Blackvectra/NRG-Assessment-Tool
GitHub: Blackvectra/NRG-Assessment-Tool
面向 MSP 的 Microsoft 365 多租户只读安全评估框架，支持 195 项控制措施检查与多框架对标，自动生成客户就绪报告。
Stars: 1 | Forks: 0
# NRG-Assessment
**专为托管服务提供商 (MSP) 设计的只读 M365 安全评估框架。**
由 Matthew Levorson — NRG Technology Services / NextLayerSec LLC 开发
GitHub: [Blackvectra/NRG-Assessment-Tool](https://github.com/Blackvectra/NRG-Assessment-Tool)
[](docs/OPENSSF-BEST-PRACTICES.md)
[](docs/SECURE-DEVELOPMENT.md)
[](docs/VULNERABILITY-DISCLOSURE-POLICY.md)
[](SECURITY.md)
## 功能简介
通过委派身份验证（或供 MSP 批量运行的 GDAP）连接到 Microsoft 365 租户，收集所有 M365 服务的原始配置数据，评估 195 项安全控制措施，并生成包含框架引用的、可直接交付给客户的 HTML 和 Markdown 报告。
**零写入租户。设计上仅限只读。**
## 首次设置
在全新的机器上，运行一次此命令：
```
# 解压 zip 后
cd C:\path\to\NRG-Assessment-v4.6.5
.\Install-NRGPrerequisites.ps1
```
这将安装/固定所需的 PowerShell 模块（EOM 固定为已知稳定的 3.2.0 版本），设置执行策略，解除文件阻止，并在您需要 XLSX 合规性矩阵时安装 Python+openpyxl。使用 `-SkipPython` 可跳过 Python 安装。
## 快速开始
### 前置条件
```
# 安装所需模块（确切版本 — 供应链锁定）
Install-PSResource -Name Microsoft.Graph.Authentication -Version 2.20.0 -TrustRepository
Install-PSResource -Name ExchangeOnlineManagement -Version 3.4.0 -TrustRepository
Install-PSResource -Name MicrosoftTeams -Version 6.4.0 -TrustRepository
Install-PSResource -Name Microsoft.Online.SharePoint.PowerShell -Version 16.0.24720.12000 -TrustRepository
Install-PSResource -Name Pester -Version 5.6.1 -TrustRepository
```
### 单租户运行
```
# 克隆 repo
git clone https://github.com/Blackvectra/NRG-Assessment-Tool
cd NRG-Assessment-Tool
# 运行评估
.\Invoke-NRGAssessment.ps1 -UserPrincipalName admin@client.com
# 输出位于 .\output\\
```
### 快速分诊、增量对比与 CI 退出代码
适用于自动化 pipeline 和快速分诊：
```
# 快速扫描 — 仅限 Critical + High controls（更快，噪音更低）
.\Invoke-NRGAssessment.ps1 -UserPrincipalName admin@client.com -Quick
# 与先前的 baseline JSON 进行比较 — 生成 delta report
# （分数差异，发现 regressions，CA / role / OAuth / DMARC drift）
.\Invoke-NRGAssessment.ps1 -UserPrincipalName admin@client.com `
-BaselineResults .\output\client\20260415-results.json
# CI / Task Scheduler 阈值 — 当 posture 发生 drift 时非零退出
# Exit 10 = critical 阈值，11 = high 阈值，12 = score 阈值
.\Invoke-NRGAssessment.ps1 -UserPrincipalName admin@client.com `
-FailOnCritical 1 -FailOnHigh 5 -FailOnScoreBelow 70
```
每次运行现在都会将租户划分为一个**租户安全成熟度层级**（初始 / 发展 / 定义 / 管理 / 优化）——该标签会显示在控制台摘要中，并嵌入到 JSON metadata 中供下游仪表板使用。
### MSP 批量运行 (GDAP)
```
# 1. 将你的客户端添加到 Config\clients.json（需要 TenantId + DelegatedOrg）
# 2. 通过 GDAP 关系，一次浏览器登录即可覆盖所有租户
.\Invoke-NRGBatchAssessment.ps1
# 运行单个客户端
.\Invoke-NRGBatchAssessment.ps1 -OnlyClient example.com
# 预览将要运行的内容
.\Invoke-NRGBatchAssessment.ps1 -WhatIf
```
### 本地 Web GUI
对于喜欢点击操作而不是输入命令的操作员，`-Web` 会启动一个本地浏览器
GUI，而不是终端流程。该 GUI 是一个基于 Pode 的回环服务器
运行在 `127.0.0.1:8765`；它从不向网络暴露自己，也绝不将
租户数据发送到任何地方。选择一个租户，点击“Run scan”，实时查看进度，
并直接内联查看现有的 HTML 报告。
```
# 一次性安装（免费，基于 MIT 许可的 PSGallery 模块）
Install-Module Pode -MinimumVersion 2.10.0 -Scope CurrentUser
# 启动 GUI（自动打开默认浏览器）
.\Invoke-NRGAssessment.ps1 -Web
# 如果 8765 端口被占用，请使用其他端口
.\Invoke-NRGAssessment.ps1 -Web -WebPort 9000
```
GUI 使用与 CLI 相同的 `Config/clients.json`，扫描通过
相同的模块函数运行，并且报告会生成在同一个 `./output/` 目录中——
因此 CLI 和 GUI 工作流可以自由混合使用。
## 架构
```
Invoke-NRGAssessment.ps1 ← Entry point (validated params, try/finally)
Invoke-NRGBatchAssessment.ps1 ← GDAP batch runner (one auth, all tenants)
NRG-Assessment.psm1 ← Module loader (recursive dot-source, path traversal check)
NRG-Assessment.psd1 ← Module manifest (220 exports, dependency declarations)
Lib/ ← Shared infrastructure
Add-NRGFinding.ps1 State management (findings, exceptions, coverage, raw data)
Connect-NRGServices.ps1 Auth (browser/device code, process-scoped MSAL)
ConvertTo-NRGHtmlSafe.ps1 XSS prevention (all tenant data escapes through here)
Get-NRGControlDefinitions.ps1 controls.json loader + content validation
Collectors/ READ-ONLY — raw data collection, no scoring
AAD/ (6 files) Auth policies, CA, users+MFA, roles, PIM, identity governance
EXO/ (3 files) Mailbox config + connection filter, Defender policies
DNS/ (1 file) SPF, DKIM, DMARC, MTA-STS, TLS-RPT, DNSSEC
SharePoint/ Teams/ Purview/
Intune/ PowerPlatform/ (5 files)
Evaluators/ SCORING ONLY — reads raw data, writes findings
Test-NRGControl-AAD.ps1 32 controls
Test-NRGControlEXO.ps1 21 controls
Test-NRGControlDNS.ps1 6 controls
Test-NRGControlDefender.ps1 16 controls
Test-NRGControlSharePoint.ps1 17 controls
Test-NRGControlTeams.ps1 18 controls
Test-NRGControlPurview.ps1 14 controls
Test-NRGControlIntune.ps1 13 controls
Test-NRGControlPowerPlatform.ps1 6 controls
Publishers/
Publish-NRGAssessmentHTML.ps1 Interactive HTML report with exec summary + findings
Publish-NRGAssessmentSummary.ps1 Markdown report for OneNote / GitHub
Config/
controls.json 195 control definitions + framework citations
frameworks.json CIS, SCuBA, NIST, CMMC, MITRE metadata
clients.json MSP client registry (TenantId + GDAP config)
Testing/
NRG.Security.Tests.ps1 100 Pester tests (OWASP/ASVS static + runtime)
.github/workflows/security.yml CI: PSScriptAnalyzer + Pester + Gitleaks + TruffleHog
```
## 控制项覆盖范围
**跨 9 项工作负载的 195 项控制措施**
| 工作负载 | 控制项 | 核心领域 |
|---|---|---|
| Entra ID (AAD) | 32 | MFA、传统身份验证、CA 策略、PIM、来宾访问、SSPR、应用授权、应急访问 |
| Exchange Online | 21 | 审计、SMTP 身份验证、自动转发、DKIM、防钓鱼、现代身份验证、DMARC |
| DNS Email Auth | 6 | SPF、DKIM、DMARC 强制执行、MTA-STS、TLS-RPT、DNSSEC |
| Defender | 16 | 安全附件/链接、欺骗情报、ZAP、隔离、预设策略 |
| SharePoint | 17 | 外部共享、OneDrive 同步、自定义脚本、链接过期、来宾过期 |
| Teams | 18 | 联盟、消费者账户、会议大厅、外部聊天、应用治理 |
| Purview | 14 | 统一审计日志、DLP、敏感度标签、保留策略、内部风险 |
| Intune | 13 | 设备合规性、BitLocker、EDR、ASR 规则、MAM、条件启动 |
| Power Platform | 6 | 租户隔离、DLP 策略、连接器分类、治理 |
**严重性分布：** 9 项严重 · 59 项高危 · 52 项中危 · 23 项低危
**每项控制措施的框架引用：** CIS M365 v6.0.1 · CISA SCuBA v1.7.1 · NIST SP 800-53 Rev 5 · CMMC 2.0 L2 · MITRE ATT&CK v16.1
## 安全加固
该工具针对其评估的威胁进行了安全加固。每个生产文件都具有：
- `#Requires -Version 7.0` — 阻止 PS 5.1 MSHTML 注入 (CVE-2025-54100)
- `Set-StrictMode -Version Latest` — 在运行时捕获未初始化的变量
- `$ErrorActionPreference = 'Stop'` — 杜绝静默错误吞噬
- `-LiteralPath` 用于所有文件操作 — 无通配符展开 (OWASP A01)
- `-Encoding utf8` 用于所有文件写入 — 显式编码 (ASVS V16.2.3)
- 对每个参数进行输入验证 — UPN、域名、路径、controlId (ASVS V5.1.3)
- `try/finally` 会话清理 — 确保发生任何错误时都能断开连接 (ASVS V7.3.2)
- 在入口处强制执行 TLS 1.2/1.3 — 不允许降级 (ASVS V11.2.2)
- 进程级 MSAL token 缓存 — 杜绝跨会话 token 泄露
- 预防 XSS — 所有租户数据在输出 HTML 之前都会通过 `ConvertTo-NRGHtmlSafe` 处理
**controls.json 内容验证** — 在任何评估器运行之前，加载器会根据白名单验证每个控制项的严重性、工作负载、类别、ControlId 格式、前缀/工作负载一致性、Remediation 中的注入模式以及重复 ID。失败即关闭：任何违规都会引发异常抛出。
**77 项自动化 Pester 测试** 涵盖了上述所有内容 — 通过 GitHub Actions 在每次推送时进行静态分析。
```
# 运行 security test suite
Invoke-Pester ./Testing/NRG.Security.Tests.ps1 -Output Detailed
```
## 客户注册表 (MSP)
编辑 `Config\clients.json` 以添加租户：
```
{
"ClientName": "Client Name",
"TenantDomain": "client.com",
"TenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"DelegatedOrg": "client.onmicrosoft.com",
"DnsDomains": ["client.com"],
"SkipPurview": false,
"SkipPowerPlatform": true,
"Active": true
}
```
从以下位置获取 TenantId：**Entra ID > Overview > Tenant ID**
从以下位置获取 DelegatedOrg：**Partner Center > Customers > client > Domains**（查找 `.onmicrosoft.com` 域）
在批量运行器访问客户租户之前，GDAP 关系必须在 Partner Center 中处于活跃状态。
## CI/CD
GitHub Actions 会在每次推送到 `main` 分支时运行：
| 任务 | 工具 | 检查内容 |
|---|---|---|
| PSScriptAnalyzer | PowerShell 静态分析 | 代码质量、语法、反模式 |
| Pester | NRG.Security.Tests.ps1 | 77 项 OWASP/ASVS 安全不变量 |
| Gitleaks | 密钥检测 | 凭据、token、API 密钥 |
| TruffleHog | 深度密钥扫描 | 所有提交中的已验证密钥 |
| SBOM | CycloneDX cdxgen | 发布时的软件物料清单 |
## 许可证
内部使用 — NRG Technology Services / NextLayerSec LLC。未授权重新分发。
*NRG-Assessment v4.11.1 · 195 项控制措施 · 231 个导出函数 · 191 项 Pester 测试*
标签：AI合规, IPv6, Libemu, Microsoft 365, PowerShell, 多租户管理, 安全基线评估, 自动化报告, 逆向工具