微步在线云 API

文件高级搜索

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

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

请求方法

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

请求方式：POSTGET

请求参数说明

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

响应参数说明

序号	参数名称	类型	描述
1	response_code	int	响应正常会返回"0"。其他Response code及对应msg描述参见"响应Code和Msg对照表"
2	verbose_msg	string	响应正常会返回"成功"。其他Response code及对应msg描述参见"响应Code和Msg对照表"
3	cursor	string	下一页的翻页标识。注意查看下一页数据时必须携带此标识，不输入该参数时，默认从第一页返回结果。
4	items	list	文件Hunting结果列表，数组中每组数据代表一个搜索结果，字段说明见"5-14"项所述。返回均返回仅沙箱数据。
5	link_s	string	沙箱详情页查询链接。
6	link_vt	string	VT详情页查询链接。
7	sha256	string	文件的SHA256。
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

#文件高级搜索

#请求方法

#请求参数说明

#响应参数说明