微步在线云 API

提交文件分析

针对办公终端、Web/FTP/邮件附件等疑似恶意文件，终端/服务器的可疑文件等，通过 22 款反病毒扫描引擎快速检测，并根据不同文件类型，系统自动选择可运行的沙箱环境进行动态检测。

调用脚本

请求方法

请求地址： https://api.threatbook.cn/v3/file/upload

请求方式：POST

使用说明

适用场景： 该接口适用于提交可疑文件进行云端多引擎扫描和沙箱动态分析，可用于邮件附件检测、终端可疑文件分析、Web/FTP 上传文件检测等场景。相关场景示例可参考：IM/邮件防钓鱼。

使用建议： 建议在客户已获取可疑文件实体、需要生成云端分析报告时调用。提交后可使用返回的 sha256 继续查询文件信誉报告或文件反病毒引擎检测报告；如需指定运行环境，可根据文件类型和实际受害环境选择合适沙箱。

响应字段解读建议： 该接口响应主要用于确认提交成功并获取后续查询入口。建议重点保存 sha256 作为样本唯一标识，并保留 permalink 便于人工查看沙箱报告。

请求参数说明

序号	参数名称	必选	类型	描述
1	apikey	是	string	API请求的身份识别标识。
2	file	是	string	需要分析的文件，单个文件大小控制在100MB以内。注意：上传文件不要超过 100MB。支持的文件类型包括：PE 可执行文件(EXE、DLL、COM 等)，Office 文档(DOC、XLS、PPT 等)，PDF，HTML，Script，MSI，SWF，JAR，LNK ，ELF，各种压缩包(ZIP、RAR、7Z 等)。
3	sandbox_type	可选	string	沙箱运行环境，用户可以指定文件的沙箱运行环境，可选环境包括： Windows win7_sp1_enx64_office2013 win7_sp1_enx86_office2013 win7_sp1_enx86_office2010 win7_sp1_enx86_office2007 win7_sp1_enx86_office2003 win10_1903_enx64_office2016 Linux ubuntu_1704_x64 centos_7_x64 Kylin kylin_desktop_v10
4	run_time	可选	int	沙箱运行时间，默认60s，根据需求控制在300s以内

响应参数说明

序号	参数名称	类型	描述	使用说明
1	response_code	int	响应正常会返回"0"。其他Response code及对应msg描述参见" 响应Code和Msg对照表"	用于判断本次请求是否成功。业务系统应先判断该字段，再解析 data 内的业务结果；非 0 时建议按异常请求处理。
2	verbose_msg	string	响应正常会返回"Ok"。其他Response code及对应msg描述参见" 响应Code和Msg对照表"	用于展示或记录接口返回说明，适合写入调用日志和错误排查信息；自动化流程建议以 response_code 为主要判断依据。
3	sha256	string	文件的hash值。	提交成功后的样本唯一标识，建议用于后续查询文件报告、终端排查和 IOC 输出。
4	permalink	string	web沙箱报告页网址。	用于跳转到沙箱报告页，适合工单流转、人工复核和报告留存。

请求示例

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

Python

cURL

PHP

Java

Python

import os
import requests
url = 'https://api.threatbook.cn/v3/file/upload';
fields = {
    'apikey': '请替换apikey',
    'sandbox_type': 'win7_sp1_enx86_office2013',
    'run_time': 60
  }
file_dir = '请替换文件地址'
file_name = 'myfile.exe'
files = {
  'file' : (file_name, open(os.path.join(file_dir, file_name), 'rb'))
}
response = requests.post(url, data=fields, files=files)
print(response.json())

响应示例（JSON）

{  
  "verbose_msg": "OK",      // 状态描述
  "response_code": 0,       // 任务状态
  "data":{
    "sha256": "{sha256}",     // 文件的 Hash 值  
    "permalink": "https://s.threatbook.com/report/file/{sha256}"//Web 沙箱报告页网址
  }
}

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

联系我们：api@threatbook.cn

#提交文件分析

#调用脚本

#请求方法

#使用说明

#请求参数说明

#响应参数说明

#请求示例

#响应示例（JSON）