dela
0335d572de
ci / go (push) Waiting to run
ci / go-db (agent) (push) Waiting to run
ci / go-db (config) (push) Waiting to run
ci / go-db (db) (push) Waiting to run
ci / go-db (evidence) (push) Waiting to run
ci / go-db (llmrec) (push) Waiting to run
ci / go-db (server) (push) Waiting to run
web / web (push) Waiting to run
docs / links (push) Canceled after 0s
detections / detections (push) Canceled after 0s
367 lines
16 KiB
Markdown
367 lines
16 KiB
Markdown
---
|
||
|
||
## name: scopesentry-mcp
|
||
description: 通过 ScopeSentry MCP 管理安全扫描平台（项目、任务、模板、资产、节点）。在用户提到 ScopeSentry、MCP、API Key、扫描任务、资产查询时使用。
|
||
|
||
# ScopeSentry MCP 使用指南
|
||
|
||
面向**已部署 ScopeSentry 实例**的用户。通过 Cursor（或其他 MCP 客户端）连接平台，无需本地源码。
|
||
|
||
## 1. 准备工作
|
||
|
||
### 1.1 确认服务可访问
|
||
|
||
- 默认 Web 界面：`http://<主机>`
|
||
- MCP 端点：`http://<主机>/mcp`（若前面有反向代理或前端代理，以实际 `/mcp` 地址为准）
|
||
|
||
### 1.2 创建 API Key
|
||
|
||
1. 浏览器登录 ScopeSentry Web 界面
|
||
2. 进入 **API Key** 管理页创建密钥（或通过管理员提供的接口创建）
|
||
3. 保存返回的 `ssk_...` 字符串（**仅显示一次**）
|
||
|
||
### 1.3 配置 Cursor MCP
|
||
|
||
Cursor → Settings → MCP → 添加服务器：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"scopesentry": {
|
||
"url": "http://<你的主机>:8082/mcp",
|
||
"headers": {
|
||
"X-API-Key": "ssk_你的密钥"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
也可使用：`Authorization: Bearer ssk_你的密钥`
|
||
|
||
配置完成后重启 MCP 或重载 Cursor，确认工具列表中出现 `list_projects`、`list_assets` 等。
|
||
|
||
---
|
||
|
||
## 2. 工具一览
|
||
|
||
|
||
| 工具 | 用途 |
|
||
| ---------------------- | ----------------- |
|
||
| `list_projects` | 按标签分组的项目树（含项目 ID） |
|
||
| `list_projects_data` | 分页项目列表，可按名称搜索 |
|
||
| `get_project` | 项目详情 |
|
||
| `create_project` | 新建项目 |
|
||
| `list_tasks` | 扫描任务列表 |
|
||
| `get_task` | 任务详情 |
|
||
| `list_scan_templates` | 扫描模板列表 |
|
||
| `get_scan_template` | 模板详情 |
|
||
| `list_plugin_modules` | 扫描流水线模块名 |
|
||
| `list_plugins` | 可用插件（含 hash、默认参数） |
|
||
| `create_scan_template` | 创建扫描模板 |
|
||
| `create_scan_task` | 创建扫描任务 |
|
||
| `list_assets` | 查询各类资产（分页列表） |
|
||
| `count_assets` | 统计资产数量（`/api/assets/common/total`） |
|
||
| `get_asset_detail` | 资产或漏洞详情 |
|
||
| `add_asset_tag` | 为资产添加标签 |
|
||
| `list_nodes` | 扫描节点列表 |
|
||
|
||
|
||
各工具参数以 MCP 工具描述（schema）为准；`list_assets` / `count_assets` 的 search、filter 语法一致，查询资产前可先阅读 `list_assets` description。
|
||
|
||
需要知道「共多少条」时用 `count_assets`（对应 Web 分页总数接口），不必为了数总数反复翻页 `list_assets`。
|
||
|
||
---
|
||
|
||
## 3. 常用工作流
|
||
|
||
### 3.1 按项目查资产
|
||
|
||
当用户或上下文**已有项目条件**时，优先带上 `filter.project` 缩小范围，避免跨项目数据过多导致响应变慢。若无明确项目，可不强制加项目筛选。
|
||
|
||
1. `list_projects` 或 `list_projects_data` 获取目标项目的 **ObjectID**（`id` / `children[].value`）
|
||
2. `list_assets` 传入 `filter.project`（**必须是 ID，不能写项目中文名**）
|
||
|
||
```json
|
||
{
|
||
"asset_type": "asset",
|
||
"pageIndex": 1,
|
||
"pageSize": 20,
|
||
"search": "domain=^example.com",
|
||
"filter": {
|
||
"project": ["<项目ObjectID>"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 创建扫描任务
|
||
|
||
1. `list_nodes` 获取在线节点名称
|
||
2. `list_scan_templates` 或 `create_scan_template` 获取模板 **ObjectID**
|
||
3. `create_scan_task`：`name`、`node` 必填，`template` 填模板 ID（不能填模板名）
|
||
|
||
**目标来源 `targetSource`（与 Web 端一致）：**
|
||
|
||
| targetSource | 说明 | 必填参数 |
|
||
| --- | --- | --- |
|
||
| `general` | 直接输入目标 | `target` |
|
||
| `project` | 从项目读取目标 | `project`（项目 ObjectID 数组） |
|
||
| `asset` | 从 Web 资产库搜索 | `search`；可选 `project`、`filter`、`targetNumber` |
|
||
| `RootDomain` | 从根域名库搜索 | `search`；可选 `project`、`filter`、`targetNumber` |
|
||
| `subdomain` | 从子域名库搜索 | `search`；可选 `project`、`filter`、`targetNumber` |
|
||
| `UrlScan` | 从 URL 扫描结果搜索 | `search`；可选 `project`、`filter`、`targetNumber` |
|
||
| `*Source`（如 `subdomainSource`） | 从资产页「选中/搜索」创建 | `targetTp=search` 时用 `search`；`targetTp=select` 时用 `targetIds` |
|
||
|
||
**示例 — 直接扫根域名：**
|
||
|
||
```json
|
||
{
|
||
"name": "example-子域名收集",
|
||
"node": ["node-1"],
|
||
"template": "<模板ObjectID>",
|
||
"targetSource": "general",
|
||
"target": "example.com\nfoo.com",
|
||
"project": ["<项目ObjectID>"]
|
||
}
|
||
```
|
||
|
||
**示例 — 从子域名库续扫（按上一任务名筛选）：**
|
||
|
||
```json
|
||
{
|
||
"name": "example-端口与漏洞",
|
||
"node": ["node-1"],
|
||
"template": "<后续模块模板ObjectID>",
|
||
"targetSource": "subdomain",
|
||
"search": "task==\"example-子域名收集\"",
|
||
"project": ["<项目ObjectID>"]
|
||
}
|
||
```
|
||
|
||
### 3.3 根域名完整信息收集（推荐两阶段）
|
||
|
||
当输入为**根域名**且要进行**完整信息收集**时，建议分两次扫描，不要一次跑全流水线。
|
||
|
||
**原因：** 分布式任务以**单个目标**为单位分发。根域名作为目标时，某节点分到该根域名后，在该节点上扫出的子域名也会继续在该节点执行后续模块，容易造成负载不均、速度慢、易出错。
|
||
|
||
**最佳实践：**
|
||
|
||
1. **第一阶段 — 仅子域名收集**
|
||
- `targetSource`: `general`
|
||
- `target`: 所有根域名（多行）
|
||
- 模板：仅启用 `SubdomainScan`、`SubdomainSecurity`（子域名扫描 + 子域名接管）
|
||
- 用 `get_task` 等待任务完成
|
||
|
||
2. **第二阶段 — 后续模块**
|
||
- `targetSource`: `subdomain`
|
||
- `search`: `task=="<第一阶段任务名称>"`（精确匹配任务名）
|
||
- 可选 `project` 缩小范围
|
||
- 模板：端口扫描、资产测绘、漏洞扫描等（可不含 SubdomainScan）
|
||
- 子域名作为独立目标分发到各节点，并行效率更高
|
||
|
||
也可在 Web 界面「子域名」资产页按任务名筛选后，使用「从子域名创建任务」，效果相同。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[根域名列表] --> B[阶段1: general + SubdomainScan]
|
||
B --> C[子域名入库]
|
||
C --> D[阶段2: subdomain + task==阶段1任务名]
|
||
D --> E[端口/资产/漏洞等模块]
|
||
```
|
||
|
||
### 3.4 创建扫描模板
|
||
|
||
1. `list_plugin_modules` → 模块名列表
|
||
2. `list_plugins`（可按 `module` 过滤）→ 各插件 `hash` 与默认 `parameter`
|
||
3. `create_scan_template`：用 `modules` 指定「模块 → 插件 hash 数组」
|
||
|
||
---
|
||
|
||
## 4. 资产查询（`list_assets` / `count_assets`）
|
||
|
||
`count_assets` 与 `list_assets` 使用相同的 `asset_type`、`search`、`filter`，返回 `{ "total": N }`，对应 Web 端 `/api/assets/common/total`。
|
||
|
||
```json
|
||
{
|
||
"asset_type": "subdomain",
|
||
"search": "task==\"某任务名\"",
|
||
"filter": {"project": ["<项目ObjectID>"]}
|
||
}
|
||
```
|
||
|
||
**性能建议（`list_assets` / `count_assets` 通用）：** 有项目条件时优先用 `filter.project` 缩小范围；`search` 中对已建索引字段尽量用 `==` 全等或 `^` 前缀匹配（见 [4.3](#43-search-搜索表达式)），避免大面积 `=` 模糊查询拖慢响应。无项目上下文时不强制加项目筛选。
|
||
|
||
支持 `filter.project` 的类型见 [4.4](#44-filter-精确过滤) 表格。
|
||
|
||
### 4.1 资产类型 `asset_type`
|
||
|
||
`asset`、`RootDomain`、`subdomain`、`app`、`mp`、`UrlScan`、`SensitiveResult`、`DirScanResult`、`crawler`、`vulnerability`、`PageMonitoring`、`IPAsset`、`SubdomainTakerResult`
|
||
|
||
别名示例：`web`→asset、`vuln`→vulnerability、`ip`→IPAsset、`url`→UrlScan
|
||
|
||
### 4.2 参数说明
|
||
|
||
|
||
| 参数 | 说明 |
|
||
| ------------------------ | --------------------------------------- |
|
||
| `pageIndex` / `pageSize` | 分页，默认 1 / 20 |
|
||
| `search` | 搜索表达式（见下节） |
|
||
| `filter` | 精确过滤 JSON（见下节） |
|
||
| `sort` | 仅 UrlScan、DirScanResult 支持按 `length` 排序 |
|
||
| `sid` | 仅 SensitiveResult：敏感规则名称 |
|
||
|
||
|
||
`search` 与 `filter` **可同时使用**。
|
||
|
||
### 4.3 search 搜索表达式
|
||
|
||
自定义 DSL（**不是 SQL**）：
|
||
|
||
|
||
| 运算符 | 含义 | 索引 | 示例 |
|
||
| ---- | ---- | ---- | --------------------------- |
|
||
| `=` | 模糊匹配（regex） | 不走索引 | `domain=example` |
|
||
| `==` | 精确匹配（全等） | **走索引** | `port==443` |
|
||
| `!=` | 排除 | — | `port!="80"` |
|
||
| `&&` | 与 | — | `domain==example.com && port==443` |
|
||
| `||` | 或 | — | `title=admin || body=login` |
|
||
|
||
|
||
**索引与运算符：** `domain`、`ip`、`port`、`title` 等字段已建索引，但仅 **`==` 全等** 或 **值以 `^` 开头的前缀匹配**（如 `domain=^example.com`）能走索引；**`=` 会转为 regex 模糊匹配，无法使用索引**，数据量大时易变慢。
|
||
|
||
**所有类型通用 search 字段：** `tag`、`task`（任务名称）、`rootDomain`
|
||
|
||
**project 不能写在 search 里**（无效或与 `&&` 组合时报错）。筛项目请用 `filter.project`。
|
||
|
||
**各类型常用 search 字段：**
|
||
|
||
|
||
| asset_type | 字段 |
|
||
| -------------------- | ----------------------------------------------------------------------------------- |
|
||
| asset | domain, ip, port, service, app, title, statuscode, icon, banner, type, body, header |
|
||
| RootDomain | domain, icp, company |
|
||
| subdomain | domain, ip, type, value |
|
||
| app | name, icp, company, category, description, url, apk |
|
||
| mp | name, icp, company, category, description, url |
|
||
| UrlScan | url, input, source, resultId, type |
|
||
| SensitiveResult | url, sname, body, info, md5 |
|
||
| DirScanResult | url, statuscode, redirect, length |
|
||
| vulnerability | url, vulname, matched, request, response, level |
|
||
| crawler | url, method, body, resultId |
|
||
| PageMonitoring | url, hash, diff, response |
|
||
| IPAsset | ip, domain, port, service, webServer, app |
|
||
| SubdomainTakerResult | domain, value, type, response |
|
||
|
||
|
||
**search 示例：**
|
||
|
||
- `domain==www.example.com && port==443`（全等，走索引）
|
||
- `domain=^example.com`（前缀匹配，走索引）
|
||
- `ip==192.168.1.1`
|
||
- `task=="某任务名"`
|
||
- `level==high`（vulnerability）
|
||
- `statuscode==200`（DirScanResult）
|
||
|
||
需模糊包含时再用 `=`，如 `title=admin`（不走索引，宜配合项目等条件缩小范围）。
|
||
|
||
### 4.4 filter 精确过滤
|
||
|
||
JSON 对象：同 key 多个值为 **OR**，不同 key 为 **AND**。
|
||
|
||
**有项目条件时优先用 `project`：** 若用户或上下文已明确项目，且 asset_type 支持 `project`，应带上以缩小范围；无项目信息时不强制。
|
||
|
||
|
||
| filter key | 含义 | 取值说明 |
|
||
| ------------ | -------- | -------------------------------------------------------- |
|
||
| `project` | 所属项目 | **ObjectID**，用 `list_projects` / `list_projects_data` 获取 |
|
||
| `task` | 来源任务 | **任务名称**，用 `list_tasks` 的 `name` |
|
||
| `port` | 端口 | 如 `"443"` |
|
||
| `service` | 服务/协议 | 如 `"https"` |
|
||
| `app` | 应用指纹 | 如 `"Nginx"` |
|
||
| `icon` | 图标 hash | |
|
||
| `statuscode` | HTTP 状态码 | 主要用于 asset |
|
||
| `status` | 状态 | UrlScan/DirScan HTTP 码；漏洞/敏感信息处理状态 |
|
||
| `level` | 漏洞等级 | critical / high / medium / low / info |
|
||
| `type` | 类型 | 如子域名记录类型 A、CNAME |
|
||
| `color` | 敏感规则颜色 | SensitiveResult |
|
||
| `sname` | 敏感规则名 | SensitiveResult |
|
||
| `tags` | 标签 | |
|
||
|
||
|
||
**各类型可用 filter key：**
|
||
|
||
|
||
| asset_type | filter key |
|
||
| ------------------------------------- | --------------------------------------------------------------- |
|
||
| asset | project, port, service, app, icon, statuscode, type, task, tags |
|
||
| RootDomain | project, tags |
|
||
| subdomain | project, type, task, tags |
|
||
| app / mp | project, tags |
|
||
| UrlScan | status, tags |
|
||
| DirScanResult | status, tags |
|
||
| SensitiveResult | status, color, sname, tags |
|
||
| crawler | project, task, tags |
|
||
| vulnerability | project, level, status, task, tags |
|
||
| PageMonitoring / SubdomainTakerResult | tags |
|
||
| IPAsset | project, port, service, app |
|
||
|
||
|
||
**filter 示例：**
|
||
|
||
```json
|
||
{"project": ["<项目ObjectID>"], "port": ["443"]}
|
||
```
|
||
|
||
**组合查询示例：**
|
||
|
||
```json
|
||
{
|
||
"asset_type": "asset",
|
||
"search": "domain=^baidu && port==443",
|
||
"filter": {"project": ["<项目ObjectID>"]},
|
||
"pageIndex": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
**注意：**
|
||
|
||
- 有项目条件时优先带 `filter.project`（支持时）；无项目上下文可不强制
|
||
- `filter.project` 勿填项目显示名称
|
||
- 已知值用 `==`，前缀用 `^`；避免对大表滥用 `=` 模糊匹配
|
||
- UrlScan 的 HTTP 状态用 `filter.status`；DirScanResult 可在 search 中用 `statuscode==200`
|
||
- SensitiveResult 按规则名：`search` 用 `sname=规则名`，或 `filter.sname`
|
||
|
||
### 4.5 排序 sort
|
||
|
||
仅 **UrlScan**、**DirScanResult** 支持：
|
||
|
||
```json
|
||
{"length": "ascending"}
|
||
```
|
||
|
||
其他类型忽略 `sort`，按时间默认排序。
|
||
|
||
---
|
||
|
||
## 5. 扫描模板模块名
|
||
|
||
`TargetHandler`、`SubdomainScan`、`SubdomainSecurity`、`PortScanPreparation`、`PortScan`、`PortFingerprint`、`AssetMapping`、`AssetHandle`、`URLScan`、`WebCrawler`、`URLSecurity`、`DirScan`、`VulnerabilityScan`、`PassiveScan`
|
||
|
||
---
|
||
|
||
## 6. 故障排查
|
||
|
||
|
||
| 现象 | 处理 |
|
||
| --------- | -------------------------------------------------- |
|
||
| MCP 无工具 | 检查 URL、API Key、ScopeSentry 是否运行 |
|
||
| 401 / 403 | 重新创建或更换 API Key |
|
||
| 资产查不到 | 确认 `filter.project` 为 ObjectID；勿在 search 写 project |
|
||
| 模板/任务创建失败 | `template` 必须是模板 ObjectID；`node` 填在线节点名 |
|
||
| 查询很慢/卡住 | 有项目时加 `filter.project`；search 对已索引字段改用 `==` 或 `^` 前缀，少用 `=`；缩小 `pageSize` |
|
||
|
||
|
||
---
|
||
|