Blackpoint Cyber

blackpoint-mcp

Blackpoint Cyber CompassOne 的模型上下文协议（MCP）服务——托管检测与响应（MDR）平台。

功能

此 MCP 服务通过决策树导航界面提供对 CompassOne 安全功能的访问：

可用领域

• 🏢 租户：客户租户管理
• 💻 资产：按文档记录的类别（CONTAINER、DEVICE、FRAMEWORK、NETSTAT、PERSON、PROCESS、SERVICE、SOFTWARE、SOURCE、SURVEY、USER）分类的资产清单。CLOUD 不是资产类别。
• 🔍 检测：来自 GET /alert-groups 的警报组（OPEN / RESOLVED、skip / take）
• 🛡️ 漏洞：漏洞管理、暗网监控、外部暴露扫描

领域结构

所有已实现的工具都会在一次 tools/list 调用中一并列出，无需 导航步骤。blackpoint_status 会报告当前运行状况和 可用领域；blackpoint_navigate/blackpoint_back 仍为喜欢引导式菜单的 客户端保留，但它们是可选的：每个领域工具 （blackpoint_tenants_*、blackpoint_assets_*、blackpoint_detections_*、 blackpoint_vulnerabilities_*）从一开始就可以直接调用。

（早期版本会要求先调用 blackpoint_navigate，才能使用领域工具。 在 Conduit 网关后方，这种方式行不通——出于安全原因，Conduit 会从所有供应商的工具列表中 隐藏 _navigate/_back，导致所有领域工具都无法通过它访问。现在工具列表是扁平的， 因此无论在哪里都能以相同方式使用。）

工具命名约定

所有工具都遵循以下模式：blackpoint_{domain}_{action}

示例：

• blackpoint_assets_list - 按类别列出资产
• blackpoint_detections_list - 列出安全检测项
• blackpoint_vulnerabilities_scans_list - 列出漏洞扫描

安装

npm install blackpoint-mcp

配置

环境变量

变量	描述	必填
BLACKPOINT_API_TOKEN	CompassOne API 令牌	stdio 模式下必填
BLACKPOINT_BASE_URL	API 基础 URL。默认为 https://api.blackpointcyber.com/v1。值可以包含或不包含 /v1，也可以使用旧版主机 api.compassone.blackpointcyber.com；这些值都会被规范化为该 URL。其他主机保留其源地址，并添加单个 /v1 后缀。	否
MCP_TRANSPORT	传输模式：stdio 或 http	否（默认：stdio）
MCP_HTTP_PORT	网关模式的 HTTP 端口	否（默认：8080）
MCP_HTTP_HOST	HTTP 绑定地址。未设置时绑定到 127.0.0.1。容器映像会设置为 0.0.0.0。	否（默认：127.0.0.1）
CONDUIT_S2S_SECRET	HTTP 服务间密钥。/mcp 要求提供有效的 X-Gateway-S2S 标头。此值为空时，HTTP 服务会以非零状态码退出。	HTTP 模式下必填
MCP_ALLOW_INSECURE_DEV	设置为 1，即可在未设置 CONDUIT_S2S_SECRET 时启动 HTTP。会记录警告并跳过 S2S 检查。仅用于本地开发。	否
AUTH_MODE	设置为 gateway 以启用基于标头的身份验证	否
LOG_LEVEL	日志级别：debug、info、warn、error	否（默认：info）

网关模式

当 AUTH_MODE=gateway 时，服务会从 HTTP 请求头读取凭据，不会回退到 process.env：

• X-Blackpoint-API-Token → API 令牌（必需；缺少请求头时返回 HTTP 401）
• X-Blackpoint-Base-Url → 本次请求的基础 URL（按与 BLACKPOINT_BASE_URL 相同的方式规范化）。缺少此请求头时，不会使用进程环境变量。

这样，支持多租户的网关即可针对每个请求进行身份验证。

HTTP 还要求设置 CONDUIT_S2S_SECRET。每个 /mcp 请求都必须携带与该密钥匹配的有效 X-Gateway-S2S 请求头。缺少请求头或请求头无效时，会在读取供应商凭据之前返回 HTTP 401。如果 CONDUIT_S2S_SECRET 为空，进程会记录错误并以非零状态退出，而不会提供 /mcp 服务。设置 MCP_ALLOW_INSECURE_DEV=1 后，进程仍会启动并记录警告；请勿在本地开发环境之外使用此设置。密钥绝不会写入日志。

GET /、GET /health 和 GET /healthz 仍是无需身份验证的存活检查，不会读取凭据。stdio 传输不使用 S2S 密钥。

用法

独立模式（stdio）

# Set credentials
export BLACKPOINT_API_TOKEN="your-api-token"

# Run the server
blackpoint-mcp

网关模式（HTTP）

export AUTH_MODE=gateway
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=8080
export CONDUIT_S2S_SECRET="your-s2s-secret"
# Optional. Unset binds to 127.0.0.1.
# export MCP_HTTP_HOST=127.0.0.1

blackpoint-mcp

不设置密钥的本地开发模式（不安全；会记录警告）：

export MCP_TRANSPORT=http
export MCP_ALLOW_INSECURE_DEV=1

blackpoint-mcp

工具调用示例

// Start by checking available domains
await tools.call("blackpoint_status");

// Navigate to assets domain
await tools.call("blackpoint_navigate", { domain: "assets" });

// List device assets for one tenant (tenantId is sent as x-tenant-id)
await tools.call("blackpoint_assets_list", { 
  class: "DEVICE",
  tenantId: "tenant_123",
  pageSize: 10 
});

// Get specific asset details
await tools.call("blackpoint_assets_get", { 
  id: "asset_12345",
  tenantId: "tenant_123"
});

// Return to navigation
await tools.call("blackpoint_back");

API 覆盖范围

✅ 已实现

领域	工具	描述
tenants	list、get	客户租户管理
assets	list、get、relationships、search	资产清单和关系
detections	list、get	警报组（GET /alert-groups，skip/take，状态为 OPEN 或 RESOLVED）。工具名称保持不变。
vulnerabilities	list、scans_list、darkweb_list、external_list	漏洞管理、暗网和外部暴露

📋 计划中

领域	状态	备注
partners	SDK 已就绪	账户管理——可开始实现
alerts	仅模型	CompassOne 封装程序中没有可用的 API 处理程序
tickets	仅模型	CompassOne 封装程序中没有可用的 API 处理程序
cloud_security	SDK 已就绪	M365/Google/Cisco 入驻——可开始实现
notifications	SDK 已就绪	联系人组和渠道——可开始实现

Partner 与 Tenant 范围

CompassOne 使用分层范围：Partner → Tenants → Assets

• Partner 令牌可访问所有关联的租户
• 限定 Tenant 范围的令牌仅限访问特定客户
• 始终指定 tenantId 参数，以避免跨租户操作

错误处理

服务会提供结构化错误响应：

{
  "content": [{ 
    "type": "text", 
    "text": "Failed to list assets: Authentication failed" 
  }],
  "isError": true
}

常见错误场景：

• 401 / 403：API 密钥无效，或账户无权访问该资源
• 404：基础 URL 或路径错误（线上 API 地址为 https://api.blackpointcyber.com/v1）
• 速率限制：自动重试，并采用指数退避
• 验证：参数无效或缺少必填字段（class、tenantId）

失败日志会记录 HTTP 状态、方法、路径和响应正文。Bearer 令牌会被隐藏。

速率限制

底层 SDK 会自动实施速率限制：

• 默认值：每个 API 密钥每 15 分钟 2000 次请求
• 429 处理：遵循 Retry-After 请求头
• 退避：后续请求采用指数退避

Docker

# Build
docker build -t blackpoint-mcp .

# Run in gateway mode. The image sets MCP_HTTP_HOST=0.0.0.0 and refuses to
# start until CONDUIT_S2S_SECRET is set. Publish the port on loopback.
docker run -p 127.0.0.1:8080:8080 \
  -e AUTH_MODE=gateway \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_PORT=8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  blackpoint-mcp

开发

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test
npm test

# Lint
npm run lint

安全注意事项

API 访问要求

• 访问 API 需要签订 CompassOne Partner Agreement
• 多租户操作需要 Partner 级别的凭据
• 建议使用 限定范围的令牌进行特定租户访问

破坏性操作

以下操作在实现后需要确认：

• 资产隔离/响应操作
• 会触发操作的工单状态更改
• 警报确认/关闭
• 修复工作流

这些操作使用 elicitConfirmation 模式，以防止意外执行。

故障排查

常见问题

未显示任何工具：

• 检查是否已设置 BLACKPOINT_API_TOKEN
• 确认令牌具有正确的作用域
• 检查到 CompassOne API 的网络连接

网关模式无法正常工作：

• 确认已设置 AUTH_MODE=gateway
• 确认已设置 CONDUIT_S2S_SECRET（如果该值为空，HTTP 会退出，除非设置了 MCP_ALLOW_INSECURE_DEV=1）
• 检查是否传入了 X-Gateway-S2S 和 X-Blackpoint-API-Token
• 确认客户端可以访问绑定地址（默认为 127.0.0.1）

速率限制：

• 监控日志中的 429 响应
• 考虑降低请求频率
• 确认令牌未在多个实例间共享

调试日志

export LOG_LEVEL=debug
blackpoint-mcp

健康检查

GET /、GET /health 和 GET /healthz 无需身份验证，也不会读取凭据：

curl -f http://127.0.0.1:8080/health

已验证身份的 MCP 调用

设置了 CONDUIT_S2S_SECRET 时，/mcp 需要 X-Gateway-S2S。在网关模式下，还需要 X-Blackpoint-API-Token：

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: <gateway-signed header>" \
  -H "X-Blackpoint-API-Token: your-token" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "id": 1, "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl", "version": "0.0.0"}}}'

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行修改并添加测试
4. 为新功能遵循领域处理程序模式
5. 提交 pull request

详细指南请参阅 CONTRIBUTING.md。

许可证

Apache-2.0 - 详情请参阅 LICENSE。