Metadata-Version: 2.5
Name: surface-mcp
Version: 0.2.0
Summary: A unified stdio MCP server for ARL, ScopeSentry and XingRin attack surface management platforms
Project-URL: Homepage, https://github.com/RuoJi6/surface-mcp
Project-URL: Repository, https://github.com/RuoJi6/surface-mcp
Project-URL: Issues, https://github.com/RuoJi6/surface-mcp/issues
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: arl,asm,attack-surface-management,mcp,scopesentry,xingrin
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2.2
Requires-Dist: pyyaml<7,>=6.0.2
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.11; extra == 'dev'
Requires-Dist: twine<8,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# SurfaceMCP

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

## 安装

需要 Python 3.10 或以上版本：

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

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

## 配置

编辑 `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"
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 客户端中添加：

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

## 测试

```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)。
