artex/skills/scopesentry/SKILL.md

---

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 → 添加服务器：

{
  "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，不能写项目中文名）

{
  "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

示例 — 直接扫根域名：

{
  "name": "example-子域名收集",
  "node": ["node-1"],
  "template": "<模板ObjectID>",
  "targetSource": "general",
  "target": "example.com\nfoo.com",
  "project": ["<项目ObjectID>"]
}

示例 — 从子域名库续扫（按上一任务名筛选）：

{
  "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 界面「子域名」资产页按任务名筛选后，使用「从子域名创建任务」，效果相同。

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。

{
  "asset_type": "subdomain",
  "search": "task==\"某任务名\"",
  "filter": {"project": ["<项目ObjectID>"]}
}

性能建议（list_assets / count_assets 通用）： 有项目条件时优先用 filter.project 缩小范围；search 中对已建索引字段尽量用 == 全等或 ^ 前缀匹配（见 4.3），避免大面积 = 模糊查询拖慢响应。无项目上下文时不强制加项目筛选。

支持 filter.project 的类型见 4.4 表格。

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
`		`	或

索引与运算符： 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 示例：

{"project": ["<项目ObjectID>"], "port": ["443"]}

组合查询示例：

{
  "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 支持：

{"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

---