# SurfaceMCP

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

## 安装

需要 Python 3.10 或以上版本：

```bash
pip install -U surface-mcp
```

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

## 方式一：直接在 Agent 中配置

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

```json
{
  "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 文件

```bash
surface-mcp init --config config.yaml
```

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

```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 加载该文件：

```json
{
  "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` 或写请求超时后，应先回查，避免重复提交。

## 测试

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

自动测试使用模拟平台和本机 stdio 子进程，不扫描外部目标。发布验证记录见 [验证记录](https://github.com/RuoJi6/surface-mcp/blob/main/docs/validation.md)。

Apache-2.0；适配器逻辑迁移自 [CyberStrikeAI](https://github.com/RuoJi6/CyberStrikeAI)，详见 [NOTICE](https://github.com/RuoJi6/surface-mcp/blob/main/NOTICE)。