Azure策略生成工具

Azpolicymcp

简单的MCP服务器，可帮助为任何资源类型创建Azure策略。

概述

本文档概述了Azure策略模型上下文协议（MCP）服务器的要求。该服务器的主要目标是增强大型语言模型（LLM）的能力， 和部署 Azure自定义策略有效。它通过提供工具来获取相关的内置策略作为示例、根据官方模式验证生成的策略的结构， 并通过Azure REST API管理策略分配它还旨在协助法学硕士根据用户意图（审计/拒绝与补救）选择适当的政策效果。目标用户是需要与Azure策略定义和分配交互的LLM应用程序（如聊天机器人或代码助理）。其价值在于为LLM提供一个标准化、可靠的接口，以便根据用户请求创建、验证和部署准确且合规的Azure策略。

核心功能

1. get_builtin_policies 工具（已实施）：

   • 它的作用： 获取顶级 分类 Azure内置策略 Azure/azure-policy GitHub存储库。可以选择按名称过滤类别。
   • 为什么重要： 允许LLM发现可用的策略类别（例如，“存储”、“计算”、“网络”）。
   • 它是如何工作的： 使用GitHub API列出 built-in-policies/policyDefinitions 路径。返回类别名称及其对应路径的列表。

2. get_policies_in_category 工具（已实施）：

   • 它的作用： 从以下位置获取指定类别路径内的单个策略定义文件（名称、路径、下载URL） get_builtin_policies。可以选择按文件名筛选策略。
   • 为什么重要： 使LLM能够深入到特定领域并找到相关的政策示例。
   • 它是如何工作的： 使用GitHub API列出所提供类别路径中的文件。返回JSON文件名、路径和直接下载URL的列表。

3. get_policy_content 工具（已实施）：

   • 它的作用： 使用从以下位置获得的直接下载URL获取特定策略定义的原始JSON内容 get_policies_in_category.
   • 为什么重要： 提供实际的策略JSON，LLM可以将其用作具体示例或模板。
   • 它是如何工作的： 对提供的GitHub原始内容URL执行HTTP GET请求。以字符串形式返回策略JSON。

4. verify_policy_structure 工具（暂时禁用）：

   • 它的作用： 根据官方Azure策略定义架构验证给定的JSON字符串。
   • 为什么重要： 确保LLM生成的任何自定义策略在呈现给最终用户之前符合Azure要求的正确语法和结构，从而防止部署错误。
   • 工作原理（预期）： 将策略定义（作为JSON字符串）作为输入。解析JSON并根据本地存储的官方Azure Policy JSON模式副本进行验证(schemas/policyDefinition.json)使用 jsonschema 图书馆。返回成功消息或验证错误。 （目前已发表评论 server.py 由于问题。)

5. deploy_policy_assignment 工具（已实施）：

   • 它的作用： 使用提供的策略定义（JSON或ID）和分配参数（范围、名称等）创建或更新Azure策略分配。
   • 为什么重要： 通过将生成并验证的策略部署到目标Azure环境中，使LLM能够完成工作流。
   • 它是如何工作的： 使用通过环境变量配置的Azure身份验证凭据(TENANT_ID, CLIENT_ID, CLIENT_SECRET)使用SCL获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyAssignments 终点。

6. query_policy_compliance 工具（已实施）：

   • 它的作用： 查询指定范围内资源的合规状态，可选择按策略分配名称或合规状态进行筛选。
   • 为什么重要： 允许LLM报告策略合规状态，为用户提供有关部署策略有效性的宝贵反馈。
   • 它是如何工作的： 使用Azure Policy Insights REST API检索指定范围内资源的符合性数据。

7. delete_policy_assignment 工具（已实施）：

   • 它的作用： 从指定范围中删除现有的Azure策略分配。
   • 为什么重要： 使LLM能够管理策略分配的生命周期，包括清理和删除。
   • 它是如何工作的： 对Azure REST API终结点执行HTTP DELETE请求以进行策略分配。

8. create_policy_definition 工具（已实施）：

   • 它的作用： 使用提供的详细信息（名称、显示名称、描述、模式、参数、策略规则等）创建或更新Azure策略定义。
   • 为什么重要： 允许LLM直接在Azure中定义自定义Azure策略，从而实现完整的端到端策略管理工作流。
   • 它是如何工作的： 使用通过环境变量配置的Azure身份验证凭据(TENANT_ID, CLIENT_ID, CLIENT_SECRET)使用SCL获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyDefinitions 终点。

9. 意图识别支持（新要求）：

   • 它是什么： 帮助LLM确定用户的目标是否是审计/防止不合规资源的功能或指导（使用以下效果 Audit, Deny)或者修复现有的（使用类似的效果 DeployIfNotExists, Modify).
   • 为什么重要： 选择正确的策略效果对于实现用户期望的结果和正确构建 policyRule.
   • 它是如何工作的： 这可能涉及：
     • 加强 create_policy_prompt （特征9）明确要求LLM与用户澄清意图。
     • 可能添加一个工具来分析政策定义草案，并根据关键字或结构建议适当的效果。
     • 为不同效果的常见用例提供指导（例如，在规则/资源中）。

10. （可选增强功能） azure_policy_schema 资源： * 它的作用： 通过MCP资源URI公开官方Azure策略JSON模式（例如。， schema://azurepolicy). * 为什么重要： 允许LLM客户端直接获取模式定义，使其能够更好地理解目标结构 之前 尝试生成。 * 它是如何工作的： 这在当前版本中已经实现。

11. （可选增强功能） azure_resource_types 资源： * 它的作用： 通过MCP资源URI（例如。， types://azure/resources). * 为什么重要： 帮助LLM在策略规则中为资源类型使用正确的标识符。

12. （可选增强功能） create_policy_prompt 提示： * 它的作用： 定义一个可重用的MCP提示模板，以指导LLM在策略创建过程中， 包括意图澄清. * 为什么重要： 规范LLM的工作流程，促使其有效地使用可用的工具和资源（例如，“为{resource_type}生成策略以执行{requirement}。 明确这是否应该审计/阻止新资源或修复现有资源。 使用策略获取工具进行示例和 verify_policy_structure 在最终确定之前。使用 deploy_policy_assignment 部署。").

13. 新 azure_resource_graph_query 工具（计划）： * 它的作用： 允许LLM使用Azure REST API运行任意Azure资源图查询，从而能够发现资源、订阅ID、资源组等。 * 为什么重要： 使LLM能够动态发现Azure环境的结构和内容，包括获取订阅ID、资源类型和关系，这对于正确的策略部署和分配至关重要。 * 它是如何工作的： 使用Azure身份验证（MSAL）获取令牌并调用资源图REST API终结点(POST https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2022-10-01)使用用户提供的查询。以JSON格式返回结果。示例查询包括列出所有订阅、查找所有VM或按类型或位置汇总资源。

用户体验

此MCP服务器的主要“用户”是LLM客户端应用程序。交互流程如下：

1. 最终用户从LLM应用程序请求自定义Azure策略（例如，“创建策略以在应用程序服务上强制HTTPS”）。
2. LLM应用程序与Azure策略MCP服务器交互。
3. LLM电话 get_builtin_policies （可选地使用查询）以查找相关的策略类别。
4. LLM电话 get_policies_in_category 对于所选的类别路径（可选地使用查询），查找相关的策略文件。
5. LLM电话 get_policy_content 使用一个或多个策略的下载URL来获取示例。
6. LLM 可能 呼叫 read_resource 在…上 schema://azurepolicy （如果实施）了解所需的结构。
7. LLM与用户交互（可能由以下人员指导 create_policy_prompt)明确意图（审计/阻止与补救）并确定适当的政策效果。
8. LLM根据用户请求、明确的意图和检索到的示例/模式生成自定义策略JSON。
9. LLM 应该 呼叫 verify_policy_structure （一旦启用）使用生成的JSON。
10. 如果有效，LLM将与用户确认部署范围和参数。
11. LLM电话 deploy_policy_assignment 具有经过验证的策略定义和分配细节。
12. LLM可以选择使用以下方式查询合规性状态 query_policy_compliance.
13. LLM可以选择使用以下命令删除策略分配 delete_policy_assignment.
14. LLM向最终用户展示部署的结果（成功或失败的详细信息）。
15. 如果验证（步骤9）或部署（步骤11）失败，LLM将使用错误反馈来纠正策略/参数，并重新验证/重新尝试部署。

Azure身份验证设置（已实现）

MCP服务器现在包括使用Azure身份验证的 msal 图书馆。确保为身份验证设置了以下环境变量：

• TENANT_ID：Azure Active Directory租户ID。
• CLIENT_ID：Azure AD应用程序客户端ID。
• CLIENT_SECRET：Azure AD应用程序的客户端机密。

这些凭据是必需的 deploy_policy_assignment, query_policy_compliance, delete_policy_assignment，以及 create_policy_definition 工具正常工作。

技术架构

• 核心框架： python mcp-sdk 使用 FastMCP.
• 服务器组件：
  • server.py：主FastMCP应用程序定义，注册工具(get_builtin_policies, get_policies_in_category, get_policy_content, deploy_policy_assignment, query_policy_compliance, delete_policy_assignment，以及 create_policy_definition).加载架构以进行验证。
  • schemas/policyDefinition.json：本地存储的官方Azure Policy JSON架构文件副本（由禁用者使用 verify_policy_structure).
  • 新 Azure身份验证设置使用 msal 带有凭据环境变量的库。
• 数据模型：
  • MCP工具的输入/输出（由中的函数签名和类型提示定义 server.py).
  • Azure策略JSON结构（作为dict/string处理）。
  • Azure策略架构JSON结构（由加载 jsonschema 在……里面 server.py).
• API和集成：
  • MCP协议接口暴露 FastMCP.
  • GitHub API通过 requests （由策略获取工具使用）。
  • 新 Azure REST API通过 httpx （使用人 deploy_policy_assignment, query_policy_compliance, delete_policy_assignment，以及 create_policy_definition).
• 关键库： mcp[cli], requests, jsonschema, 新 msal, httpx.
• 基础设施： Python 3.x环境。需要安全配置Azure凭据（例如，环境变量、托管身份（如果托管在Azure中））。

发展路线图

• 第一阶段：MVP（核心功能）

  • [X] 设置基本 FastMCP 服务器项目结构(server.py).
  • [X] 获取并存储官方Azure Policy JSON模式 schemas/.
  • []实施并修复 verify_policy_structure 工具使用 jsonschema 以及所存储的模式。 （当前被阻止/禁用）
  • [X] 实施 get_builtin_policies, get_policies_in_category, get_policy_content 使用GitHub API(requests).
  • []所有工具的基本单元测试。
  • []基本 README.md 解释设置和使用。
  • []实现Azure Resource Graph API工具(azure_resource_graph_query)允许LLM查询资源、获取订阅ID和发现环境详细信息。
  • []记录资源图工具的使用情况并提供示例查询。
  • []添加逻辑以建议或自动获取策略部署工具的订阅ID（如果未提供）。

• 第2阶段：增强和可靠性

  • 实施 azure_policy_schema MCP资源。
  • 实施 azure_resource_types MCP资源（需要整理此列表）。
  • 实施 create_policy_prompt MCP提示， 包括意图澄清指南.
  • 实现一种机制来检查/更新架构文件。
  • 改进工具中的错误处理和日志记录（添加超时，可能进一步改进）。
  • 扩大测试覆盖范围。
  • 将资源图工具结果与策略部署工作流集成（例如，自动建议范围、验证资源存在）。

• 第3阶段：部署和高级功能（新）

  • 实施稳健的Azure身份验证机制（例如，使用 azure-identity 具有服务负责人或管理身份）。
  • 实施 deploy_policy_assignment 工具，处理不同的范围和参数。
  • 如果简单的提示不够，则添加逻辑/工具来支持意图识别（审计/拒绝与补救）。
  • 实施对分配需要托管身份的策略的支持（用于 deployIfNotExists/Modify).
  • 进一步提高测试覆盖率，包括部署的集成测试（需要仔细设置）。
  • 扩展资源图工具以支持高级查询、连接和聚合，从而获得更丰富的环境见解。

逻辑依赖链

1. [X] 使用以下命令建立基础Python项目 mcp-sdk.
2. [X] 获取并集成Azure策略JSON模式(schemas/policyDefinition.json).
3. [X] 实现GitHub API数据访问工具(get_builtin_policies, get_policies_in_category, get_policy_content).
4. []实施并修复 verify_policy_structure （取决于模式）。 （已阻止）
5. 实施可选资源。
6. 实施可选提示 （包括意图澄清）.
7. 实施Azure身份验证。
8. 实施 deploy_policy_assignment （取决于验证和身份验证）。
9. 实施可靠性功能（模式更新）。

最初的重点是通过GitHub API实现策略检索。下一个重点是解决验证问题，然后实现部署功能。

当前状态和下一步

• 状态： MCP服务器正在运行。发现策略类别的工具(get_builtin_policies)，在类别中列出政策(get_policies_in_category)，获取策略内容(get_policy_content)，部署策略分配(deploy_policy_assignment)，查询合规性(query_policy_compliance)，删除策略分配(delete_policy_assignment)，并创建策略定义(create_policy_definition)已实现且功能正常。包括基本的错误处理和超时。这 verify_policy_structure 该工具已实现，但由于运行时错误/验证逻辑问题，目前已被注释掉。架构文件(schemas/policyDefinition.json)存在。
• 下一个行动计划：
  1. 调试和修复 verify_policy_structure: 取消注释中的工具 server.py 并诊断 jsonschema 验证错误。确保它根据以下内容正确验证策略JSON schemas/policyDefinition.json 文件。
  2. 实现Azure资源图API工具： 添加一个工具来运行任意资源图查询，使LLM能够动态获取订阅ID和资源详细信息。在文档中提供示例查询。
  3. 添加基本自述文件： 创建一个 README.md 解释如何设置环境、运行服务器和使用可用工具。
  4. 单元测试： 开始添加单元测试，从当前可用的策略获取工具开始。

风险和缓解措施

• 风险： verify_policy_structure 事实证明，该工具很难修复，或者需要对模式进行重大调整。
  • 缓解措施： 深入了解 jsonschema 文档和特定的验证错误。将下载的架构与Azure文档示例进行比较。如有必要，首先寻求更简单的验证方法。
• （新）风险： 安全可靠地处理Azure身份验证很复杂。
  • 缓解措施： 使用标准库，如 azure-identity遵循凭证管理的最佳实践（环境变量、密钥库、托管身份）。明确记录设置要求。
• （新）风险： Azure策略分配REST API有细微差别（范围、参数、用于修复的标识管理）。
  • 缓解措施： 从更简单的分配场景开始（例如，资源组范围内的审计策略）。逐步增加对参数和不同作用域的支持。广泛参考 Azure REST API文档.对API响应执行彻底的错误处理。
• （新）风险： LLM可能会误解用户对策略效果的意图（审计/拒绝与补救）。
  • 缓解措施： 设计清晰的提示(create_policy_prompt).举个例子。记录交互以识别常见的LLM错误。如果仅靠提示是不够的，可以考虑添加显式检查或专用分析工具。
• （新）风险： 部署不正确的策略或分配可能会对Azure环境产生负面影响。
  • 缓解措施： 强调 verify_policy_structure 步骤。在内部实施检查 deploy_policy_assignment 对于所需参数。鼓励用户在部署前进行确认。建议在非生产环境中进行测试。
• 风险： GitHub API速率限制或影响策略获取工具的停机时间。
  • 缓解措施： 当前的实现使用未经身份验证的请求（可能存在较低的速率限制）。记录这一限制。考虑稍后为经过身份验证的请求添加可选的GitHub令牌支持（更高的限制）。如果瞬态错误变得普遍，则实现合理的重试逻辑。如果需要，会短暂缓存结果。
• 风险： 保留本地存储的架构(schemas/policyDefinition.json)更新需要努力。
  • 缓解措施： 在待办事项列表中添加定期检查/手动更新流程（第2阶段）。记录当前架构的来源和日期。

附录

• Azure策略文档
• Azure策略GitHub存储库
• 新 Azure策略分配REST API
• Azure资源图REST API
• Azure资源图查询语言
• Azure资源图查询示例
• MCP Python SDK文档 （参考用户提供 README.md)
• JSON模式规范
• 请求库
• jsonschema库
• 新 azure身份库
• 新 Azure策略定义REST API
• 新 Python文档
• 新 httpx库