chore(skill): 更新 ScopeSentry skill 内容

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-10-27 17:03:49 +08:00 · 2026-07-26 06:31:32 -04:00
1 parent a1778e8990
commit 2c3ca4b194
@@ -1,8 +1,8 @@
 ---
-name: scopesentry
-description: 通过 ScopeSentry  ASM 资产管理安全扫描平台（项目、任务、模板、资产、节点）。在用户提到 ScopeSentry、扫描任务、资产查询时使用。
-mcps: ScopeSentry
---
+
+## name: scopesentry-mcp
+description: 通过 ScopeSentry MCP 管理安全扫描平台（项目、任务、模板、资产、节点）。在用户提到 ScopeSentry、MCP、API Key、扫描任务、资产查询时使用。
+
 # ScopeSentry MCP 使用指南

 面向**已部署 ScopeSentry 实例**的用户。通过 Cursor（或其他 MCP 客户端）连接平台，无需本地源码。
@@ -60,13 +60,16 @@ Cursor → Settings → MCP → 添加服务器：
 | `list_plugins`         | 可用插件（含 hash、默认参数） |
 | `create_scan_template` | 创建扫描模板            |
 | `create_scan_task`     | 创建扫描任务            |
-| `list_assets`          | 查询各类资产            |
+| `list_assets`          | 查询各类资产（分页列表）       |
+| `count_assets`         | 统计资产数量（`/api/assets/common/total`） |
 | `get_asset_detail`     | 资产或漏洞详情           |
 | `add_asset_tag`        | 为资产添加标签           |
 | `list_nodes`           | 扫描节点列表            |


-各工具参数以 MCP 工具描述（schema）为准；`list_assets` 的字段说明最完整，查询资产前可先阅读该工具 description。
+各工具参数以 MCP 工具描述（schema）为准；`list_assets` / `count_assets` 的 search、filter 语法一致，查询资产前可先阅读 `list_assets` description。
+
+需要知道「共多少条」时用 `count_assets`（对应 Web 分页总数接口），不必为了数总数反复翻页 `list_assets`。

 ---

@@ -74,6 +77,8 @@ Cursor → Settings → MCP → 添加服务器：

 ### 3.1 按项目查资产

+当用户或上下文**已有项目条件**时，优先带上 `filter.project` 缩小范围，避免跨项目数据过多导致响应变慢。若无明确项目，可不强制加项目筛选。
+
 1. `list_projects` 或 `list_projects_data` 获取目标项目的 **ObjectID**（`id` / `children[].value`）
 2. `list_assets` 传入 `filter.project`（**必须是 ID，不能写项目中文名**）

@@ -82,7 +87,7 @@ Cursor → Settings → MCP → 添加服务器：
  "asset_type": "asset",
  "pageIndex": 1,
  "pageSize": 20,
-  "search": "domain=example",
+  "search": "domain=^example.com",
  "filter": {
    "project": ["<项目ObjectID>"]
  }
@@ -95,7 +100,76 @@ Cursor → Settings → MCP → 添加服务器：
 2. `list_scan_templates` 或 `create_scan_template` 获取模板 **ObjectID**
 3. `create_scan_task`：`name`、`node` 必填，`template` 填模板 ID（不能填模板名）

-### 3.3 创建扫描模板
+**目标来源 `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`
@@ -103,7 +177,21 @@ Cursor → Settings → MCP → 添加服务器：

 ---

-## 4. 资产查询（`list_assets`）
+## 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`

@@ -130,15 +218,17 @@ Cursor → Settings → MCP → 添加服务器：
 自定义 DSL（**不是 SQL**）：


-| 运算符  | 含义   | 示例                          |
-| ---- | ---- | --------------------------- |
-| `=`  | 模糊匹配 | `domain=example`            |
-| `==` | 精确匹配 | `port==443`                 |
-| `!=` | 排除   | `port!="80"`                |
-| `&&` | 与    | `domain=baidu && port==443` |
-| `||` | 或    | `title=admin || body=login` |
+| 运算符  | 含义   | 索引 | 示例                          |
+| ---- | ---- | ---- | --------------------------- |
+| `=`  | 模糊匹配（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`。
@@ -165,15 +255,21 @@ Cursor → Settings → MCP → 添加服务器：

 **search 示例：**

- `domain=baidu && port==443`
+- `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   | 含义       | 取值说明                                                     |
 | ------------ | -------- | -------------------------------------------------------- |
@@ -221,7 +317,7 @@ JSON 对象：同 key 多个值为 **OR**，不同 key 为 **AND**。
 ```json
 {
  "asset_type": "asset",
-  "search": "domain=baidu && port==443",
+  "search": "domain=^baidu && port==443",
  "filter": {"project": ["<项目ObjectID>"]},
  "pageIndex": 1,
  "pageSize": 10
@@ -230,7 +326,9 @@ JSON 对象：同 key 多个值为 **OR**，不同 key 为 **AND**。

 **注意：**

+- 有项目条件时优先带 `filter.project`（支持时）；无项目上下文可不强制
 - `filter.project` 勿填项目显示名称
+- 已知值用 `==`，前缀用 `^`；避免对大表滥用 `=` 模糊匹配
 - UrlScan 的 HTTP 状态用 `filter.status`；DirScanResult 可在 search 中用 `statuscode==200`
 - SensitiveResult 按规则名：`search` 用 `sname=规则名`，或 `filter.sname`

@@ -261,7 +359,8 @@ JSON 对象：同 key 多个值为 **OR**，不同 key 为 **AND**。
 | 401 / 403 | 重新创建或更换 API Key                                    |
 | 资产查不到     | 确认 `filter.project` 为 ObjectID；勿在 search 写 project |
 | 模板/任务创建失败 | `template` 必须是模板 ObjectID；`node` 填在线节点名            |
-| 查询很慢      | 缩小 `pageSize`，增加 search/filter 条件                  |
+| 查询很慢/卡住   | 有项目时加 `filter.project`；search 对已索引字段改用 `==` 或 `^` 前缀，少用 `=`；缩小 `pageSize` |


 ---
+