vikk376/Google-Threat-Intelligence-on-Azure-Cloud

# 适用于 Microsoft Copilot Studio 的 GTI MCP Server 一个生产就绪的 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器，它将 **Google Threat Intelligence** (GTI / VirusTotal) 作为工具公开，运行在 **Azure Container Apps** 上，并作为智能体工具直接接入 **Microsoft Copilot Studio**。 使用 FastMCP 基于 **streamable HTTP** 构建，正确处理了双层身份验证和 DNS rebinding 保护，因此您永远不会遇到经典的 `HTTP 421` (Misdirected Request) 错误。 ## 目录 1. [它能为您提供什么](#what-this-gives-you) 2. [架构](#architecture) 3. [前置条件](#prerequisites) 4. [步骤 1 — 克隆仓库](#step-1--clone-the-repository) 5. [步骤 2 — 提供您的输入（资源组、区域、API 密钥）](#step-2--provide-your-inputs-rg-region-api-key) 6. [步骤 3 — 部署到 Azure](#step-3--deploy-to-azure) 7. [步骤 4 — 测试已部署的服务器](#step-4--test-the-deployed-server) 8. [步骤 5 — 连接到 Microsoft Copilot Studio](#step-5--connect-to-microsoft-copilot-studio) 9. [步骤 6 — 在 Copilot Studio 中测试](#step-6--test-inside-copilot-studio) 10. [Day-2 运维](#day-2-operations) 11. [故障排除](#troubleshooting) 12. [项目结构](#project-structure) 13. [安全注意事项](#security-notes) 14. [许可证](#license) ## 它能为您提供什么 您的 Copilot Studio 智能体可使用 **六种 GTI 工具**： | 工具 | 描述 | |------|-------------| | `get_file_report` | 通过 MD5 / SHA-1 / SHA-256 获取文件判定结果 | | `get_file_behavior` | 沙箱行为（进程、网络、MITRE ATT&CK 技术） | | `get_url_report` | URL 判定结果、分类、最终 URL | | `get_ip_report` | IP 信誉、ASN、地理位置 | | `get_domain_report` | 域名信誉、分类、注册商、DNS 记录 | | `search_gti` | GTI 情报搜索（需要企业版 / GTI 级别密钥） | ## 架构 ``` Microsoft Copilot Studio │ streamable HTTP + X-API-Key ▼ Azure Container Apps (ingress, HTTPS) │ ▼ gti-mcp container (FastMCP) ├─ X-API-Key edge middleware ← validates Copilot's request └─ GTI tools ──────────────► Google Threat Intelligence / VirusTotal API v3 (uses VT_APIKEY, server-side only) ``` **双层安全：** - `VT_APIKEY` — 您的 GTI / VirusTotal 密钥。作为 Azure Container App 机密存储；永远不会离开容器。 - `X-API-Key`（又名 `EDGE_API_KEY`） — Copilot Studio 在标头中发送的内容。如果您未提供，则会在部署时自动生成。 ## 前置条件 | 要求 | 如何验证 | |-------------|---------------| | 具有现有资源组的 Azure 订阅 | `az group list -o table` | | 已安装并登录 Azure CLI | `az --version`，然后运行 `az login` | | Google Threat Intelligence / VirusTotal API 密钥 | [virustotal.com](https://www.virustotal.com) → 您的个人资料 → API 密钥 | | Bash shell（Linux、macOS、WSL、Git Bash 或 **Azure Cloud Shell**） | `bash --version` | | Python 3.11+（仅用于本地测试脚本） | `python --version` | | Microsoft Copilot Studio 访问权限 | [copilotstudio.microsoft.com](https://copilotstudio.microsoft.com) | ## 步骤 1 — 克隆仓库 ``` git clone https://github.com//gti-mcp-copilot-studio.git cd gti-mcp-copilot-studio chmod +x deploy.sh ``` 或者，如果您手动下载了文件，只需 `cd` 进入该文件夹并运行 `chmod` 命令行。 ## 步骤 2 — 提供您的输入（资源组、区域、API 密钥） 您有 **三种方式** 提供配置。选择最方便的一种即可 — 它们可以组合使用。 ### 方法 A — `.env` 文件（推荐） 这对于重复部署来说最简洁。复制模板并填写： ``` cp .env.example .env nano .env # or: code .env / vim .env / notepad .env ``` 至少填写以下三个值： ``` RG=my-resource-group LOCATION=centralindia VT_APIKEY=paste-your-gti-or-virustotal-key-here ``` 保存并退出。`.env` 包含在 `.gitignore` 中，因此永远不会被推送。 然后运行： ``` ./deploy.sh ``` ### 方法 B — 在您的 shell 中设置环境变量 适用于 CI 或快速一次性部署： ``` export RG="my-resource-group" export LOCATION="centralindia" export VT_APIKEY="paste-your-gti-key" ./deploy.sh ``` ### 方法 C — 交互式提示（无需文件，无需导出） 直接运行即可。脚本会提示您输入任何缺失的内容： ``` ./deploy.sh ``` 您将看到： ``` Azure resource group name: my-resource-group Azure region (e.g. centralindia, eastus, canadacentral): centralindia Google Threat Intelligence / VirusTotal API key: ← typed but hidden ``` API 密钥提示是隐藏的（类似于密码）。在每个值之后按 **Enter** 键。 ### 脚本需要的变量与可选变量 | 变量 | 必需 | 留空时的默认值 | |----------|:--------:|------------------| | `RG` | ✅ | _提示您输入_ | | `LOCATION` | ✅ | _提示您输入_ | | `VT_APIKEY` | ✅ | _提示您输入（隐藏）_ | | `ACR` | ➖ | `acrgtimcp` + 随机后缀（必须全局唯一） | | `ENV_NAME` | ➖ | `env-gti-mcp` | | `APP` | ➖ | `gti-mcp` | | `IMAGE_TAG` | ➖ | `1.0.0` | | `CREATE_RG` | ➖ | `false` — 如果 `RG` 不存在，脚本将失败。设置为 `true` 则自动创建。 | | `EDGE_API_KEY` | ➖ | 自动生成的 64 位随机十六进制字符（您的 `X-API-Key`） | ## 步骤 3 — 部署到 Azure 一旦您的输入就位，运行： ``` ./deploy.sh ``` 预计运行时间：**3–5 分钟**（ACR 镜像构建是最耗时的部分）。 您将看到如下进度： ``` >> Using existing resource group: my-resource-group >> ACR: acrgtimcp17284 >> Building image gti-mcp:1.0.0 in ACR (no local Docker needed) >> Container Apps environment: env-gti-mcp >> Container App: gti-mcp ``` 完成后，脚本会打印出一个结果区块。**这是整个部署中最重要的输出 — 请将这三个值复制并保存到安全的地方：** ``` ============================================================ GTI MCP deployed successfully. Resource group: my-resource-group Region: centralindia ACR: acrgtimcp17284 MCP URL: https://gti-mcp..centralindia.azurecontainerapps.io/mcp Health: https://gti-mcp..centralindia.azurecontainerapps.io/health X-API-Key: <64-char-hex-string-shown-only-here> >> Save the X-API-Key now. You enter it in Copilot Studio and it is not shown again. To read it back later: az containerapp secret show -g my-resource-group -n gti-mcp \ --secret-name edge-api-key --query value -o tsv ============================================================ ``` ## 步骤 4 — 测试已部署的服务器 在前往 Copilot Studio 之前，运行本地健康检查，以确保服务器端一切正常。将这两个新值添加到您的 `.env` 中： ``` # 在 .env 的底部 MCP_URL=https://gti-mcp..centralindia.azurecontainerapps.io/mcp MCP_KEY=paste-the-X-API-Key-from-the-deploy-output ``` 然后在您的终端中运行： ``` python -m venv .venv # Windows: .venv\Scripts\activate # macOS / Linux: source .venv/bin/activate pip install -r requirements-test.txt python test_mcp.py ``` 您应该会看到五行 `PASS`： ``` Testing GTI MCP at: https://gti-mcp.<...>.azurecontainerapps.io/mcp [PASS] Health endpoint reachable -> HTTP 200 {"status":"ok",...} [PASS] Wrong X-API-Key is rejected (401) -> HTTP 401 [PASS] MCP handshake (initialize) -> connected, no 421/401 [PASS] List tools -> 6 tools: get_file_report, ... [PASS] Call get_file_report (live GTI lookup) -> {"sha256":"...", ...} ======================================================== RESULT: ALL CHECKS PASSED — ready for Copilot Studio ======================================================== ``` 如果任何检查失败，消息会告诉您哪一层出了问题。请参阅[故障排除](#troubleshooting)。 ## 步骤 5 — 连接到 Microsoft Copilot Studio 您将需要： - 您的 **MCP URL**（来自步骤 3 — 以 `/mcp` 结尾） - 您的 **X-API-Key**（来自步骤 3） ### 5.1 — 打开您的智能体并启用生成式编排 1. 前往 **[copilotstudio.microsoft.com](https://copilotstudio.microsoft.com)** 并登录。 2. **右上角** — 确认您处于正确的**环境**中。您创建的连接将存在于该环境中。 3. 打开您的智能体，或点击 **Create → New agent** 并为其命名。 4. 点击 **gear / Settings**（智能体内部右上角） → **Generative AI**（或编排部分） → 确认 **orchestration 为 Generative** → **Save**。 *在经典编排下，MCP 工具将被忽略 — 此步骤是强制性的。* ### 5.2 — 将 MCP server 添加为工具 5. 在智能体的左侧导航中，点击 **Tools**。 6. 点击 **+ Add a tool**。 7. 在出现的面板中，点击顶部的 **+ New tool**。 8. 选择 **Model Context Protocol**。 9. 填写表单： - **Server name:** `GTI` - **Description:** `Google Threat Intelligence lookups (file, URL, IP, domain, sandbox, search)` - **Server URL / Endpoint:** *粘贴您的* `https://<...>/mcp` *URL* - **Authentication:** 选择 **API key** 10. API key 详情出现： - **Parameter / Header name:** `X-API-Key` - **Location:** **Header** - 点击 **Create**。 ### 5.3 — 创建连接 11. Copilot 提示您 **Create a connection**。一个对话框会询问 API key 的值。 12. 粘贴您的 **X-API-Key** → 点击 **Create**。 13. 回到该工具页面，点击 **Add to agent**（或 **Add and configure**）。 ### 5.4 — 确认连接 14. 点击 **GTI** 工具以打开其详情页面。 15. 查看 **Tools** 部分 — 它会**实时**查询您的服务器并列出所有六个工具（`get_file_report`、`get_file_behavior`、`get_url_report`、`get_ip_report`、`get_domain_report`、`search_gti`）。如果它们出现，说明配置正确。 16. *（可选）* 在每个工具上，切换 **completion / confirmation** 设置，以便智能体自动运行它而无需询问用户 — 这能提供更流畅的 SOC 聊天用户体验。 ## 步骤 6 — 在 Copilot Studio 中测试 1. 打开右侧的 **Test your agent** 面板。 2. 发送一个强制触发工具调用的 prompt。例如： 3. 您应该会看到智能体调用 `get_file_report` 工具并返回判定结果。 4. 接下来尝试使用 IP 或域名，以确认工具选择在整个集合中均能正常工作： ### 发布以便其他渠道可以使用它 5. **右上角 → Publish**。 6. **Channels / Settings** → 添加 Teams、Web 或任何您希望智能体可被访问的渠道。 ## Day-2 运维 ### 推送代码更改并重新部署 ``` az acr build -r -t gti-mcp:1.0.1 . az containerapp update -g -n gti-mcp \ --image .azurecr.io/gti-mcp:1.0.1 ``` ### 读回 X-API-Key ``` az containerapp secret show -g -n gti-mcp \ --secret-name edge-api-key --query value -o tsv ``` ### 轮换 X-API-Key ``` az containerapp secret set -g -n gti-mcp \ --secrets edge-api-key=$(openssl rand -hex 32) ``` 然后更新 Copilot Studio 连接中的值（Tools → GTI → connection）。 ### 跟踪实时日志 ``` az containerapp logs show -g -n gti-mcp --tail 100 --follow ``` ### 销毁资源 ``` az containerapp delete -g -n gti-mcp --yes az containerapp env delete -g -n env-gti-mcp --yes az acr delete -g -n --yes ``` ## 故障排除 | 症状 | 原因 | 修复方法 | |--------|------|-----| | `test_mcp.py` 步骤 1 失败/超时 | 容器未运行，或 URL 错误 | `az containerapp logs show -g -n gti-mcp --tail 50` | | 返回 HTTP `421` Misdirected Request | 缺少传输安全修复的旧镜像 | 使用新 tag 重新构建并部署 | | 使用了正确的密钥但返回 HTTP `401` | Azure 中的 `edge-api-key` 机密与您发送的内容不匹配 | 使用 `az containerapp secret show ...` 将其读回 | | 步骤 5（实时 GTI 查找）返回 `unauthorized` / `forbidden` | `VT_APIKEY` 机密错误或您的密钥缺少权限 | 使用 `az containerapp secret set ... --secrets vt-apikey=` 进行更新 | | Copilot Studio "Tools" 部分显示 0 个工具 | URL 错误（必须以 `/mcp` 结尾）或 X-API-Key 错误 | 首先重新运行 `test_mcp.py`；修复其中的失败项 | | `search_gti` 返回 `forbidden` 但其他工具正常 | `search_gti` 需要企业版 / GTI 级别密钥 | 使用 GTI Enterprise 密钥，或从您的智能体中移除 `search_gti` | | `deploy.sh` 提示“未找到资源组” | RG 名称拼写错误，或订阅错误 | `az group list -o table`，或设置 `CREATE_RG=true` 进行创建 | ## 项目结构 ``` . ├── server.py # GTI MCP server (FastMCP, streamable HTTP, X-API-Key) ├── Dockerfile # container image build ├── requirements.txt # server runtime dependencies ├── deploy.sh # one-command Azure deploy (.env / env / interactive) ├── test_mcp.py # local health check (full MCP handshake) ├── requirements-test.txt # test-only dependencies ├── .env.example # config template — copy to .env, fill in, never commit ├── .gitignore # keeps .env, .venv, logs, __pycache__ out of git ├── .dockerignore # keeps secrets and dev files out of the image ├── LICENSE # MIT └── README.md # this file ``` ## 安全注意事项 - **切勿提交 `.env`** — 它包含了您的真实密钥。它已被 gitignore 忽略，但在每次提交前请使用 `git status` 进行验证。 - `VT_APIKEY` 和 `EDGE_API_KEY` 作为 **Azure Container App 机密** 存储，而不是在镜像或源代码中。 - 请像对待密码一样对待 **X-API-Key**。只要它可能已被暴露（聊天记录、截图、支持工单），就应立即对其进行轮换。 - 端点在设计上是 **公共 HTTPS** — Copilot 必须能够访问它。X-API-Key 边缘层是保护其免受未经身份验证的调用者攻击的屏障。 - 为了进行额外加固，您可以将 Azure API Management 或 Front Door 置于 Container App 之前，并添加 WAF / IP 允许列表。 ## 许可证 MIT — 查看 [LICENSE](LICENSE)。

标签：AI智能体, API集成, Ask搜索, Azure云服务, MCP协议, Microsoft Copilot, VirusTotal, 可观测性, 威胁情报, 开发者工具, 请求拦截, 逆向工具