调查零信任评估连接失败、检查被跳过、运行缓慢、依赖项冲突以及报告问题。 从受影响的阶段开始,如果特定于症状的检查无法解决问题,则收集诊断。 保留 PowerShell 会话和可用诊断,以供调查。
在开始之前,请收集评估信息、PowerShell 版本、运行范围和错误摘要。 请参阅先决条件,获得您所需的信息。
Prerequisites
- 评估 PowerShell 会话(如果仍可用)或其生成的诊断。
- 评估和 PowerShell 版本、所选的支柱和测试 ID、受影响的阶段和错误摘要。
故障排除清单
在更改权限、依赖项或超时之前确定失败阶段。
确定受影响的阶段
确定哪个评估阶段失败,以便你可以选择相关的诊断。
- 查看连接消息和 每运行诊断文件 ,以确定连接、导出、数据库创建、测试或报表处理期间是否出现问题。
- 记录评估版本、PowerShell 版本、所选支柱和测试 ID,以及已脱敏的错误摘要。
- 如果可能使用继续,请保留已完成的导出和数据库。
检查访问和覆盖范围
使用症状表选择下一个检查。 成功的 Microsoft Graph 连接并不代表所有其他服务都已建立,跳过某项检查并不能证明配置是安全的。
| 问题 | 需要检查的事项 |
|---|---|
| Graph 同意或角色验证失败。 | 将授予与 Get-ZtGraphScope、激活所需的用户角色或配置应用权限进行比较,然后重新连接。 新的软件包可能需要额外同意。 |
| 服务无法连接,或者测试被跳过。 | 检查服务的角色、许可证、平台和连接消息。 请参阅 连接指南。 |
| 保护、标签、数据丢失防护(DLP)或搜寻检查返回授权错误。 | 检查命令或 API 的工作负荷角色分配和数据范围,而不仅仅是Microsoft Entra ID角色名称。 使用 访问表。 |
| 基础结构未发现任何问题。 | 验证Azure读取访问权限和订阅标记。 没有标记/可访问的订阅不算通过评估。 |
| 运行时间很长、请求被限流,或内存压力增加。 | 检查收集器和测试日志。 查看 配置设置中的回溯、并发、缓存和超时。 |
| 证书连接失败。 | 检查证书有效性/私钥、应用公钥注册、租户 GUID、授权同意和服务主体角色。 SharePoint还需要当前连接器中的可导出密钥。 |
| 受约束的语言模式可防止执行。 | 使用支持评估的已批准的主机/策略。 不要绕过组织控制;高级覆盖也无法让受限操作正常运行。 |
原因和解决方案
使用以下过程处理依赖项错误以及报告错误。 在选择解决方法之前,请检查受影响的版本。
解决 Graph 程序集冲突
对于 Could not load file or assembly Microsoft.Graph.Authentication,请从干净的进程开始,而不是删除共享模块。
- 启动新
pwsh -NoProfile进程。 - 让评估在其他云模块之前加载其固定的依赖项。
- 如果问题仍然存在,请检查 依赖项缓存和清理主机指南 。
另一个已安装的模块不会自动发生冲突,但已加载的程序集可能不兼容。 删除或重新导入模块未必能可靠地卸载程序集。 避免全面删除共享 Graph 模块和第三方清理脚本作为默认补救措施。
解决 DuckDB 初始化错误
此错误 The type initializer for 'DuckDB.NET.Data.DuckDBConnectionStringBuilder' threw an exception 可能具有不同的根本原因。
- 检查内部异常。 在 Windows 中,
duckdb的DllNotFoundException可指示缺少本机依赖项。 - 如果缺少该组件,请安装 Microsoft Visual C++ Redistributable (x64)。
- 在新的 PowerShell 会话中重试。 不要假设每个数据库错误都有相同的原因。
从报表呈现错误中恢复
较旧的报表可能会显示 Unexpected Application Error! Invalid array length。 相关报告包括 microsoft/zerotrustassessment#1235、 microsoft/zerotrustassessment#1272、 microsoft/zerotrustassessment#1310 和 microsoft/zerotrustassessment#1388。
- 查看您所使用版本的发行和发布历史记录。 不要想当然地认为始终需要预发布版本。
- 如果导出和数据库创建已完成,请保留它们。
- 安装适用的修补程序后,请重新连接,并使用带有原始路径和 pillar 的
-Resume重新运行评估和报表处理。 - 如果成功生成了经典 HTML 报表,请使用该报表。
检查评估活动
查看 PowerShell 源、进度仪表板和每次运行日志,以了解评估活动。 上游高级故障排除指导涵盖支持包分析。
高级故障排除和数据收集
不同的诊断捕获不同的阶段。 在收集或共享数据之前,选择与故障相对应的位置。
日志和诊断文件
<Path> 是传递给 Invoke-ZtAssessment -Path 的目录,或在默认情况下为 .\ZeroTrustReport。 可选的支持包、每次运行生成的文件和扩展的 PSFramework 日志是三个单独的诊断位置。
| 货位 | 内容和用途 |
|---|---|
<Path>\log\ |
由 -ExportLog 在即将成功完成时创建的包含 .cliDat 快照的 PSFramework 支持包 ZIP。 如果未使用该开关,或运行在此阶段之前失败,则它可能不存在。 |
<Path>\zt-export\logs\<run>\1-export_progress.log |
导出收集器进度和状态。 从此处开始查找数据收集问题。 |
<Path>\zt-export\logs\<run>\2-database_progress.log |
数据库生成进度和计时。 选择“继续”将跳过此阶段。 |
<Path>\zt-export\logs\<run>\3-test_progress.log |
评估执行进度和状态。 |
<Path>\zt-export\logs\<run>\1-Export\export_<Name>.md |
收集器状态、持续时间、时间戳、端点/类型、模块版本和诊断消息。 |
<Path>\zt-export\logs\<run>\2-Tests\<TestID>.md |
测试标题、状态、持续时间、时间戳、模块版本和详细消息,可能包括查询文本。 |
%APPDATA%\PowerShell\PSFramework\Logs\on Windows |
独立于输出路径的扩展消息日志和 XML 错误记录。 适用于连接/导入问题、异常、源位置、堆栈跟踪和单个测试外部的消息。 |
<run> 使用时间戳格式 yy-MM-dd-HHmmss。 文件会随着各阶段执行而出现;部分运行或恢复后的运行不一定包含每个文件。 按次运行生成的文件生成时独立于 -ExportLog。
扩展的 PSFramework 文件包括计算机/进程标识符和编号段,例如 <computer>_<pid>_message_0.log 和 <computer>_<pid>_error_0.xml。 可用性和保留取决于日志记录提供程序配置。
在 Windows 上,%APPDATA% 标识用户的漫游文件夹,通常为 %USERPROFILE%\AppData\Roaming。 在 PowerShell 中,使用 $env:APPDATA;等效的日志路径为 Join-Path $env:APPDATA 'PowerShell\PSFramework\Logs'。
其余<Path>\zt-export部分是评估数据,而不仅仅是日志:导出的实体、ztConfig.json、db\zt.db和ZeroTrustAssessmentReport.jsonZeroTrustWorkshop.json。 这些文件可以帮助重现或恢复运行,但可以包含敏感的租户数据。 删除 <Path> 不会删除单独的 PSFramework 日志。
捕获支持包
如果某次运行在创建可选支持包之前失败,请在关闭它之前在同一 PowerShell 会话中捕获诊断信息。
为诊断包选择单独的目标。 它不需要与评估输出路径匹配。 将示例目标替换为此次运行所用的文件夹:
New-PSFSupportPackage -Path C:\AssessmentLogs\Run01 -Force提取生成的 ZIP 以访问其
.cliDat文件。在共享之前查看并编辑掉诊断中的敏感信息。 有关如何导入和分析该快照,请参阅 高级日志分析指南。
支持包会捕获当前可用的会话诊断信息,包括消息和错误历史记录,以及可能的命令历史记录或控制台输出。 它不是所有导出的租户文件的自动存档。
Warning
报表、导出、支持包和扩展日志可以包含个人信息、租户标识符、查询值和配置详细信息。 切勿将它们附加到公共GitHub问题或将其上传到未经批准的工具。 仅通过与接收方约定的、已获批准的私密渠道共享更多诊断信息。
报告问题或提供反馈
搜索或提交GitHub问题,或使用反馈通道。 包含评估版本、PowerShell 版本、选定的支柱和测试 ID、受影响的阶段以及经过脱敏处理的错误摘要。
评估是一个社区项目,而不是官方Microsoft产品。 社区问题报告不是支持合同,也不是响应保证。 共享诊断之前,请先阅读支持策略。