Azpolicymcp
简单的MCP服务器，可帮助为任何资源类型创建Azure策略。
概述
本文档概述了Azure策略模型上下文协议（MCP）服务器的要求。该服务器的主要目标是增强大型语言模型（LLM）的能力， *和部署* Azure自定义策略有效。它通过提供工具来获取相关的内置策略作为示例、根据官方模式验证生成的策略的结构， *并通过Azure REST API管理策略分配*它还旨在协助法学硕士根据用户意图（审计/拒绝与补救）选择适当的政策效果。目标用户是需要与Azure策略定义和分配交互的LLM应用程序（如聊天机器人或代码助理）。其价值在于为LLM提供一个标准化、可靠的接口，以便根据用户请求创建、验证和部署准确且合规的Azure策略。
核心功能
get_builtin_policies工具（已实施）：
- 它的作用： 获取顶级 *分类* Azure内置策略 Azure/azure-policy GitHub存储库。可以选择按名称过滤类别。 - 为什么重要： 允许LLM发现可用的策略类别（例如，“存储”、“计算”、“网络”）。 - 它是如何工作的： 使用GitHub API列出 built-in-policies/policyDefinitions 路径。返回类别名称及其对应路径的列表。
get_policies_in_category工具（已实施）：
- 它的作用： 从以下位置获取指定类别路径内的单个策略定义文件（名称、路径、下载URL） get_builtin_policies。可以选择按文件名筛选策略。 - 为什么重要： 使LLM能够深入到特定领域并找到相关的政策示例。 - 它是如何工作的： 使用GitHub API列出所提供类别路径中的文件。返回JSON文件名、路径和直接下载URL的列表。
get_policy_content工具（已实施）：
- 它的作用： 使用从以下位置获得的直接下载URL获取特定策略定义的原始JSON内容 get_policies_in_category. - 为什么重要： 提供实际的策略JSON，LLM可以将其用作具体示例或模板。 - 它是如何工作的： 对提供的GitHub原始内容URL执行HTTP GET请求。以字符串形式返回策略JSON。
verify_policy_structure工具（暂时禁用）：
- 它的作用： 根据官方Azure策略定义架构验证给定的JSON字符串。 - 为什么重要： 确保LLM生成的任何自定义策略在呈现给最终用户之前符合Azure要求的正确语法和结构，从而防止部署错误。 - 工作原理（预期）： 将策略定义（作为JSON字符串）作为输入。解析JSON并根据本地存储的官方Azure Policy JSON模式副本进行验证(schemas/policyDefinition.json)使用 jsonschema 图书馆。返回成功消息或验证错误。 *（目前已发表评论 server.py 由于问题。)*
deploy_policy_assignment工具（已实施）：
- 它的作用： 使用提供的策略定义（JSON或ID）和分配参数（范围、名称等）创建或更新Azure策略分配。 - 为什么重要： 通过将生成并验证的策略部署到目标Azure环境中，使LLM能够完成工作流。 - 它是如何工作的： 使用通过环境变量配置的Azure身份验证凭据(TENANT_ID, CLIENT_ID, CLIENT_SECRET)使用SCL获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyAssignments 终点。
query_policy_compliance工具（已实施）：
- 它的作用： 查询指定范围内资源的合规状态，可选择按策略分配名称或合规状态进行筛选。 - 为什么重要： 允许LLM报告策略合规状态，为用户提供有关部署策略有效性的宝贵反馈。 - 它是如何工作的： 使用Azure Policy Insights REST API检索指定范围内资源的符合性数据。
delete_policy_assignment工具（已实施）：
- 它的作用： 从指定范围中删除现有的Azure策略分配。 - 为什么重要： 使LLM能够管理策略分配的生命周期，包括清理和删除。 - 它是如何工作的： 对Azure REST API终结点执行HTTP DELETE请求以进行策略分配。
create_policy_definition工具（已实施）：
- 它的作用： 使用提供的详细信息（名称、显示名称、描述、模式、参数、策略规则等）创建或更新Azure策略定义。 - 为什么重要： 允许LLM直接在Azure中定义自定义Azure策略，从而实现完整的端到端策略管理工作流。 - 它是如何工作的： 使用通过环境变量配置的Azure身份验证凭据(TENANT_ID, CLIENT_ID, CLIENT_SECRET)使用SCL获取访问令牌。构造并执行对 providers/Microsoft.Authorization/policyDefinitions 终点。
- 意图识别支持（新要求）：
- 它是什么： 帮助LLM确定用户的目标是否是审计/防止不合规资源的功能或指导（使用以下效果 Audit, Deny)或者修复现有的（使用类似的效果 DeployIfNotExists, Modify). - 为什么重要： 选择正确的策略效果对于实现用户期望的结果和正确构建 policyRule. - 它是如何工作的： 这可能涉及： - 加强 create_policy_prompt （特征9）明确要求LLM与用户澄清意图。 - 可能添加一个工具来分析政策定义草案，并根据关键字或结构建议适当的效果。 - 为不同效果的常见用例提供指导（例如，在规则/资源中）。
- （可选增强功能）
azure_policy_schema资源：
\* 它的作用： 通过MCP资源URI公开官方Azure策略JSON模式（例如。， schema://azurepolicy). \* 为什么重要： 允许LLM客户端直接获取模式定义，使其能够更好地理解目标结构 *之前* 尝试生成。 \* 它是如何工作的： 这在当前版本中已经实现。
- （可选增强功能）
azure_resource_types资源：
\* 它的作用： 通过MCP资源URI（例如。， types://azure/resources). \* 为什么重要： 帮助LLM在策略规则中为资源类型使用正确的标识符。
- （可选增强功能）
create_policy_prompt提示：
\* 它的作用： 定义一个可重用的MCP提示模板，以指导LLM在策略创建过程中， *包括意图澄清*. \* 为什么重要： 规范LLM的工作流程，促使其有效地使用可用的工具和资源（例如，“为{resource_type}生成策略以执行{requirement}。 *明确这是否应该审计/阻止新资源或修复现有资源。* 使用策略获取工具进行示例和 verify_policy_structure 在最终确定之前。使用 deploy_policy_assignment 部署。").
- 新
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客户端应用程序。交互流程如下：
- 最终用户从LLM应用程序请求自定义Azure策略（例如，“创建策略以在应用程序服务上强制HTTPS”）。
- LLM应用程序与Azure策略MCP服务器交互。
- LLM电话
get_builtin_policies（可选地使用查询）以查找相关的策略类别。 - LLM电话
get_policies_in_category对于所选的类别路径（可选地使用查询），查找相关的策略文件。 - LLM电话
get_policy_content使用一个或多个策略的下载URL来获取示例。 - LLM *可能* 呼叫
read_resource在…上schema://azurepolicy（如果实施）了解所需的结构。 - LLM与用户交互（可能由以下人员指导
create_policy_prompt)明确意图（审计/阻止与补救）并确定适当的政策效果。 - LLM根据用户请求、明确的意图和检索到的示例/模式生成自定义策略JSON。
- LLM *应该* 呼叫
verify_policy_structure（一旦启用）使用生成的JSON。 - 如果有效，LLM将与用户确认部署范围和参数。
- LLM电话
deploy_policy_assignment具有经过验证的策略定义和分配细节。 - LLM可以选择使用以下方式查询合规性状态
query_policy_compliance. - LLM可以选择使用以下命令删除策略分配
delete_policy_assignment. - LLM向最终用户展示部署的结果（成功或失败的详细信息）。
- 如果验证（步骤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). - 进一步提高测试覆盖率，包括部署的集成测试（需要仔细设置）。 - 扩展资源图工具以支持高级查询、连接和聚合，从而获得更丰富的环境见解。
逻辑依赖链
- \[X\] 使用以下命令建立基础Python项目
mcp-sdk. - \[X\] 获取并集成Azure策略JSON模式(
schemas/policyDefinition.json). - \[X\] 实现GitHub API数据访问工具(
get_builtin_policies,get_policies_in_category,get_policy_content). - \[\]实施并修复
verify_policy_structure（取决于模式）。 *（已阻止）* - 实施可选资源。
- 实施可选提示 *（包括意图澄清）*.
- 实施Azure身份验证。
- 实施
deploy_policy_assignment（取决于验证和身份验证）。 - 实施可靠性功能（模式更新）。
最初的重点是通过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 文件。 1. 实现Azure资源图API工具： 添加一个工具来运行任意资源图查询，使LLM能够动态获取订阅ID和资源详细信息。在文档中提供示例查询。 1. 添加基本自述文件： 创建一个 README.md 解释如何设置环境、运行服务器和使用可用工具。 1. 单元测试： 开始添加单元测试，从当前可用的策略获取工具开始。
风险和缓解措施
- 风险：
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阶段）。记录当前架构的来源和日期。