Policypulse Mcp

PolicyPulse MCP

一个 MCP 服务。三种策略引擎。无需切换上下文。

PolicyPulse 将 OPA/Gatekeeper、Kyverno 和 Azure Policy 整合到一个接口中，因此你可以通过任何兼容 MCP 的客户端，用通俗语言向 AI 助手询问真实的合规状况。

---

问题

现代 Kubernetes 环境会同时运行多个策略引擎：

• OPA Gatekeeper — 准入控制，适用于本地部署和混合环境
• Kyverno — 适用于 AKS、EKS 和 GKE 的策略即代码
• Azure Policy — 扫描整个 Azure 订阅的合规情况

每个引擎都有自己的 API、违规格式和合规框架映射。平台工程师需要在三个仪表板、两个 CLI 和 Azure Portal 之间切换，才能回答：“我们合规吗？”

解决方案

PolicyPulse 将这三种引擎统一为 7 个 MCP 工具。向 AI 助手提问：

“所有引擎中最严重的违规项有哪些？” “推送之前，检查一下这个部署清单。” “哪些违规项对应 PCI-DSS 要求？” “解释这项违规，并告诉我如何修复。”

---

架构

MCP Clients (Claude, Cursor, GitHub Copilot, Cline, Windsurf, Continue.dev, Zed)
        │
        │  stdio (local)  ──or──  SSE over HTTPS (enterprise / Container Apps)
        ▼
┌───────────────────────────────────────┐
│           PolicyPulse MCP             │
│                                       │
│  ┌─────────────────────────────────┐  │
│  │      Intelligence Layer         │  │
│  │  risk summary · explain ·       │  │
│  │  prioritize · framework enrich  │  │
│  └──────────┬──────────────────────┘  │
│             │  Violation / Policy     │
│  ┌──────────┴──────────────────────┐  │
│  │       Normalized Schema         │  │
│  └──┬───────────┬──────────────┬───┘  │
│     │           │              │      │
│  ┌──┴──┐  ┌─────┴──┐  ┌───────┴──┐   │
│  │ GK  │  │Kyverno │  │  Azure   │   │
│  │     │  │        │  │  Policy  │   │
│  └──┬──┘  └────┬───┘  └────┬─────┘   │
└─────┼──────────┼───────────┼─────────┘
      │          │           │
   AKS/k8s    AKS/k8s    Azure Subscription
  Constraints PolicyReports  PolicyInsights API

控制目录是唯一可信来源：它既用于为实时违规项补充 CIS/PCI-DSS/NIST/SOC 2 参考信息，也用于部署前静态门控，在无需集群的情况下检查 YAML 清单。

---

7 个 MCP 工具

工具	功能
cluster_status	显示已连接的引擎；按集群显示舰队概览和身份验证模式；显示凭据类型
list_policies	列出所有引擎中的策略；可按引擎筛选
get_violations	列出所有违规项并补充框架参考信息；可按命名空间／引擎／严重程度／集群筛选
get_compliance_risk_summary	跨引擎风险摘要，包含监管影响
explain_violation	以通俗语言解释一项违规，并提供框架映射和修复步骤
check_manifest_compliance	部署前静态门控——粘贴 YAML，即可获取违规项，无需集群
list_controls	完整的 9 项控制目录，包含 CIS／PCI-DSS／NIST 800-53／SOC 2 映射

---

快速入门 — 演示模式

无需集群或 Azure 凭据：

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

POLICYPULSE_DEMO=true policy-pulse-mcp

---

连接到 AKS

在集群上安装策略引擎

# Kyverno
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update
helm install kyverno kyverno/kyverno -n kyverno --create-namespace

# OPA Gatekeeper
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm install gatekeeper/gatekeeper --name-template=gatekeeper \
  -n gatekeeper-system --create-namespace

# Apply demo policies and workloads (wait 2-3 min for audit reports)
kubectl apply -f demo-cluster/kyverno-policies.yaml
kubectl apply -f demo-cluster/gatekeeper-policies.yaml
kubectl apply -f demo-cluster/non-compliant-workloads.yaml

对集群运行

pip install -e ".[all]"
az aks get-credentials --resource-group <rg> --name <cluster>

AZURE_SUBSCRIPTION_ID=<sub-id> \
AZURE_CREDENTIAL_TYPE=cli \
policy-pulse-mcp

---

多集群舰队

PolicyPulse 可以在单个会话中查询多个集群。每项违规都包含 cluster 字段，因此查询时可以按集群筛选。

根据 PolicyPulse 的托管位置，有两种指定集群的方式：

模式	上下文格式	适用场景
Kubeconfig	label:context-name	本地开发，或将 kubeconfig 挂载到 Pod 中
Workload Identity	label:resourceGroup/clusterName	托管在 Container Apps 或 AKS 上——无需 kubeconfig 文件

Kubeconfig 模式（本地开发）

为每个集群获取凭据，然后让 PolicyPulse 使用单个 kubeconfig 中的多个上下文：

az aks get-credentials --resource-group rg-prod --name aks-prod
az aks get-credentials --resource-group rg-staging --name aks-staging

POLICYPULSE_CLUSTERS=prod:aks-prod,staging:aks-staging \
AZURE_SUBSCRIPTION_ID=<sub-id> \
policy-pulse-mcp

上下文名称（aks-prod、aks-staging）必须与 ~/.kube/config 中的上下文匹配。

Workload Identity 模式（托管部署）

使用 resourceGroup/clusterName 格式。PolicyPulse 会调用 Azure 管理 API 获取每个集群的 API 服务器 URL 和 CA 证书，然后使用托管身份令牌进行身份验证——任何位置都不需要 kubeconfig 文件。

POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod,staging:rg-staging/aks-staging \
AZURE_SUBSCRIPTION_ID=<sub-id> \
AZURE_CREDENTIAL_TYPE=managed_identity \
policy-pulse-mcp

完整设置说明请参阅下方的 Workload Identity 设置部分。

---

在 Azure Container Apps 上托管

对于企业部署，可在 Azure Container Apps 上将 PolicyPulse 作为 SSE 服务运行。这样，多个团队和工具便能通过 HTTPS 连接到一个集中管理的合规服务。

stdio 与 SSE

	stdio	SSE
传输方式	本地管道	HTTP / HTTPS
客户端	一个（仅限本地进程）	多个（可并发）
身份验证	无	Bearer 令牌 / Azure AD
托管位置	仅限开发者笔记本电脑	Container Apps、AKS、任意云平台
适用场景	本地开发、Claude Desktop	企业、CI/CD、多团队

步骤 1 — 构建并推送容器

docker build -t policypulse-mcp:latest .

az acr login --name <your-acr>
docker tag policypulse-mcp:latest <your-acr>.azurecr.io/policypulse-mcp:latest
docker push <your-acr>.azurecr.io/policypulse-mcp:latest

步骤 2 — 创建 Container App

az containerapp create \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --environment <your-aca-environment> \
  --image <your-acr>.azurecr.io/policypulse-mcp:latest \
  --target-port 8000 \
  --ingress external \
  --env-vars \
    POLICYPULSE_TRANSPORT=sse \
    AZURE_SUBSCRIPTION_ID=<sub-id> \
    AZURE_CREDENTIAL_TYPE=managed_identity \
    POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod,staging:rg-staging/aks-staging

使用 resourceGroup/clusterName 格式设置 POLICYPULSE_CLUSTERS 可启用 Workload Identity 模式——容器中不需要 kubeconfig 文件。

步骤 3 — 分配托管身份

az containerapp identity assign \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --system-assigned

PRINCIPAL_ID=$(az containerapp identity show \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --query principalId -o tsv)

然后按照 Workload Identity 设置部分的说明，授予该身份访问每个 AKS 集群的权限。

步骤 4 — 网络连接

PolicyPulse 需要从 Container Apps 访问每个 AKS API 服务器：

# Option A: VNet integration (recommended for production)
# Create the Container Apps environment on the same VNet as your AKS clusters.
az containerapp env create \
  --name policy-pulse-env \
  --resource-group <your-rg> \
  --location eastus \
  --infrastructure-subnet-resource-id <subnet-id>

# Option B: Public AKS — whitelist the Container App outbound IP
ACA_IP=$(az containerapp show \
  --name policy-pulse-mcp \
  --resource-group <your-rg> \
  --query properties.outboundIpAddresses[0] -o tsv)

az aks update \
  --name aks-prod \
  --resource-group rg-prod \
  --api-server-authorized-ip-ranges $ACA_IP

你的 SSE 终结点为：

https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse

---

Workload Identity 设置

本节介绍 resourceGroup/clusterName 集群格式所需的全部配置，这是适用于 Container Apps 和托管在 AKS 上的部署的推荐方式。

工作原理

当 PolicyPulse 检测到 POLICYPULSE_CLUSTERS=prod:rg-prod/aks-prod 时，它会：

1. 使用管理平面令牌调用 Azure 管理 API，获取集群的 API 服务器 URL 和 CA 证书。
2. 获取范围限定为 AKS AAD 服务器应用程序的第二个令牌（受众为 6dae42f8-4368-4678-94ff-3960e28e3630）。
3. 使用这两项信息构建 Kubernetes 客户端——无需任何 kubeconfig 文件。

PolicyPulse (Container App or AKS pod)
        │
        │  managed identity token
        ▼
Azure AD
        │
        ├──► management.azure.com  →  listClusterUserCredential
        │                             (gets API server URL + CA cert)
        │
        └──► AKS API server (each cluster)
             "I am identity X — is my token valid?"
             "Yes — you have view access — here are your violations"

先决条件

• 每个目标 AKS 集群都必须启用 AAD 集成。这是 2021 年及之后创建的集群的默认设置。验证方法：

  az aks show --resource-group rg-prod --name aks-prod \
    --query "aadProfile" -o json
  # Should return a non-null object
  

• 托管身份需要具备两个级别的权限：Azure 管理平面（用于获取集群凭据）以及每个 Kubernetes 集群内部（用于读取策略资源）。

步骤 1 — 授予管理平面权限

该身份必须能够在每个目标集群上调用 listClusterUserCredential，并读取 Azure Policy 合规状态。

PRINCIPAL_ID=<principal-id-of-your-managed-identity>
SUB_ID=<your-subscription-id>

# Azure Policy — read compliance state across the subscription
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Policy Insights Data Reader (Preview)" \
  --scope /subscriptions/$SUB_ID

# AKS — fetch cluster credentials (repeat for each target cluster)
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-prod/providers/Microsoft.ContainerService/managedClusters/aks-prod

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-staging/providers/Microsoft.ContainerService/managedClusters/aks-staging

步骤 2 — 在每个集群上授予 Kubernetes RBAC 权限

管理平面令牌将 PolicyPulse 引入 API 服务器后，Kubernetes 仍会检查自身的 RBAC。具体方法取决于集群使用的是 Azure RBAC 还是 本地 RBAC。

检查集群使用的模式：

az aks show --resource-group rg-prod --name aks-prod \
  --query "aadProfile.enableAzureRbac" -o tsv
# true = Azure RBAC mode, false/null = local RBAC mode

Azure RBAC 模式（新集群推荐）：

Azure RBAC 角色会直接映射到 Kubernetes RBAC——无需在集群内运行 kubectl 命令。

# Grant read access to Gatekeeper and Kyverno resources (repeat per cluster)
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service RBAC Reader" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-prod/providers/Microsoft.ContainerService/managedClusters/aks-prod

az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Azure Kubernetes Service RBAC Reader" \
  --scope /subscriptions/$SUB_ID/resourceGroups/rg-staging/providers/Microsoft.ContainerService/managedClusters/aks-staging

本地 RBAC 模式（较旧的集群）：

你需要在每个集群内使用该身份的客户端 ID（而非主体/对象 ID）创建 ClusterRoleBinding。

# Get the client ID of the managed identity
CLIENT_ID=$(az identity show \
  --name <your-managed-identity-name> \
  --resource-group <your-rg> \
  --query clientId -o tsv)

# Run this for each target cluster
az aks get-credentials --resource-group rg-prod --name aks-prod

kubectl create clusterrolebinding policypulse-reader \
  --clusterrole=view \
  --user="$CLIENT_ID"

view ClusterRole 提供对大多数资源的只读访问权限，包括 Gatekeeper 和 Kyverno 用于记录违规情况的自定义资源。

步骤 3 — 配置 PolicyPulse

在 Container App 或 Pod 上设置这些环境变量：

AZURE_SUBSCRIPTION_ID    = <your-subscription-id>
AZURE_CREDENTIAL_TYPE    = managed_identity
POLICYPULSE_CLUSTERS     = prod:rg-prod/aks-prod,staging:rg-staging/aks-staging

对于用户分配的托管身份，还需设置：

AZURE_CLIENT_ID          = <client-id-of-the-user-assigned-identity>

步骤 4 — 验证连接

服务运行后，调用 cluster_status。响应会显示每个集群的身份验证模式：

{
  "fleet": [
    { "label": "prod",    "context": "rg-prod/aks-prod",       "auth": "workload_identity" },
    { "label": "staging", "context": "rg-staging/aks-staging", "auth": "workload_identity" }
  ]
}

如果 "auth" 显示 "workload_identity"，且集群出现在 connected_engines 中，则表示设置已完成。

故障排查

症状	可能原因	修复方法
AZURE_SUBSCRIPTION_ID must be set	缺少环境变量	设置 AZURE_SUBSCRIPTION_ID
管理 API 返回 403	缺少 Cluster User Role	执行步骤 1 中的角色分配
k8s API 返回 401 Unauthorized	缺少 k8s RBAC	对该集群执行步骤 2
aadProfile is null	未启用 AAD 集成	使用 az aks update --enable-aad 启用
No CA certificate found	kubeconfig 未返回 CA	检查集群运行状况；回退方案会使用未经验证的 TLS

---

MCP 客户端配置

Claude Desktop — 本地（stdio）

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "policy-pulse": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-sub-id",
        "AZURE_CREDENTIAL_TYPE": "cli"
      }
    }
  }
}

Claude Desktop — 企业版（SSE）

{
  "mcpServers": {
    "policy-pulse": {
      "url": "https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse"
    }
  }
}

Cursor

打开 Settings → MCP → Add Server：

{
  "policy-pulse": {
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

企业版 SSE：{ "url": "https://..." }

GitHub Copilot（VS Code）

将以下内容添加到工作区中的 .vscode/mcp.json：

{
  "servers": {
    "policy-pulse": {
      "type": "sse",
      "url": "https://policy-pulse-mcp.<unique-id>.eastus.azurecontainerapps.io/sse"
    }
  }
}

本地 stdio：

{
  "servers": {
    "policy-pulse": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
    }
  }
}

Continue.dev

~/.continue/config.json：

{
  "mcpServers": [
    {
      "name": "policy-pulse",
      "command": "python",
      "args": ["-m", "policy_pulse_mcp.server"],
      "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
    }
  ]
}

Cline（VS Code）

Cline 扩展 → MCP Servers → Add：

{
  "policy-pulse": {
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

Windsurf（Codeium）

Windsurf Settings → MCP → Add server：

{
  "policy-pulse": {
    "serverType": "stdio",
    "command": "python",
    "args": ["-m", "policy_pulse_mcp.server"],
    "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
  }
}

Zed Editor

~/.config/zed/settings.json：

{
  "context_servers": {
    "policy-pulse": {
      "command": {
        "path": "python",
        "args": ["-m", "policy_pulse_mcp.server"],
        "env": { "AZURE_SUBSCRIPTION_ID": "your-sub-id" }
      }
    }
  }
}

---

环境变量

核心

变量	默认值	描述
POLICYPULSE_DEMO	false	true = 使用模拟数据，无需集群或 Azure 凭据
POLICYPULSE_TRANSPORT	stdio	本地客户端使用 stdio，托管部署使用 sse
POLICYPULSE_HOST	0.0.0.0	SSE 服务绑定地址
PORT	8000	SSE 服务端口（也接受 POLICYPULSE_PORT）
POLICYPULSE_LOG	INFO	日志级别（DEBUG、INFO、WARNING）

Kubernetes

变量	默认值	描述
KUBECONFIG	~/.kube/config	kubeconfig 文件路径（仅在 kubeconfig 模式下使用）
POLICYPULSE_CLUSTERS	（单个集群）	逗号分隔的列表。支持两种格式：label:context-name（kubeconfig 模式）或 label:resourceGroup/clusterName（工作负载身份模式）。示例：prod:rg-prod/aks-prod,dev:aks-dev-context

Azure

变量	是否必需	描述
AZURE_SUBSCRIPTION_ID	Azure Policy 和工作负载身份所需	要查询策略合规性的订阅
AZURE_CREDENTIAL_TYPE	否（默认值：auto）	auto | cli | managed_identity | service_principal
AZURE_TENANT_ID	service_principal 模式所需	Azure AD 租户 ID
AZURE_CLIENT_ID	service_principal 或用户分配的 MI 所需	客户端或身份 ID
AZURE_CLIENT_SECRET	service_principal 模式所需	客户端密钥

---

Azure 凭据类型

本地开发：

az login
AZURE_CREDENTIAL_TYPE=cli policy-pulse-mcp

CI/CD — 服务主体：

AZURE_CREDENTIAL_TYPE=service_principal \
AZURE_TENANT_ID=<tenant-id> \
AZURE_CLIENT_ID=<client-id> \
AZURE_CLIENT_SECRET=<secret> \
policy-pulse-mcp

Container Apps / AKS 生产环境 — 托管身份：

AZURE_CREDENTIAL_TYPE=managed_identity policy-pulse-mcp

托管身份所需的 Azure 角色：

角色	范围	用途
Policy Insights Data Reader (Preview)	订阅	读取 Azure Policy 合规状态
Azure Kubernetes Service Cluster User Role	每个 AKS 集群	通过管理 API 获取集群凭据
Azure Kubernetes Service RBAC Reader	每个 AKS 集群	读取 Gatekeeper/Kyverno 资源（Azure RBAC 集群）

对于使用本地 RBAC 而非 Azure RBAC 的集群，请参阅工作负载身份设置的步骤 2。

---

安装

pip install policy-pulse-mcp                      # core only (demo + static gate)
pip install "policy-pulse-mcp[kubernetes]"        # + Gatekeeper + Kyverno
pip install "policy-pulse-mcp[azure]"             # + Azure Policy
pip install "policy-pulse-mcp[all]"               # everything

从源代码安装：

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

---

开发

git clone https://github.com/raviteja-pegata/policy-pulse-mcp
cd policy-pulse-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"

make test          # 87 tests, fully offline, ~0.3s
make demo-server   # POLICYPULSE_DEMO=true
make lint
make fmt

---

路线图

v0.2

• get_violation_history — 查看合规性随时间的变化
• check_resource_compliance — 查询特定 Azure 资源
• 支持多个 Azure 订阅
• 用于集群内部署的 Helm chart
• 发布到 PyPI

v0.3

• 由 YAML 驱动的目录扩展 — 无需编写 Python 即可添加控制项
• search_catalog 工具
• GitHub Actions 部署前门禁示例

v1.0

• generate_remediation_manifest
• create_exemption_request
• trigger_azure_remediation_task

---

License

MIT — see LICENSE.