UpGuard CyberRisk MCP Server

UpGuard CyberRisk MCP 服务

一个用于与 UpGuard 的 CyberRisk API 集成的模型上下文协议（MCP）服务。此服务通过标准化接口提供全面的安全风险评估和管理功能。

功能

• 67 个 API 工具，涵盖 13 个类别，全面支持安全管理
• 25 个全面的提示词，包括 8 个用于复杂操作的高级工作流提示词
• 实时风险评估，支持供应商监控和数据泄露检测
• 自动生成文档，支持多种输出格式
• 交互式 API 浏览器，提供 Swagger UI 和 Redoc 界面
• 全面的架构验证，包含 22 个 Zod 架构定义
• CI/CD 集成，支持自动部署文档

增强提示词（v1.4.0 新增）

此服务现包含 25 个全面的提示词（8 个增强提示词 + 17 个现有提示词），为复杂安全操作提供引导式工作流：

🔴 风险管理提示词

• upguard_comprehensive_risk_assessment - 完整的风险评估工作流
• upguard_risk_trend_analysis - 多周期风险趋势分析
• upguard_account_risk_dashboard：为你的账户创建风险仪表板。
• upguard_risk_trend_analysis_original：分析指定期间内的风险趋势。
• upguard_risk_severity_analysis：按严重程度分析风险。
• upguard_critical_risk_prioritization：确定关键风险的优先级。
• upguard_risk_type_analysis：按类型分析风险。
• upguard_monthly_risk_report：生成月度风险报告。
• upguard_risk_mitigation_planning：制定风险缓解计划。
• upguard_executive_risk_summary：创建面向管理层的风险摘要。

📊 合规与报告

• upguard_compliance_reporting_suite - 自动生成合规报告

🌐 资产管理

• upguard_domain_lifecycle_management - 完整的域名生命周期工作流
• upguard_bulk_asset_management - 大规模资产管理操作
• upguard_network_security_assessment - 全面的网络安全分析
• upguard_check_domain_risks：检查特定域名的风险。
• upguard_review_typosquatting_for_domain：查看域名的仿冒域名信息。
• upguard_manage_bulk_hostnames_simple：批量添加和移除主机名的简单工作流。

🪝 运维与监控

• upguard_setup_comprehensive_alerting - 完整的告警基础设施设置
• upguard_security_dashboard_setup - 基于角色的安全仪表板配置

🏢 供应商与组织提示词

• upguard_get_my_organization_risks：获取组织的所有风险列表。
• upguard_monitor_new_vendor：开始监控新供应商。
• upguard_assess_vendor_risks：对特定供应商进行风险评估。
• upguard_get_my_organization_details：获取组织的详细信息。
• upguard_list_vendors_with_critical_risks：列出所有存在关键风险的供应商。
• upguard_full_vendor_risk_profile：获取供应商的完整风险概况。
• upguard_monitor_new_vendor_and_send_questionnaire：监控新供应商并向其发送问卷。

🚨 数据泄露与报告提示词

• upguard_investigate_breaches：调查特定域名的数据泄露事件。
• upguard_generate_report：生成报告。
• upguard_investigate_identity_breach_for_domain：调查域名相关的身份数据泄露事件。
• upguard_generate_vendor_report_and_track：生成供应商报告并跟踪其状态。

优势：

• 为复杂的安全工作流提供分步指导
• 多工具编排，结合多个 API 端点
• 为不同利益相关者（CISO、分析师、合规人员）提供基于角色的工作流
• 集成最佳实践，内置安全建议

📖 查看 ENHANCED_PROMPTS.md，了解详细文档和示例。

快速开始

前提条件

• Node.js 18+
• npm 或 yarn
• UpGuard CyberRisk API 凭据

安装

git clone https://github.com/leroylim/upguard-cyberrisk-mcp-server-nodejs.git
cd upguard-cyberrisk-mcp-server-nodejs
npm install

配置

创建 .env 文件并填入你的 UpGuard 凭据：

UPGUARD_API_KEY=your_api_key_here

运行服务

npm start

MCP 配置

要将此服务与 Claude Desktop 或其他兼容 MCP 的客户端配合使用，需要将其添加到 MCP 配置文件中。

适用于 Claude Desktop（Windows/Mac/Linux）

将以下配置添加到你的 claude_desktop_config.json 文件中：

Windows： %APPDATA%\Claude\claude_desktop_config.json Mac： ~/Library/Application Support/Claude/claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "upguard-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/upguard-cyberrisk-mcp-server/src/index.js"
      ],
      "env": {
        "UPGUARD_API_KEY": "your_upguard_api_key_here"
      }
    }
  }
}

适用于 Cursor IDE

将以下配置添加到 Cursor 设置目录中的 mcp.json 文件：

Windows： %APPDATA%\Cursor\User\mcp.json Mac： ~/Library/Application Support/Cursor/User/mcp.json
Linux： ~/.config/Cursor/User/mcp.json

{
  "mcpServers": {
    "upguard-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/upguard-cyberrisk-mcp-server/src/index.js"
      ],
      "env": {
        "UPGUARD_API_KEY": "your_upguard_api_key_here"
      }
    }
  }
}

配置说明

• 替换路径：将 /path/to/your/upguard-cyberrisk-mcp-server/src/index.js 更新为你的实际安装路径
• 替换 API 密钥：将 your_upguard_api_key_here 更新为你的实际 UpGuard API 密钥
• 服务名称：你可以将 upguard-mcp 改为任意名称

获取 UpGuard API 密钥

前提条件：

• 拥有具备管理员权限的 UpGuard 账户（只有管理员可以访问 API 令牌）
• 可以访问 UpGuard 平台：cyber-risk.upguard.com

分步说明：

1. 登录 UpGuard 账户：https://cyber-risk.upguard.com
2. 点击 Settings 图标，位于 UpGuard 右上角
3. 在设置菜单中打开 API 选项卡
4. 创建或管理 API 密钥：
   • 所有现有 API 密钥都会列在此处
   • 点击 “Create new API key” 以生成新密钥
   • 如有需要，也可以在此选项卡中删除现有密钥
5. 复制 API 密钥——它是由字母和数字组成的字符串
6. 将密钥粘贴到 MCP 配置文件中

测试 API 密钥（可选）： 你可以使用 curl 测试 API 密钥是否有效：

curl -H "Authorization: YOUR_API_KEY" "https://cyber-risk.upguard.com/api/public/vendors"

安全说明：

• 妥善保管 API 密钥，不要公开分享
• 只有管理员可以创建和管理 API 密钥
• 你可以创建多个 API 密钥，并根据需要删除
• API 基础 URL 为：https://cyber-risk.upguard.com/api/public

如需了解更多详情，请参阅 UpGuard 官方 API 身份验证指南。

需要重启

更新 MCP 配置后，请重启 Claude Desktop 或 IDE，使更改生效。

文档系统

本项目提供一套全面的文档生成系统，可根据源代码生成多种格式的文档：

📚 可用的文档格式

• 📊 交互式文档中心 - 集中导航并展示统计信息
• 🚀 Swagger UI - 用于测试端点的交互式 API 浏览器
• 📚 Redoc - 美观、专业的 API 文档
• 📖 Markdown - 包含示例、便于阅读的文档
• 🔧 OpenAPI 规范 - 适用于工具的机器可读 API 规范

🛠️ 文档命令

# Generate complete documentation pipeline
npm run docs:full

# Individual generation steps
npm run docs:extract      # Extract tools from source code
npm run docs:generate     # Generate OpenAPI and Markdown
npm run docs:html         # Generate HTML documentation
npm run docs:test         # Validate generated documentation

# Utility commands
npm run docs:clean        # Clean generated files
npm run docs:build        # Generate with mock fallback

📊 文档统计

• 67 个 API 工具，分布在 13 个类别中
• 22 个 Schema 定义，使用 Zod 进行验证
• 54 个带 Schema 的工具（Schema 覆盖率为 80%）
• 195KB OpenAPI 规范，包含全面的示例
• 37KB Markdown 文档，包含身份验证指南

🌐 查看文档

运行 npm run docs:full 后，在浏览器中打开以下任一文件：

• 文档中心：docs/generated/index.html
• Swagger UI：docs/generated/swagger.html
• Redoc：docs/generated/redoc.html
• Markdown：docs/generated/API.md
• OpenAPI 规范：docs/generated/openapi.json

API 类别

🛡️ 风险管理（10 个工具）

• 获取可用风险及风险详情
• 账户和供应商风险监控
• 风险筛选和分类

🏢 供应商管理（16 个工具）

• 监控和管理供应商安全
• 供应商风险评估
• 批量供应商操作

🌐 域名管理（9 个工具）

• 域名监控和分析
• 子域名发现
• 域名风险评估

🔍 IP 管理（5 个工具）

• IP 地址监控
• 网络安全分析
• IP 风险评估

📊 报告生成（7 个工具）

• 自定义安全报告
• 自动报告计划
• 报告数据导出

🚨 泄露监控（2 个工具）

• 数据泄露检测
• 泄露影响分析

⚡ 批量操作（6 个工具）

• 批处理功能
• 批量更新供应商
• 批量数据操作

🔗 Webhook 管理（5 个工具）

• 事件通知设置
• Webhook 配置
• 实时警报

📋 其他类别

• 问卷管理（1 个工具）
• 错拼检测（1 个工具）
• 标签管理（1 个工具）
• 通知管理（1 个工具）
• 常规（3 个工具）

开发

项目结构

├── src/
│   ├── tools/           # API tool implementations
│   │   ├── schemas/     # Zod schema definitions
│   │   ├── risks.js     # Risk management tools
│   │   ├── vendors.js   # Vendor management tools
│   │   └── ...          # Other tool categories
│   └── utils/
│       ├── doc-generator.js  # Documentation generator
│       └── logger.js         # Logging utility
├── scripts/
│   ├── extract-tools-direct.js  # Tool extraction
│   ├── generate-docs.js         # Documentation generation
│   ├── generate-html-docs.js    # HTML documentation
│   └── test-docs.js             # Documentation testing
├── docs/
│   ├── generated/       # Generated documentation
│   └── extracted-tools.json    # Extracted tool data
└── .github/workflows/
    └── docs.yml         # CI/CD documentation pipeline

添加新工具

1. 在相应类别文件中创建工具实现
2. 将 schema 定义添加到 src/tools/schemas/index.js
3. 运行 npm run docs:full 更新文档
4. 使用 npm run docs:test 进行测试

Schema 验证

所有工具都使用 Zod schema 验证输入：

const { z } = require('zod');
const { vendorHostname, labels } = require('./schemas');

// Tool with schema validation
server.tool('tool_name', 'Description', {
  hostname: vendorHostname,
  labels: labels.optional()
}, async (args) => {
  // Implementation
});

CI/CD 集成

项目通过 GitHub Actions 自动生成文档：

• 触发条件：推送到 main/master、工具文件变更、手动触发
• 生成内容：自动生成所有格式的文档
• 部署内容：带有交互式文档的 GitHub Pages
• 构建产物：文档文件，保留 30 天

测试

# Run all tests
npm test

# Lint code
npm run lint
npm run lint:fix

# Test documentation
npm run docs:test

贡献

1. Fork 此仓库
2. 创建功能分支
3. 添加带有适当 schema 的工具
4. 使用 npm run docs:full 更新文档
5. 使用 npm run docs:test 测试更改
6. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

支持

• GitHub Issues：报告错误或请求功能
• 文档：可在 docs/generated/ 中查看多种格式的文档
• API 参考：交互式 Swagger UI 和 Redoc 界面

---

UpGuard CyberRisk MCP Server v1.4.0 | MIT 许可 | 查看文档