SurfaceMCP

通过统一 MCP 工具操作 ARL / 灯塔、ScopeSentry、XingRin / 星环。纯 Python，使用 stdio；由 Agent 启动，直接请求配置的平台，无需监听端口。

安装

需要 Python 3.10 或以上版本：

pip install -U surface-mcp

源码安装：pip install .。开发安装：pip install -e '.[dev]'。

方式一：直接在 Agent 中配置

从 0.3.0 起，在支持 stdio 的 MCP 客户端中填写以下配置即可，不需要 YAML 或 .env 文件。env 是 JSON 中的环境变量字段，Agent 会在启动 SurfaceMCP 时传入。

{
  "mcpServers": {
    "surface": {
      "command": "surface-mcp",
      "args": ["serve"],
      "env": {
        "SURFACE_ARL_BASE_URL": "https://arl.example.com",
        "SURFACE_ARL_USERNAME": "admin",
        "SURFACE_ARL_PASSWORD": "your-password",
        "SURFACE_SCOPESENTRY_BASE_URL": "https://scope.example.com",
        "SURFACE_SCOPESENTRY_USERNAME": "ScopeSentry",
        "SURFACE_SCOPESENTRY_PASSWORD": "your-password",
        "SURFACE_XINGRIN_BASE_URL": "https://xingrin.example.com",
        "SURFACE_XINGRIN_USERNAME": "admin",
        "SURFACE_XINGRIN_PASSWORD": "your-password"
      }
    }
  }
}

替换为自己的地址和账号，删除不用的平台对应的环境变量。实例 ID 分别为 arl、scopesentry、xingrin。密码按原文读取。

方式二：使用 YAML 文件

surface-mcp init --config config.yaml

编辑 config.yaml，填写自己的平台地址、用户名和密码，删除不用的平台：

servers:
  arl:
    provider: arl
    base_url: https://arl.example.com
    username: admin
    password: "your-password"
  scopesentry:
    provider: scopesentry
    base_url: https://scope.example.com
    username: ScopeSentry
    password: "your-password"
  xingrin:
    provider: xingrin
    base_url: https://xingrin.example.com
    username: admin
    password: "your-password"

然后让 Agent 加载该文件：

{
  "mcpServers": {
    "surface": {
      "command": "surface-mcp",
      "args": ["serve", "--config", "/absolute/path/config.yaml"]
    }
  }
}

YAML 的实例名称是工具参数 resource_id，可配置多个同类平台；密码支持 ${ARL_PASSWORD} 等环境变量占位符。显式传入 --config 时以该文件为准，不合并 SURFACE_* 配置；省略时读取环境变量。程序不会自动读取 .env 文件。

配置说明

• 无需配置目标白名单即可创建、重启或恢复扫描。0.3.0 已移除 scope.allowed；旧 YAML 请删除该字段。
• 如需排除目标，可选填 YAML scope: {denied: [192.0.2.1]}，或 env 中的 SURFACE_SCOPE_DENIED（逗号或空白分隔）。默认无黑名单，支持 IP、CIDR、域名及 *.example.com。
• HTTPS 默认校验证书；自签名实验环境可在 YAML 设置 verify_tls: false，或设置对应的 SURFACE_ARL_VERIFY_TLS / SURFACE_SCOPESENTRY_VERIFY_TLS / SURFACE_XINGRIN_VERIFY_TLS 为字符串 "false"。
• ARL 支持 YAML api_key 或 SURFACE_ARL_API_KEY，与密码互斥；其他平台使用用户名和密码。
• command 找不到时填写已安装 surface-mcp 的绝对路径。修改配置后重新加载 MCP 连接。不要提交真实凭据。

保存后让 Agent 执行：“列出 ASM 平台并测试连接，暂不创建扫描。”

共 11 项工具：surface_list_resources、surface_test_connection、surface_get_task_profile、surface_list_task_options、surface_create_template、surface_create_task、surface_list_tasks、surface_get_task、surface_list_assets、surface_stop_task、surface_manage_task。

扫描流程：查询参数与动态选项 → 创建任务 → 保存任务 ID → 查询进度 → 读取资产。仅支持显式目标、即时扫描；没有数据库、定时扫描或自动唤醒 Agent。可选黑名单针对提交目标，上游后续发现范围由平台自身控制。

ARL 支持策略创建、重启和删除；ScopeSentry 支持模板创建、恢复、重启和删除；XingRin 支持查询、创建和停止。删除默认保留结果。ScopeSentry 指定模板前须读取 template_detail，并传回 template_verification_token。任务返回 resolution_pending=true 或写请求超时后，应先回查，避免重复提交。

测试

pip install -e '.[dev]'
pytest -q
ruff check src tests

自动测试使用模拟平台和本机 stdio 子进程，不扫描外部目标。发布验证记录见 验证记录。

Apache-2.0；适配器逻辑迁移自 CyberStrikeAI，详见 NOTICE。