From 2c3ca4b194bfc3aa343588a0439b40ff3b362b13 Mon Sep 17 00:00:00 2001 From: Autumn-27 <53844290+Autumn-27@users.noreply.github.com> Date: Sun, 26 Jul 2026 06:31:32 -0400 Subject: [PATCH] =?UTF-8?q?chore(skill):=20=E6=9B=B4=E6=96=B0=20ScopeSentr?= =?UTF-8?q?y=20skill=20=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/scopesentry/SKILL.md | 139 ++++++++++++++++++++++++++++++------ 1 file changed, 119 insertions(+), 20 deletions(-) diff --git a/skills/scopesentry/SKILL.md b/skills/scopesentry/SKILL.md index e6ad41f..793b54b 100644 --- a/skills/scopesentry/SKILL.md +++ b/skills/scopesentry/SKILL.md @@ -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` | ---- \ No newline at end of file +--- +