audit-tenant-settings

审计租户设置

根据精心整理的基线审计 Fabric / Power BI 租户设置，发现偏差，列出容量、域和工作区范围的委派覆盖，调查这些设置所引用的 Entra 安全组，并将调查结果转化为有依据的讨论，探讨后续措施。始终与此技能一同调用 fabric-cli 技能；它提供此技能所依赖的 fab CLI 指南和管理 API 参考。

先决条件

此插件是 fabric-cli 插件的附加组件。它需要：

• 已安装并启用 fabric-cli 插件；该插件提供 fab CLI 指南和管理 API 参考文档。
• 使用 Fabric / Power BI 管理员帐户完成身份验证的 fab CLI（ms-fabric-cli）。
• 完成身份验证且具有 Graph 权限（Group.Read.All、User.Read.All、Directory.Read.All、RoleManagement.Read.Directory）的 az CLI，用于调查安全组。

设置

通过 .claude/fabric-admin.local.md 配置项目设置：

---
enabled: true
tenant_label: "Contoso"
snapshot_path: "~/.cache/fabric-admin-audit/last-snapshot.json"
drift_threshold_high: 5
drift_threshold_medium: 15
notification_level: "info"
schedule: "weekly"
---

# Fabric Admin Configuration

Additional context or tenant-specific notes.

字段	类型	默认值	用途
enabled	bool	true	启用或禁用此插件
tenant_label	string	none	PDF 页眉和审计报告中显示的标签
snapshot_path	string	~/.cache/fabric-admin-audit/last-snapshot.json	上次运行快照 JSON 的存储和读取位置
drift_threshold_high	int	5	高风险偏差数量超过此值时发出警报
drift_threshold_medium	int	15	偏差总数超过此值时发出警报
notification_level	string	info	详细程度：quiet、info、verbose
schedule	string	weekly	首选审计频率：daily、weekly、monthly、ad-hoc

何时使用此技能

对于任何需要解读后给出答案、而非仅调用原始 API 的租户、委派或 SG 范围治理问题，请调用此技能。常见请求包括：

• “运行租户治理审计”
• “与上个月相比，是否出现了偏差？”
• “PublishToWeb 有什么作用？我们应该启用它吗？”
• “哪些设置的范围应用于 PowerBI_ServicePrincipals 组？组内有哪些成员？”
• “列出所有容量、域和工作区覆盖”
• “在我的场景中，启用此设置是否安全？”

关键规则

• 绝不猜测。 租户设置的行为、SG 成员资格和覆盖的影响，必须以整理后的元数据、实时 API 或 Microsoft Learn 为依据。来源未提及或相互矛盾时，请明确说明。
• 收集需求。 定期使用 AskUserQuestion 技能询问用户的租户情况、用户行为和采用情况。使用 fabric-cli 技能和 fab 了解租户中的内容清单及其结构，并通过活动日志／事件了解用户的采用情况和活动。指出关键模式、异常以及高风险操作或场景（例如发布到 Web、导出，以及与外部用户、全组织用户或 C 级员工共享）。
• 不要捏造门户标题、说明、建议、风险级别、SG 成员资格或 ACL 结构。 如果元数据或 API 中缺少相关事实，请获取这些信息。
• 不得声称绝对合规（HIPAA、SOC 2、GDPR 等）。结论仅限于指出与整理后的基线相比观察到的偏差，以及原始 API 的发现。
• 建议仅供参考，不是强制要求或普遍适用的规则。 整理后的 recommended 字段反映的是主观判断和社区默认做法，并未考虑用户的具体场景。请始终说明其中的细微差异，并由用户自行决定。
• 务实且审慎，避免危言耸听。 考虑用户场景的实际可行性，并参与决策和规划，让用户了解当前租户设置配置带来的实际影响：
  • 这对治理意味着什么：用户可以执行哪些操作、访问哪些内容，以及创建哪些内容？
  • 这对创建、共享和分发等关键流程有何影响？
  • 这对 Fabric 容量使用和资源限制有何影响？
  • 这会造成哪些阻碍，从而妨碍有效分析？
  • 启用或禁用某项设置是否会阻止用户操作或产生新的依赖？

权威来源（按优先级排序）

1. 整理后的元数据：references/tenant-settings-metadata.yaml。其中包含每项已知设置的 human_name、description、preview、source_url、recommended、risk 和 recommendation_nuance。任何有关租户设置的问题，都应先查阅此文件。
2. 实时 API：通过 fab api 和 az 调用：
   • 全租户状态：fab api "admin/tenantsettings"
   • 委派的覆盖设置：fab api "admin/capacities/delegatedTenantSettingOverrides"、admin/domains/...、admin/workspaces/...
   • Entra 组和角色分配：az ad group、az rest --method get --uri https://graph.microsoft.com/v1.0/...
3. Microsoft Learn：访问 https://learn.microsoft.com/en-us/fabric/admin/tenant-settings-index，或使用 pbi-search CLI。元数据已过时、设置刚推出，或用户提出基线无法解答的功能问题时，请查阅此来源。

工作流

按顺序执行以下步骤。只有在理由明确时才可跳过某一步；不得悄然省略。

1. 验证前提条件

• 检查 fab --version 是否为当前版本；如果版本过旧，请运行 uv tool upgrade ms-fabric-cli。
• 确认 fab auth status 显示有效会话；如果没有，请让用户运行 fab auth login。
• 管理员访问权限检查：运行 fab api "admin/capacities" 2>&1 | head -5。如果返回 401／403，则该帐户不是 Fabric／Power BI 管理员；请停止并询问用户如何继续（请管理员运行此命令，或改用非管理员脚本）。
• 如果需要调查任何 SG，请确认 az account show 显示的会话至少具有 Group.Read.All、User.Read.All、Directory.Read.All 和 RoleManagement.Read.Directory 权限。请让用户运行 az login，不要自动进行身份验证。

2. 运行审计脚本

uv run ${CLAUDE_PLUGIN_ROOT}/skills/audit-tenant-settings/scripts/audit-tenant-settings.py -o /tmp/tenant-audit.md

常见变体：

• --drift-only 仅显示不合规设置，缩短报告。
• --snapshot /path/to/snap.json 在审计多个租户时，按租户隔离数据。
• --no-snapshot 跳过变更检测（首次运行，或希望从干净状态开始时）。

脚本会将实时状态与整理后的元数据合并，并一次性计算偏差、预览功能、SG 范围限定，以及自上次快照以来的变更。管理员写入端点的速率限制为每分钟 25 个请求；收到 429 时请遵循 Retry-After。

如需生成便于分享的一至两页简报，请对同一快照运行 PDF 生成器：

uv run ${CLAUDE_PLUGIN_ROOT}/skills/audit-tenant-settings/scripts/generate_audit_pdf.py -o /tmp/tenant-audit.pdf

PDF 会重点呈现概要计数、自上次快照以来的变更、偏差表和委派覆盖项摘要。它通过导入复用与 Markdown 脚本相同的审计逻辑，并读取相同的快照路径，因此变更检测始终保持一致。如果不是以管理员身份运行，可使用 --no-overrides 跳过覆盖项枚举；也可使用 --tenant-label "Contoso" 在页眉添加租户名称。请将 PDF 与 Markdown 审计报告配套使用；PDF 面向利益相关者，Markdown 用于工作过程讲解。

3. 检查脚本输出

从头到尾阅读生成的 Markdown，然后按以下顺序呈现发现：

1. 摘要部分的概要计数（总数、合规数、偏差数、预览数、SG 范围限定数）。
2. 自上次审计以来的变更（新增、移除、切换、sg_changed、property_changed）。如果没有快照，说明这是“首次运行”。
3. 高风险偏差：偏差表中标记为 risk: high 的设置。
4. SG 范围限定方面的注意事项：基线建议限定范围（on:sg / off:sg），但当前适用于整个组织的设置，以及通过启发式方法标记的任何个人 UPN。
5. 当前已启用的预览功能（管理员往往没意识到自己已同意启用这些功能）。

摘要请保持简洁（不超过 400 个单词）。面向用户的文字中请使用门户标题，而非 API 名称；仅在确有必要精确指明时才附注 (settingName)。

4. 枚举委派覆盖项

租户范围的状态只反映了一半情况。任何父设置将 delegateToCapacity / delegateToDomain / delegateToWorkspace 设为 true 的设置，都可能在相应范围内被本地覆盖。跳过此步骤是治理报告出错的最常见原因。

请提取全部三个范围的数据，并为每个覆盖项标记为 drift-vs-tenant、drift-vs-recommended、high-risk（父设置具有 risk: high）或 orphan（父设置未委派；该覆盖项已失去作用）。绝不要悄然省略任何覆盖项，即使它符合规范也不例外。当用户询问特定工作区、容量或域时，请将覆盖项显示在租户默认值上方，以便清楚呈现实际生效状态。

完整的枚举模式、筛选方法和变更机制：references/delegated-overrides.md。

5. 调查安全组的配置与策略

任何限定到安全组的设置，其强度都取决于该组的成员、所有权和治理。若限定范围所指向的安全组（SG）为空或已过时，实际上就没有起到限定作用。反过来，若设置仅限于成员规模庞大且动态变化的安全组，那么在 RLS 规范的租户中，这种限制可能还不如将设置保留为组织范围。

枚举实时租户设置中引用的每个 graphId，通过 az ad group 解析每个 ID，按 @odata.type 对成员分类，与 Fabric / Power BI / Global 管理员角色分配交叉核查，并将每项发现反馈到对应的租户设置行。风险标记类别（空组、来宾成员、已过时的所有者、动态成员身份、嵌套 SP）以及准确的 Graph 查询见 references/security-groups.md。

当 SG 策略本身看起来不合理时（例如，一个 SG 被用于不相关的安全策略、个人用户被直接添加到角色型组中、所有权仍归已离职员工所有），应直截了当地指出，不要危言耸听。目标是帮助用户重新思考模型，而不是吓唬他们。

6. 深入调查偏差领域

对于每项需要关注偏差的设置，在发表意见前，先以权威来源为依据：

1. 按关键字搜索精选元数据：

   grep -i -A6 '<keyword>' ${CLAUDE_PLUGIN_ROOT}/skills/audit-tenant-settings/references/tenant-settings-metadata.yaml
   

2. 确认实时状态：

   fab api "admin/tenantsettings" -q "text.tenantSettings[?settingName=='<API name>']"
   

3. 如果元数据已过时，或未涵盖该场景所需的细节，则获取规范文档：元数据中的 source_url，或通过 pbi-search 搜索门户标题或 API 名称。
4. 按以下格式作答：门户标题 + API 名称、一句话描述、预览状态、当前状态、建议策略、风险等级、建议的具体说明、文档链接。

如果元数据与文档不一致，以文档为准，并向用户指出这种差异，以便更新基线。

7. 呈现发现并展开有依据的讨论

客观地呈现结果。避免危言耸听。设置偏离基线并不一定就有问题；基线是通用的，用户的场景可能有所不同。同样，设置符合基线，也不代表它一定适合用户所在的组织。

对于每个偏差领域，都应兼顾讨论的两个方面：

• 偏离建议配置：当前不符合精选基线的设置。说明更改这些设置会带来什么影响、哪些功能会失效、哪些功能将因此可用。
• 建议配置可能不适合该用户：符合基线，但可能需要根据用户的场景进行调整的设置（例如，需要有选择地启用 PublishToWeb 的自助服务型组织，或需要将 ServicePrincipalsUseReadAdminAPIs 设置得比通用建议更严格的受监管租户）。

在用户场景会影响建议时，提出简短、针对性的问题：许可模式（Pro、PPU、Premium、Fabric）、内容生命周期（自助服务还是企业管理）、监管要求、安全组策略，以及正在推进的采用目标。不要询问与建议无关的事项。

8. 与用户共同制定后续步骤

共同制定计划，而不是直接替用户做决定。可考虑以下事项：

• 文档：在进行任何更改前，在运行手册中记录当前状态、安全组成员资格和覆盖项清单。
• 安全组整改：创建或整合安全组、分配用户/服务主体、弃用空组或过时组，并将所有权从已离职员工名下转移。
• 受控更改租户设置：先通过安全组范围控制试点一部分用户，再逐步扩大范围。始终通过门户或显式的 fab api -X post 命令进行；此技能绝不会自动应用更改。
• 容量 / 域 / 工作区覆盖项审计：与用户一起逐项检查覆盖项列表，并决定哪些是有意设置的，哪些应予以移除。
• Power BI 实施规划系列中的采用规划、实施规划和安全与合规规划相关环节。指向相关文章，而不是复述其内容。
• 定期快照和警报：当用户希望持续监督而非临时审查时，可主动提出设置定期运行的审计脚本（例如通过 cron、定时 GitHub Action、定时运行的 Fabric 笔记本或 Azure DevOps 管道），以刷新快照并将生成的差异发送到易于查看的位置。之后，可将变更检测输出接入警报渠道；Fabric Activator 是一种选择，也可以通过 Power Automate 使用 Teams 或电子邮件、通过 webhook 向寻呼机发送通知，或使用简单的收件箱规则。借此可捕获 Microsoft 新增的设置、状态偏移和安全组成员资格变更，无需手动重新运行审计。范围和接入方式由用户决定；此技能可以帮助设计流程，但未经明确批准，不得部署任何内容。

每份计划结尾都必须附上以下免责声明：“这些建议依据精选基线以及本次审计时的实时 API 状态。Agent 提供的信息可能并非完全准确或适用于具体场景；在生产环境中应用任何内容之前，用户有责任进行尽职调查、试点变更，并与自身的安全、合规和 Fabric 管理团队确认。”

输出标准

• 面向用户的文本中使用门户标题（元数据中的 human_name）；仅在需要精确区分或 API 名称更易识别时，才以 (settingName) 标注。
• 带计数的摘要使用 ASCII 表格或对齐的项目符号列表。不要使用表情符号或装饰性格式。
• 原样引用元数据和文档中的描述与建议；切勿以改变含义的方式转述。
• 完整审计摘要不超过 400 词。单个设置的问题不超过 200 词。当用户询问某个 recommended 字段为 review 的设置“是否应该”采用时，明确说明基线没有明确立场，并阐述相关细节。
• 除非用户明确要求，否则绝不公开完整的安全组成员名单或完整的工作区用户列表。应汇总人数、角色分布和明确的风险项。

边缘情况

• 实时 API 中存在未知设置：Microsoft 在上次刷新元数据后新增了该设置。获取对应的 Learn 条目以了解背景，并提出扩展 tenant-settings-metadata.yaml。
• 元数据条目在实时 API 中缺失：设置已重命名或停用。不要提供建议。
• 设置描述含糊：如果有多个设置符合查询，请列出候选项并询问用户要了解哪一个。
• 没有 fab auth 会话：请用户先运行 fab auth login。不要自动进行身份验证。
• 用户询问安全组，但没有 az login：请用户运行 az login。可提出先使用脚本的启发式 UPN 标记进行初步冒烟测试。
• 速率限制（429）：按照 Retry-After 退避。恢复时，从失败的设置继续，而不是重新开始。
• 超大型租户：管理员工作区和项目 API 会分页。使用 continuationUri / continuationToken 并以流式方式处理；不要尝试将所有内容一次性载入单个响应。

资源

随附内容

• references/tenant-settings-metadata.yaml；为所有已知 Fabric / Power BI 租户设置整理的基准数据（门户标题、说明、预览、建议、风险、注意事项、文档链接）。
• references/delegated-overrides.md；枚举、分类委派的覆盖设置，并且仅针对容量进行更改。
• references/security-groups.md；解析 graphIds、对成员进行分类、检测危险信号，并交叉核对管理员角色分配。
• scripts/audit-tenant-settings.py；审计与变更检测脚本。通过同级 references/ 路径读取元数据 YAML。
• scripts/generate_audit_pdf.py；将同一审计内容呈现为简洁的一至两页 PDF 简报。通过导入同级脚本复用审计逻辑，可选择枚举委派的覆盖设置，并生成紧凑的编辑风格摘要，包含关键计数、与上次审计相比的变更、偏差表格以及委派覆盖设置部分。在 Markdown 审计之后（或取代 Markdown 审计），运行 uv run scripts/generate_audit_pdf.py -o /tmp/tenant-audit.pdf；将 PDF 分享给利益相关者，并保留 Markdown 以供工作审查时使用。

主 fabric-cli 技能中的相关阅读

• plugins/fabric-cli/skills/fabric-cli/references/admin.md；用于设置更新、分页和活动事件的原始管理员 API 机制。
• plugins/fabric-cli/skills/fabric-cli/references/permissions.md；用于治理审计跨领域部分的工作区和项目 ACL 工作流。
• plugins/fabric-cli/skills/fabric-cli/SKILL.md；fab CLI 的入口和命令参考。

外部资料

• Microsoft Learn 租户设置索引；脚本可能展示的所有设置的权威上游资料。
• Power BI 实施规划：安全与合规规划；在步骤 8 中结合调查结果参考。