微步在线云 API

文件信誉报告

获取文件详细的静态分析&动态分析报告，包括文件的概要信息、网络行为、行为签名、静态信息、释放行为、进程行为、反病毒扫描引擎检测结果。

调用脚本

请求方法

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

请求方式：POSTGET

使用说明

适用场景： 该接口适用于获取文件的完整静态分析和动态分析报告，可用于恶意样本研判、邮件附件分析、终端可疑文件处置、样本行为分析和威胁报告输出。相关场景示例可参考：IM/邮件防钓鱼。

使用建议： 建议在已获得文件 Hash 或已通过提交文件分析接口获取 sha256 后调用。若只需轻量级多引擎结论，可使用文件反病毒引擎检测报告接口；若需要综合判断样本风险、行为、网络通信和释放文件，应使用本接口。

响应字段解读建议： 建议优先查看 summary.threat_level、summary.malware_type、summary.malware_family、summary.threat_score 和 multiengines 判断样本整体风险；再结合 signature、network、pstree、dropped、strings 和 static 还原样本行为、提取 IOC 并支撑处置建议。

请求参数说明

序号	参数名称	必选	类型	描述
1	apikey	是	string	API请求的身份识别标识。
2	resource	是	string	文件的hash值，用于获取分析报告。支持sha256/sha1/md5。
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	query_fields	可选	string	文件分析报告，默认获取全部，可选数据包括： summary network signature static dropped pstree multiengines strings

响应参数说明

序号	参数名称	类型	描述	使用说明
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	multiengines	object	反病毒扫描引擎检测结果。JSON对象，具体内容项描述如下： result: 每个扫描引擎检测结果说明如下：无检出：显示为safe。有检出：显示具体的检出的病毒结果标签。如：Trojan。 scan_time：多引擎扫描样本的具体时间。示例如：2019-10-22 16:17:48	用于了解多款反病毒引擎的检出情况，是样本风险判断的重要证据之一。
4	summary	object	概要信息。JSON对象，具体内容项描述如下： threat_level：威胁等级。分为malicious（恶意）、suspicious（可疑）、clean（安全）、unknown（未知）四类。此威胁等级判定为结合静态、反病毒多引擎、多沙箱环境动态分析后结果的综合判定结果。 malware_type：威胁分类。样本威胁分类全集参见："样本威胁分类全集"。 malware_family：病毒家族，如Xorddos等。 is_whitelist：是否为白名单文件，true 是白名单，false不是白名单。 submit_time：文件提交时间，示例如：2019-01-22 17:36:21。 file_name：文件名称。 file_type：文件类型。 sample_sha256：文件的 Hash 值。 md5：文件的MD5值。 sha1：文件的SHA1值。 scenes：场景检测。 Cybercrime：黑产样本。 CS_Detect：CobaltStrike木马样本。 RT_Tools：红队工具。 Exploit：漏洞利用。 HW202X：重保样本，根据年份而定。 tag：标签。JSON对象，包含内容项如下： s：静态标签。JSON数组。如："时间戳异常"等。部分常见标签参见： "部分常见样本标签" x：反病毒引擎检测标签。JSON数组。如："Trojan"等。 threat_score：威胁评分值，取值为整数。根据该评分，threat_level 字段会自动判定并输出对应等级：当 threat_score 位于 [5, 29] 区间（含端点）时，threat_level 显示为 unknown；位于 [30, 60] 区间（含端点）时，显示为可疑；当 threat_score 大于 60 时，则显示为恶意。 sandbox_type：本次指定获取的沙箱运行分析环境。运行环境全集参见："沙箱运行环境全集" sandbox_type_list：样本分析成功的所有沙箱运行环境列表。 multi_engines：反病毒扫描引擎检出率。如"7/25"。	文件报告的核心概要，建议优先查看威胁等级、威胁类型、家族、标签、评分和样本 Hash。
5	signature	array	行为签名。JSON数组，每个item包含内容项如下： severity: 严重等级，int类型。数字越高等级越高。 references: 引用， JSON数组。 sig_class: 签名分类。字符串类型。 name: 签名名称。字符串类型。 description: 行为描述。 markcount:标记计数， int类型。 marks: 签名原始数据，JSON数组。 families: 样本家族，JSON数组。 attck_id: ATT&CK ID，int类型。 attck_info: ATT&CK 详情，JSON数组。	用于查看沙箱行为签名，适合理解样本关键恶意行为和报告提炼。
6	static	object	静态信息。JSON对象。所有静态信息报告响应示例参见附录： "文件静态信息报告响应示例全集"	用于查看文件静态结构和特征，适合分析师进一步研判。
7	pstree	object	进程行为。	用于查看样本运行后的进程关系，适合终端排查和行为链还原。
8	network	object	网络行为。 fingerprint：指纹信息，JSON数组。 tls: TLS协议，JSON数组。 udp: UDP协议，JSON数组。 dns_servers: DNS服务，JSON数组。 http: HTTP协议，JSON数组。 irc: IRC 协议，JSON数组。 smtp: SMTP协议，JSON数组。 tcp: TCP协议，JSON数组。 smtp_ex: SMTP 协议数据扩充，JSON数组。 mitm: 中间人，JSON数组。 hosts: 网络主机，JSON数组。 dns: 域名系统，JSON数组。 http_ex: HTTP 协议数据扩充，JSON数组。 domains: 域名，JSON数组。 dead_hosts: 失联主机，JSON数组。 icmp: ICMP协议，JSON数组。 https_ex: HTTPS 协议数据扩充，JSON数组。	用于查看样本网络通信行为，适合提取域名、IP、URL 等 IOC 并开展网络侧处置。
9	dropped	array	释放行为。JSON数组，每个item包含内容如下： sha1: 文件sha1值，字符串类型。 sha256:文件 sha256值，字符串类型。 md5: 文件md5值，字符串类型。 urls:URLs提取，JSON数组。 size: int类型。 filepath: 文件路径，字符串类型。 name:文件名称，字符串类型。 crc32: 文件CRC32，字符串类型。 ssdeep: 文件SSDeep值，字符串类型。 type: 文件类型，字符串类型。 yara: YARA，JSON数组。	用于查看样本释放文件，可继续查询释放文件 Hash 或在终端侧排查。
10	strings	object	字符串相关。JSON对象，每个item包含内容如下： sha256：从文件中提取的字符串，根据sha256变化，对应文件本身静态字符，数组类型。 pcap：从流量中提取的字符串，数组类型。	用于查看文件和流量字符串，适合提取可疑路径、命令、域名、URL 和配置线索。
11	permalink	string	web沙箱报告页网址。	用于跳转到沙箱报告页，适合人工复核、报告留存和协同分析，不建议作为自动化风险判断依据。

请求示例

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

Python

cURL

PHP

Java

Python

import requests

url = 'https://api.threatbook.cn/v3/file/report'
params = {
    'apikey': '请替换apikey',
    'sandbox_type': '请替换运行环境',
    'resource': '请替换文件hash值'
}
response = requests.get(url, params=params)
print(response.json())

响应示例（JSON）

{ 
  "response_code": 0, 
  "data": {   
    "summary": {    // 概要信息     
      "threat_level": "malicious",// 威胁等级(malicious 恶意, suspicious 可疑, clean 安全, unknown 未知)    
      "malware_type": "Trojan",  // 威胁分类，具体详见样本威胁分类全集
      "malware_family": "CobaltStrike",  // 病毒家族  
      "is_whitelist": false,      // 是否为白名单文件，true 白名单     
      "submit_time": "2019-01-22 17:36:21",     // 文件提交时间     
      "file_name": "test.exe",  // 文件名称     
      "file_type": "EXEx86",    // 文件类型     
      "sample_sha256": "{sha256}",  // 文件的 sha256 值  
      "md5": "{md5}", // 文件的MD5值
      "sha1": "{sha1}", // 文件的SHA1值   
      "scenes": [
        "Cybercrime"
      ],
      "tag": {   
        "s": [     // 静态标签     
          "语言neutral",     
          "时间戳异常"  
        ],   
        "x": [     // 检测标签     
          "Trojan"  
        ]     
      },     
      "threat_score": 60,     
      "sandbox_type": "win7_sp1_enx86_office2013",  // 本次指定获取的沙箱运行分析环境.
      "sandbox_type_list": ["win7_sp1_enx86_office2013","win7_sp1_enx86_office2007"],  // 样本分析成功的所有沙箱运行环境列表境 
      "multi_engines": "7/22"   // 反病毒扫描引擎检出率   
    },   
    "multiengines": {   // 反病毒扫描引擎检测结果(safe 无检出，e.g Trojan 检出结果)  
      "result": {
        "Kaspersky": "Trojan",     
        "Microsoft": "safe"   
       },
       "scan_time": "2019-10-22 16:17:48"   //多引擎扫描样本的具体时间
    },
    "static": {     // 静态信息，以 PE 文件为例     
      "details": {   
        "pe_version_info": [],  // PE 文件版本信息   
        "pe_sections": [],  // PE 文件节表信息  
        "pe_signatures": {},    // PE 文件签名信息   
        "pe_imports": [],   // PE 文件导入表信息   
        "pe_resources": [],     // PE 文件资源信息   
        "tag": [],  // PE 文件静态标签   
        "pe_detect": {},    // PE 文件第三方检测信息   
        "pe_basic": {},     // PE 文件基本信息   
        "pe_exports": []    // PE 文件导出表信息     
      },     
      "basic": {    // 文件基本信息   
        "sha1": "{sha1}",   
        "sha256": "{sha256}",   
        "file_type": "{magic}",   
        "file_name": "test.exe",   
        "ssdeep": "{ssdeep}",   
        "file_size": 33397,   
        "md5": "{md5}"     
      }   
    },  
    "signature": [     // 行为签名     
      {   
        "severity": 1,  // 严重等级，数字越高等级越高   
        "references": [],   
        "sig_class": "Static File Characteristics",     // 签名分类   
        "name": "static_linked",    // 签名名称   
        "description": "{"en": "Binary is statically linked", "cn": "此文件是静态链接的"}",//行为描述   
        "markcount": 1,   
        "marks": [],    // 签名原始数据   
        "families": [],   
        "attck_id": "",   
        "attck_info": {}     
      }   
    ],   
    "dropped": [   // 释放行为     
      {   
        "sha1": "{sha1}",   
        "urls": [],   
        "sha256": "{sha256}",   
        "size": 33558,   
        "filepath": "C:\Users\test.exe",   
        "name": "test.exe",   
        "crc32": "",   
        "ssdeep": "{ssdeep}",   
        "type": "{magic}",   
        "yara": [],   
        "md5": "{md5}"     
      }   
    ],  
    "pstree": {     // 进程行为     
      "children": [   
        {     
          "track": true,     
          "pid": 1255,  // 进程 ID     
          "process_name": "",   // 进程名称     
          "command_line": "",   // 进程命令符     
          "first_seen": "17:36:34.047315676",     
          "ppid": 1209,     // 父进程 ID     
          "children": []    // 子进程 list   
        }     
      ],     
      "process_name": {   
        "en": "Analysed 1 processes in total",   
        "cn": "共分析了1个进程"     
      }  
    },  
    "network": {    // 网络行为
      "fingerprint": [],
      "tls": [],     
      "udp": [],     
      "dns_servers": [],     
      "http": [],     
      "irc": [],     
      "smtp": [],     
      "tcp": [],     
      "smtp_ex": [],     
      "mitm": [],     
      "hosts": [],     
      "dns": [],     
      "http_ex": [],     
      "domains": [],     
      "dead_hosts": [],     
      "icmp": [],     
      "https_ex": []   
    },
    "strings": {
      "sha256": [], //从文件中提取的字符串
      "pcap": [] //从流量中提取的字符串
    },
    "permalink": "https://s.threatbook.com/report/file/{sha256}" // web沙箱报告页网址
  }, 
  "verbose_msg": "OK"
}

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

联系我们：api@threatbook.cn

#文件信誉报告

#调用脚本

#请求方法

#使用说明

#请求参数说明

#响应参数说明

#请求示例

#响应示例（JSON）