carrydela/artex
1
0
Fork 0
Code Issues Pull Requests Actions 10 Packages Projects Releases Wiki Activity

First Commit
ci / go (push) Waiting to run
Details
ci / go-db (agent) (push) Waiting to run
Details
ci / go-db (config) (push) Waiting to run
Details
ci / go-db (db) (push) Waiting to run
Details
ci / go-db (evidence) (push) Waiting to run
Details
ci / go-db (llmrec) (push) Waiting to run
Details
ci / go-db (server) (push) Waiting to run
Details
web / web (push) Waiting to run
Details
docs / links (push) Canceled after 0s
Details
detections / detections (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
dela
2026-10-09 08:38:16 +08:00
commit 0335d572de
756 changed files with 201663 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/scopesentry/SKILL.md
+366
View File
@@ -0,0 +1,366 @@
---
## 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` |
---