jiwoochris/artex-ko/scopesentry

2. 工具一览

各工具参数以 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 端一致）：

示例 — 直接扫根域名：

{
  "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 等待任务完成

1. 第二阶段 — 后续模块

• 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 参数说明

search 与 filter 可同时使用。

4.3 search 搜索表达式

自定义 DSL（不是 SQL）：

索引与运算符： domain、ip、port、title 等字段已建索引，但仅 `==` 全等 或 值以 `^` 开头的前缀匹配（如 domain=^example.com）能走索引；`=` 会转为 regex 模糊匹配，无法使用索引，数据量大时易变慢。

所有类型通用 search 字段： tag、task（任务名称）、rootDomain

project 不能写在 search 里（无效或与 && 组合时报错）。筛项目请用 filter.project。

各类型常用 search 字段：

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：

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. 故障排查