微步在线云 API

文件高级搜索

文件高级搜索 API 提供基于 Hunting 查询语句 的高阶检索能力，支持用户以统一、灵活的查询语法，对海量文件样本进行精准搜索与分析。

通过该 API，用户可将复杂的 Hunting 规则程序化地接入业务系统，快速获取与安全分析、威胁狩猎相关的文件结果。

请求方法

请求地址： https://api.threatbook.cn/v3/hunting/query

请求方式：POSTGET

使用说明

适用场景： 该接口适用于基于 Hunting 查询语法进行样本库检索，可用于威胁狩猎、样本批量发现、同类样本扩线、IOC 验证和专题样本分析。

使用建议： 建议在已经明确检索条件或狩猎规则后调用，例如文件名、Hash、内容片段、文件类型、检测标签、时间范围等。查询结果可作为后续文件信誉报告查询、样本下载申请、专题分析或威胁狩猎报告的输入。

响应字段解读建议： 建议先结合 items 中的 sha256、detection、malware_type、malware_family、first_seen、last_seen 判断样本风险和活跃时间；再使用 link_s、segments 等字段进行人工复核和命中原因解释。结果较多时应使用 cursor 分页获取。

请求参数说明

序号	参数名称	必选	类型	描述
1	apikey	是	string	API请求的唯一标识。
2	query	是	string	符合Hunting查询逻辑和查询语法Hunting查询语句。语句可参考：“Hunting语法说明与运算逻辑” 注意：参数值必须携带英文””，例如 file_name=”abc” 对于包含特殊字符的参数，需要将参数URL Encode之后传递，例如content=”GH%3Fder()”
3	cursor	否	string	翻页标识，不输入该参数时，默认从第一页返回结果。每页最多返回500条数据。

响应参数说明

序号	参数名称	类型	描述	使用说明
1	response_code	int	响应正常会返回"0"。其他Response code及对应msg描述参见"响应Code和Msg对照表"	用于判断本次请求是否成功。业务系统应先判断该字段，再解析 data 内的业务结果；非 0 时建议按异常请求处理。
2	verbose_msg	string	响应正常会返回"成功"。其他Response code及对应msg描述参见"响应Code和Msg对照表"	用于展示或记录接口返回说明，适合写入调用日志和错误排查信息；自动化流程建议以 response_code 为主要判断依据。
3	cursor	string	下一页的翻页标识。注意查看下一页数据时必须携带此标识，不输入该参数时，默认从第一页返回结果。	用于分页获取后续结果。需要继续拉取数据时，将该值带入下一次请求；不应将其理解为固定页码。
4	items	list	文件Hunting结果列表，数组中每组数据代表一个搜索结果，字段说明见"5-14"项所述。返回均返回仅沙箱数据。	每个 item 代表一个命中的样本结果，适合批量导出、进一步查询文件报告或沉淀狩猎线索。
5	link_s	string	沙箱详情页查询链接。	用于跳转查看沙箱详情页，适合人工复核和报告留存。
6	link_vt	string	VT详情页查询链接。	用于外部交叉验证，适合作为补充参考；若客户环境不允许访问外部平台，可不作为处置依赖。
7	sha256	string	文件的SHA256。	样本唯一标识，建议作为后续查询文件报告、终端排查和 IOC 输出的主键。
8	file_name	string	文件名。	用于识别样本名称和形态，但文件名可能被伪造，不建议作为唯一判断依据。
9	file_size	int	文件大小。	用于筛选样本类型和排查异常文件，适合与其他条件组合分析。
10	file_type	string	文件类型。	用于理解样本格式，帮助选择后续分析方式。
11	detection	string	多引擎检出率。	用于快速评估多引擎检出强度，检出率越高越适合优先查看。
12	first_seen	timestamp	首次提交时间。	用于判断样本首次出现时间，适合发现新样本或追踪历史传播。
13	last_seen	timestamp	末次分析时间。	用于判断样本近期活跃度或最近观察时间。
14	malware_type	string[]	威胁分类,可能有多个	用于按威胁分类筛选和聚合结果，如恶意软件、勒索、挖矿等。
15	malware_family	string[]	病毒家族,可能有多个	用于按病毒家族聚合样本，适合专题分析和威胁狩猎。
16	segments	objects	仅在使用content搜索时出现，列出对应文件所有命中的segments片段。	仅在内容检索时出现，用于解释样本命中查询条件的具体片段，适合人工复核和规则调优。

请求示例

微步在线云API支持cURL、Python、PHP、Java、Go语言的请求，以Python为例：

Python

cURL

PHP

Java

Python

import requests

url = "https://api.threatbook.cn/v3/hunting/query"

query = {
  "apikey":"请替换apikey",
  "query":"请替换hunting查询语句"
}

response = requests.request("GET", url, params=query)

print(response.json())

响应示例（JSON）

{
    "response_code": 0,
    "verbose_msg": "成功",
    "data": {
        "cursor": "xxxxxxxxxxxxxxxxxxxxx",
        "items": [
            {
                "link_s": "https://s.threatbook.com/report/file/9145f476a9f1f3b793709276de9631dd406e4f240863bbf3d6c66bc3456feb4d",
                "link_vt": "https://www.virustotal.com/gui/file/9145f476a9f1f3b793709276de9631dd406e4f240863bbf3d6c66bc3456feb4d",
                "sha256": "9145f476a9f1f3b793709276de9631dd406e4f240863bbf3d6c66bc3456feb4d",
                "file_name": "9145f476a9f1f3b793709276de9631dd406e4f240863bbf3d6c66bc3456feb4d",
                "file_size": 64000,
                "file_type": "PE32 executable (GUI) Intel 80386, for MS Windows",
                "detection": "12/28",
                "first_seen": "2025-08-24 15:00:58",
                "last_seen": "2025-10-15 15:37:59",
                "malware_type": ["恶意软件"],
                "malware_family": ["Andromeda"]
                "segments": {
                    "77200": "522801fa8b45e45057ffd2ff55ec58eb06ff55ecff55ec83c408ff55ecff55f483c40861c30000000000000000000000"
                }
            }
        ]
    }
}

云API是北京微步在线科技有限公司旗下产品了解微步在线《用户服务条款》《数据保护政策》

联系我们：api@threatbook.cn

#文件高级搜索

#请求方法

#使用说明

#请求参数说明

#响应参数说明

#请求示例