jmaciasc-google/gti-mcp-server
GitHub: jmaciasc-google/gti-mcp-server
一个生产就绪的 Google 威胁情报 MCP 服务器，为 LLM Agent 提供 IOC 查询、文件行为分析和域名/IP 信誉检测等接口，支持安全的企业级云端与本地部署。
Stars: 0 | Forks: 0
# Google Threat Intelligence MCP Server
一个用于 Google Threat Intelligence (GTI) 的生产就绪、高度优化的 Model Context Protocol (MCP) 服务器（整合了 VirusTotal 和 Mandiant 的威胁分析功能）。该服务器支持通过 `stdio` 进行本地桌面集成，以及通过 Server-Sent Events (SSE) 进行云原生网络部署，使其能够完全兼容 Google Cloud Run 或任何其他容器原生环境。
## 项目起源与部署理念
本仓库 **100% 基于官方的 Google 开源实现**，该实现托管在 [google/mcp-security](https://github.com/google/mcp-security) 仓库中。
虽然官方项目被设计为一个广泛的、面向开发者的多工具 mono-repo，**但本项目专门为了让非技术用户、安全分析师和 IT 管理员**能够毫无阻碍地在几分钟内部署一个安全的企业级 Google Threat Intelligence (GTI) MCP 服务器而创建。
### 🔍 本仓库与官方 Mono-Repo 的区别
| 功能 / 方面 | 官方 Google `mcp-security` Mono-Repo | 本专用 GTI 项目 |
| :--- | :--- | :--- |
| **项目重点** | 多服务器（SCC、SecOps、SOAR、GTI）开发者工作区。 | **100% 专注于 Google Threat Intelligence (GTI)**。完全去除了不相关的臃肿内容。 |
| **嵌套结构** | 深度嵌套在 `/server/gti` 文件夹下。 | **扁平化至根目录**。干净的 git clone 和运行体验。 |
| **机密安全** | 基本环境变量（存在明文泄露风险）。 | **严格执行使用 Google Secret Manager**。 |
| **云端部署** | 最简化的开发者部署脚手架。 | **生产就绪的 Google Cloud Run 模板**。 |
| **用户引导** | 面向软件开发者和工程师。 | **专为非技术用户设计**，提供对新手友好的命令指南。 |
| **无 Agent 验证** | 需要设置并连接 LLM 桌面客户端。 | 通过动态、自动化的 `verify.sh` 脚本实现 **即时、零 Agent 验证**。 |
## 目录
1. [核心功能](#core-features)
2. [配置与自定义（可选）](#configuration--customization-optional)
3. [本地开发与设置](#local-development--setup)
4. [容器化与 Docker](#containerization--docker)
5. [生产环境 Google Cloud Run 部署（严格的 Secret Manager）](#production-google-cloud-run-deployment-strict-secret-manager)
6. [无需 Agent 的验证](#verification-without-an-agent)
7. [MCP 客户端配置](#mcp-client-configurations)
## 核心功能
此 MCP 服务器向任何兼容的 LLM Agent 公开高性能的威胁情报 endpoint。
### 🔍 情报与追踪
- **`search_iocs(query, limit)`**：使用高级搜索过滤器查询妥协指标。
- **`get_hunting_ruleset`** & **`get_entities_related_to_a_hunting_ruleset`**：访问并映射结构化的威胁检测签名。
### 📁 文件与制品
- **`get_file_report(hash)`**：检查 MD5、SHA1 或 SHA256 哈希，以验证多引擎检测和威胁行为者分类。
- **`get_file_behavior_report(id)`** & **`get_file_behavior_summary(hash)`**：获取深度的沙箱执行数据。
### 🌐 域名、IP 和 URL
- **`get_domain_report(domain)`** & **`get_entities_related_to_a_domain`**：解析被动 DNS 映射、注册商详情和信誉分类。
- **`get_ip_address_report(ip_address)`**：检索地理位置、自治系统号 (ASN) 和检测结果。
- **`get_url_report(url)`** & **`get_entities_related_to_an_url`**：检查特定的 URL。
## 配置与自定义（可选）
本项目已预配置，完全开箱即用。**您无需修改任何这些文件即可进行部署。** 但是，如果您有特定的网络或架构需求，可以自定义这些配置文件：
| 文件路径 | 用途 | 修改详情 |
| :--- | :--- | :--- |
| **`docker-compose.yml`** | 本地容器配置 | 根据需要更改容器端口映射或本地环境引用。 |
| **`Dockerfile`** | 镜像构建规范 | 自定义基础 Python 版本或更新构建阶段的包。 |
## 本地开发与设置
### 前置条件
- Python **3.11** 或更高版本。
- 有效的 Google Threat Intelligence (VirusTotal) API key。
### 快速开始（本地 Python）
1. **克隆仓库并进入目录：**
git clone
cd gti-mcp-server
2. **配置您的 API Key（仅在内存中）：**
直接在您的终端会话中导出您的 Google Threat Intelligence API key。该 key 仅存在于您的 shell 临时 RAM 中，从不写入磁盘：
export VT_APIKEY="your_actual_gti_api_key_here"
3. **安装包和依赖项：**
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
4. **在本地运行服务器：**
# 以 stdio 模式运行（默认，用于本地桌面 Agent）：
gti-mcp-server
# 以 SSE/HTTP 网络模式运行（用于云模拟或容器测试）：
TRANSPORT=sse PORT=8080 gti-mcp-server
## 容器化与 Docker
该服务器打包了高性能、安全的 **多阶段 Docker 构建**。构建器阶段将应用程序打包成 Python wheel，运行阶段将其安装在以受限制的非 root 系统用户（UID 为 10001 的 `mcpuser`）身份运行的精简环境中。
### 1. 构建 Docker 镜像
```
docker build -t gti-mcp-server:latest .
```
### 2. 使用 Docker Compose 运行
使用 Docker Compose 会将容器绑定到端口 `8080`，并从您的 `.env` 文件加载配置：
```
docker compose up -d
```
## 生产环境 Google Cloud Run 部署（严格的 Secret Manager）
本节提供了部署到 Google Cloud Run 的默认安全、分步演练。它使用 **Google Secret Manager** 进行凭据存储，并使用 **GCP IAM OIDC 身份验证** 限制调用（禁止未经身份验证的访问）。
### 步骤 1：设置您的部署变量
将下面的占位符值替换为您的 GCP 详情：
```
PROJECT_ID="your-gcp-project-id" # Your GCP Project ID
REGION="us-central1" # GCP Region to deploy to
REPO="mcp-servers" # Artifact Registry Repository name
IMAGE="gti-mcp-server" # Container Image name
```
### 步骤 2：启用所需的 GCP 服务
启用容器托管和安全密钥存储所需的 Google API：
```
# 设置您的活动 gcloud 项目上下文
gcloud config set project ${PROJECT_ID}
# 启用 Secret Manager、Artifact Registry 和 Cloud Run API
gcloud services enable \
secretmanager.googleapis.com \
artifactregistry.googleapis.com \
run.googleapis.com
```
### 步骤 3：在 Google Secret Manager 中保护您的 API Key
创建一个托管密钥，以安全地托管您的 Google Threat Intelligence (VirusTotal) API key：
1. **创建 Secret 容器：**
gcloud secrets create VT_APIKEY --replication-policy="automatic"
2. **将您的 API key 值添加为密钥的版本 1：**
*将 `YOUR_ACTUAL_GTI_API_KEY` 替换为您的实际 token：*
echo -n "YOUR_ACTUAL_GTI_API_KEY" | gcloud secrets versions add VT_APIKEY --data-file=-
### 步骤 4：授予对 Cloud Run Service Account 的访问权限
Cloud Run 服务在指定的 service account 下运行。默认情况下，Cloud Run 使用 **Compute Engine 默认 service account** 来调用其他 GCP API。
1. **获取您的项目编号 (Project Number)：**
PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
echo "Your Project Number is: ${PROJECT_NUMBER}"
2. **确定默认的 Service Account Email：**
默认的 service account email 遵循以下模式：`${PROJECT_NUMBER}-compute@developer.gserviceaccount.com`
3. **授予此 service account 密钥访问者权限：**
这授权 Cloud Run 容器在启动时获取并解密密钥：
gcloud secrets add-iam-policy-binding VT_APIKEY \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
### 步骤 5：部署到 Cloud Run（选择您的路径）
您可以选择以下两条路径中的任意一条来编译和部署您的服务器。**强烈建议非技术用户选择选项 A，因为它不需要 Docker 或手动配置 registry！**
#### 🚀 选项 A：直接的源代码到云端部署（无需本地 Docker）
这是最快、最简单的方法。Google Cloud 将安全地打包您的源代码目录，将其上传，在后台使用您的 `Dockerfile` 运行 **Google Cloud Build**，在底层自动配置一个私有的 Artifact Registry，并部署服务。
只需在您的仓库根目录运行以下单条命令：
```
gcloud run deploy gti-mcp-server \
--source . \
--region=${REGION} \
--platform=managed \
--no-allow-unauthenticated \
--set-secrets="VT_APIKEY=VT_APIKEY:latest" \
--set-env-vars="TRANSPORT=sse,PORT=8080" \
--port=8080
```
#### 🐳 选项 B：传统的 Docker 构建、推送和部署
如果您更喜欢使用在笔记本电脑本地运行的 Docker 来编译、标记和推送容器镜像，请选择此路径：
1. **在 Artifact Registry 中创建 Docker repository：**
gcloud artifacts repositories create ${REPO} \
--repository-format=docker \
--location=${REGION} \
--description="MCP Servers Repository"
2. **验证 Docker 以推送到您的 GCP registry：**
gcloud auth configure-docker ${REGION}-docker.pkg.dev
3. **构建并标记镜像（Intel/AMD64 目标格式）：**
docker build --platform linux/amd64 -t ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest .
4. **将镜像推送到 GCP：**
docker push ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest
5. **将推送的镜像部署到 Cloud Run：**
gcloud run deploy gti-mcp-server \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest \
--region=${REGION} \
--platform=managed \
--no-allow-unauthenticated \
--set-secrets="VT_APIKEY=VT_APIKEY:latest" \
--set-env-vars="TRANSPORT=sse,PORT=8080" \
--port=8080
## 无需 Agent 的验证
由于云服务器禁用了未经身份验证的访问 (`--no-allow-unauthenticated`)，标准的公共请求将被阻止。为了验证其是否正常工作，您的请求必须包含 **授权 OIDC Bearer Token**。
### 选项 A：自动本地验证脚本
确保您已通过 `gcloud` 本地登录到您的 GCP 账户，然后运行本地验证脚本，该脚本会自动处理 OIDC token 的生成并查询远程服务器：
```
# 确保脚本可执行
chmod +x verify.sh
# 针对您的远程 Cloud Run URL 运行
HOST="gti-mcp-server-xxxxxx-uc.a.run.app" PORT="443" ./verify.sh
```
### 选项 B：使用 Curl 进行手动验证
1. **生成与您的 Cloud Run 服务 URL 匹配的 Google ID Token：**
TARGET_URL="https://gti-mcp-server-xxxxxx-uc.a.run.app"
ID_TOKEN=$(gcloud auth print-identity-token --audiences="${TARGET_URL}")
2. **建立 SSE 连接（包含 token）：**
curl -i -H "Authorization: Bearer ${ID_TOKEN}" "${TARGET_URL}/sse"
*预期响应：*
HTTP/1.1 200 OK
Content-Type: text/event-stream
...
event: endpoint
data: /messages/?session_id=da831f24d35e40a0bb5c3da42903e670
3. **发送 JSON-RPC POST 请求（包含 token）：**
curl -s -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ID_TOKEN}" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}' \
"${TARGET_URL}/messages/?session_id=da831f24d35e40a0bb5c3da42903e670"
## MCP 客户端配置
要将此安全的云端部署服务器连接到您的本地桌面 Agent 或云工作流，您必须提供您的 Google OIDC Bearer Token。
### Claude Desktop（连接到安全的 Cloud Run）
更新您的 Claude Desktop 设置 (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```
{
"mcpServers": {
"gti-secure-cloud": {
"url": "https://gti-mcp-server-xxxxxx-uc.a.run.app/sse",
"headers": {
"Authorization": "Bearer YOUR_GOOGLE_OIDC_ID_TOKEN_HERE"
}
}
}
}
```
标签：Google Cloud Run, MCP服务, 威胁情报, 开发者工具, 请求拦截, 逆向工具