SurfaceMCP

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

安装

需要 Python 3.10 或以上版本：

pip install surface-mcp
surface-mcp init --config config.yaml

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

配置

编辑 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"
scope:
  allowed: [192.0.2.1]  # 替换为你有权扫描的目标
  denied: []

• 实例名称是工具参数 resource_id，可配置多个同类平台。
• 密码支持 ${ARL_PASSWORD} 等环境变量；ARL 也支持 api_key，与密码互斥。
• HTTPS 默认校验证书；自签名实验环境可为对应实例设置 verify_tls: false。
• scope.allowed 为空时只能查询和停止任务，不能创建、重启或恢复扫描；拒绝规则优先。支持 IP、CIDR、域名和 *.example.com 范围规则。
• 配置修改后重新加载 Agent 的 MCP 连接。不要提交真实配置。

接入 Agent

在支持 stdio 的 MCP 客户端中添加：

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

command 找不到时，填写已安装 surface-mcp 的绝对路径。配置中的环境变量也必须对 Agent 启动的进程可见。

保存后让 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。