Public API 1.0 版
采用Public API ,可以让你通过建立简单的脚本来访问文件检测分析功能。即不通过Web接口,就可以进行上传扫描文件、查看已完成扫描的报告等操作。
API采用HTTP POST请求和JSON返回,Public API Key每分钟最多支持6次请求。当您需要更多次请求, 请联系 contactus@threatbook.cn,获取Private API。
Private API 可以提供较Public API更高的访问性能,以及更丰富的信息,包括沙箱的行为分析数据,以及安全分析使用的Passive DNS、whois、开源情报等信息。
Public API是一项免费的服务,可供免费的网站和程序使用。 请不要将Public API用于任何商业产品或服务, 不能作为防病毒产品的替代品,也不能用于任何可能直接或间接损害防病毒产业的项目中。更多信息请参考 服务条款
目标受众
本文档适用于想使用JSON和HTTP编写客户端应用程序的程序员们。 本文档假设您能够理解网络和编程的常规思想。虽然代码案例使用的是python语言,但是您可以使用任何语言和API进行交互。
起步
首先,您需要进行注册,之后就可以在个人资料页面看到您的个人API Key。该Key将用于您的所有API操作。
传送和扫描文件
您可以通过Public API上传扫描文件。我们建议您在上传文件之前先检索最新版的文件报告,看它是否满足您的要求, 以便节省时间和带宽。请把上传文件大小控制在80MB以内,如果您需要上传更大的文件,请联系我们contactus@threatbook.cn。
如需扫描文件,请执行如下链接的HTTP POST请求:
https://x.threatbook.cn/api/v1/file/scan
API调用需要文件以multipart/form-data方式提交,详见参数说明及示例代码。
参数:下载文档
• apikey:注册后获取的个人API Key。
• file:该部分包含上传文件的文件名和文件本身。
例子中使用python的postfile.py来发送文件实体。使用之前请下载postfile.py,并放在与代码文件相同目录中。
请参考以下用法: 下载示例
import postfile
host = "x.threatbook.cn"
selector = "https://x.threatbook.cn/api/v1/file/scan"
fields = [("apikey", "-YOUR API KEY HERE-")]
file_content = open("sample.txt", "rb").read()
files = [("file", "sample.txt", file_content)]
json = postfile.post_multipart(host, selector, fields, files)
print json
                  
{
  "response_code": 1,
  "verbose_msg": "Your scan request has been submitted and queued, please come back for the report later.",
  "resource": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063",
  "scan_id": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  "permalink": "https://x.threatbook.cn/report/scan/01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  "sha256": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063",
  "sha1": "3ffd17c5eeb611aa6a2bf49ba398c02a4cabf013",
  "md5": "8587bba271ef7e6619212c60e3270ef2",
  [...]
}
                  
事后您可以使用scan_id字段在报告检索API中查询本文件的扫描报告。请注意,使用Public API扫描文件的优先级是最低的, 扫描速度取决于平台的负载率和事件的优先级(私有用户的优先级更高),扫描整个文件可能需要几秒钟或几个小时, 您需要使用scan_id定期查询扫描结果,所以为了减小负载、节省时间,请不要重复上传扫描。
重新扫描已提交的文件
本调用可以重新扫描文件库中的文件,无需再次提交,节省了带宽。 我们建议您在重新扫描之前先检索下最新版的文件报告,看它是否满足您的需求,以便节省时间和带宽。
如需重新扫描文件,请执行如下链接的HTTP POST请求:
https://x.threatbook.cn/api/v1/file/rescan
参数: 下载文档
• apikey:注册后获取的个人API Key。
• resource: 一个md5/sha1/sha256类型的hash值。或者多个CSV格式(最多25个)中的任意三个hash的组合, 本类型单次调用即可执行批量请求。请注意,该文件必须是扫描文件库中已存在文件。
请参考以下用法: 下载示例
import json as simplejson
import urllib
import urllib2
url = "https://x.threatbook.cn/api/v1/file/rescan"
parameters = {'apikey': '-YOUR API KEY HERE-', 'resource': '01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063'}
data = urllib.urlencode(parameters)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
json = response.read()
print json
                  
{
  "response_code": 1,
  "verbose_msg": "Your scan request has been submitted and queued, please come back for the report later.",
  "resource": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063",
  "scan_id": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  "permalink": "https://x.threatbook.cn/report/scan/01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  "sha256": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063"
  "sha1": "3ffd17c5eeb611aa6a2bf49ba398c02a4cabf013",
  "md5": "8587bba271ef7e6619212c60e3270ef2",
  [...]
}   
                  
根据response_code的返回值您可以知道hash值对应的文件是否排队成功,等待重新扫描,或该文件在文件库中不存在,或出现了其它未知错误。 事后,您还可以使用scan_id字段在报告检索API中查询本文件的报告。请注意,使用Public API扫描文件的优先级是最低的, 扫描速度取决于平台的负载率和事件的优先级(私有用户的优先级更高),扫描整个文件可能需要几个小时, 您需要使用scan_id定期查询扫描结果,所以请不要重复上传扫描。
检索文件扫描报告
如需检索指定文件的扫描报告,请执行如下链接的HTTP POST请求:
https://x.threatbook.cn/api/v1/file/report
参数: 下载文档
• apikey:个人API关键字。
• resource: 给定一个md5/sha1/sha256类型的hash值,将会检索到该样本的最新报告。您也可以通过指定的scan_id访问该报告。 您也可以通过指定的CSV列表(hash和scan_id的组合,最多4项)访问,单次调用即可执行批量请求。
请参考以下用法:下载示例
import json as simplejson
import urllib
import urllib2
url = "https://x.threatbook.cn/api/v1/file/report"
parameters = {'apikey': '-YOUR API KEY HERE-', 'resource': '01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063'}
data = urllib.urlencode(parameters)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
json = response.read()
print json
                  
{
  "response_code": 1,
  "verbose_msg": "Scan finished, result can be found in the scans key.",
  "resource": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063",
  "scan_id": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  "md5": "8587bba271ef7e6619212c60e3270ef2",
  "sha1": "3ffd17c5eeb611aa6a2bf49ba398c02a4cabf013",
  "sha256": "01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063",
  "scan_date": "2010-05-15 03:38:44",
  "positives": 12,
  "total": 15,
  "scans": {
           "Kingsoft": {"detected": true, "version": "2010-05-14.01", "result": "Trojan.Generic.3611249", "update": "20100514"},
           "TrendMicro": {"detected": true, "version": "10.00", "result": "Trojan.VB.acgy", "update": "20100514"},
           "Qihu360": {"detected": true, "version": "5.400.0.1158", "result": "Generic.dx!rkx", "update": "20100515"},
           "Microsoft": {"detected": true, "version": "6.5.2.0.280", "result": "Trojan/VB.gen", "update": "20100514"},
           "Avira": {"detected": true, "version": "5.0.27.0", "result": "Trojan.VB.JFDE", "update": "20100514"},
           "AVG": {"detected": true, "version": "5115", "result": "avariant of Win32/Qhost.NTY", "update": "20100514"},
           [...]
           },
  "permalink": "https://x.threatbook.cn/report/scan/01f97755e8cd9f931bad6fe08d03326f29d3b449dbe11bab28b889f558675063-1452202902747",
  [...]
}   
                  

根据response_code的返回值您可以知道hash值对应的文件是否排队成功,等待重新扫描,或该文件在文件库中不存在,或出现了其它未知错误。 事后,您还可以使用scan_id字段在报告检索API中查询本文件的报告。请注意,使用Public API扫描文件的优先级是最低的, 扫描速度取决于平台的负载率和事件的优先级(私有用户的优先级更高),扫描整个文件可能需要几个小时, 您需要使用scan_id定期查询扫描结果,所以请不要重复上传扫描。
示例代码和文档下载
以下是一些示例代码,要运行示例代码,请安装Python 2.x版本(https://www.python.org/)。

扫描文件并取结果  下载示例
该示例先上传一个文件进行扫描,等数秒后再去取扫描结果。代码唯一的参数是要扫描的文件路径。
请参考以下用法:
python.exe vbupload.py c:\virus\test.exe
                  
获取文件扫描结果  下载示例
该示例获取一个文件的最近一次的扫描结果。代码唯一的参数是文件HASH值,可以为MD5/SH1/SHA256中的一种。
请参考以下用法:
python.exe vbquery.py 933e1778b2760b3a9194c2799d7b76052895959c3caedefb4e9d764cbb6ad3b5
                  
文档下载
ThreatBook API说明文档  下载文档
该文档详细说明了每个API的输入输出值,以及每个值的含义。
Private API 1.0 版

微步在线威胁分析平台的 Private API遵循REST API的最佳实践和方针,提供一种简便的方式,让您通过任何客户端来调用威胁分析平台数据库中的数据及其检测分析功能。

本文档适用于想使用JSON和HTTP编写客户端应用程序的情况,文档详细介绍了相关API接口参数及输出数据格式。同时提供基于Python的代码示例,当然您可以使用任何语言和API进行交互。

Private API提供的功能包括但不限于:

  • 文件检测:上传文件,以获得多引擎检测结果、文件静态分析报告和动态沙箱分析报告。
  • Hash查询:提交一种类型的Hash值(MD5、SHA1、SHA256),查询相关样本的检测结果,以及静态、动态分析报告。
  • 域名分析:获取域名对应的IP地址、IP地址相关地理位置信息、当前Whois信息、威胁类型、相关攻击团伙或安全事件信息,同时可以根据客户需求提供其它更详尽的情报数据
  • IP分析:获取IP的地理位置信息、相关域名、ASN信息、威胁类型、相关攻击团伙或安全事件信息,同时可以根据客户需求提供其它更详尽的情报数据。
认证

使用Private API,您需要相应的apikey。不同于通过分析平台网站注册得到的Public API apikey。作为我们的商业客户或合作伙伴,我们会通过邮件的方式交付您对应的apikey。

滥用

微步在线针对滥用系统的情况,保留停用账号的权利。滥用有关的活动包括并不限于:约定范围外共享账号、可疑/恶意的查询参数、访问受限制资源等。

文件检测/Hash查询

扫描文件

提交文件进行扫描

HTTP 方法:post

URL:https://x.threatbook.cn/api/v1/file/scan

1. 输入参数

输入 类型 说明
apikey string 用户专属apikey
file 要用multipart/form-data方式提交
notify_url (optional) string 扫描结束后,发通知(POST)到这个URL,POST的内容如下(为多引擎部分的扫描结果):
  • md5:文件的md5值
  • sha1:文件的sha1值
  • sha256:文件的sha256值
  • scan_id:这次扫描的id,用于后面取扫描报告
  • scan_date:扫描时间

2. Python 样例 下载示例

# encoding: UTF-8
#
import httplib, mimetypes
import urllib
import urllib2
import os
import sys
import optparse
import hashlib
import socket
import time
import uuid
# The apikey.
API_KEY = "PUT YOUR APIKEY HERE"
FILE_SIZE_LIMIT = 100 * 1024 * 1024   # 100MB
class postfile:
    @staticmethod
    def post_multipart(host, selector, fields, files):
        content_type, body = postfile.encode_multipart_formdata(fields, files)
        if selector.lower().startswith("https://"):
            h = httplib.HTTPS(host)
        else:
            h = httplib.HTTP(host)
        h.putrequest('POST', selector)
        h.putheader('content-type', content_type)
        h.putheader('content-length', str(len(body)))
        h.endheaders()
        h.send(body)
        errcode, errmsg, headers = h.getreply()
        try:
            ret = h.file.read()
        except Exception, e:
            print "Error - post_multipart"
            return False
        return ret
    @staticmethod
    def encode_multipart_formdata(fields, files):
        BOUNDARY = '----------' + str(uuid.uuid1()).replace('-', '')
        CRLF = '\r\n'
        L = []
        for (key, value) in fields:
            L.append('--' + BOUNDARY)
            L.append('Content-Disposition: form-data; name="%s"' % key)
            L.append('')
            L.append(value)
        for (key, filename, value) in files:
            L.append('--' + BOUNDARY)
            L.append('Content-Disposition: form-data; name="%s"; filename="%s"' % (key, filename))
            L.append('Content-Type: %s' % postfile.get_content_type(filename))
            L.append('')
            L.append(value)
        L.append('--' + BOUNDARY + '--')
        L.append('')
        body = CRLF.join((bytes(i) for i in L))
        content_type = 'multipart/form-data; boundary=%s' % BOUNDARY
        return content_type, body
    @staticmethod
    def get_content_type(filename):
        return mimetypes.guess_type(filename)[0] or 'application/octet-stream'
class ThreatBook(object):
    def __init__(self, api_key):
        super(ThreatBook, self).__init__()
        self.api_key = api_key
    def __repr__(self):
        return "<ThreatBook proxy>"
    def get(self, filename, content):
        print "Getting the report ..., return the result after 3 seconds.\r\n"
        time.sleep(3)
        sha256 = hashlib.sha256(content).hexdigest()
        url = "https://x.ThreatBook.cn/api/v1/file/report"
        
        parameters = {"resource": sha256,
                       "apikey": self.api_key,
                       "dev_id": "test_device",
                       "path": filename}
        data = urllib.urlencode(parameters)
        req = urllib2.Request(url, data)
        response = urllib2.urlopen(req)
        ret_json = response.read()
        print "Report(in JSON):\r\n"
        print ret_json
        return 1;
    def scan(self, filename, content):
        print "File uploading ...\r\n"
        # scan the file
        host = "x.threatbook.cn"
        selector = "https://x.threatbook.cn/api/v1/file/scan"
        fields = [("apikey", self.api_key),("dev_id","test_device")]
        files = [("file", filename, content)]
        ret_json = postfile.post_multipart(host, selector, fields, files)
        if False == ret_json:
            print "Upload failed!"
            return False
        else:
            print "Upload succeed, the response (in JSON):\r\n"
            print ret_json
            return True
def main():
    parser = optparse.OptionParser(usage = """
    %prog <file_path>
Samples:
    %prog c:\\virus\\test.exe
    """)
    (options, arguments) = parser.parse_args()
    if len(sys.argv) < 2:
        parser.print_usage()
        return -1
    filepath = arguments.pop(0)
    if not os.path.exists(filepath):
        print "Error: file not found."
        return -1
    filesize = os.path.getsize(filepath)
    if filesize == 0:
        print "Error: file size is 0."
        return -1;
    if filesize > FILE_SIZE_LIMIT:
        print "Error: file size beyond the limitation: 50MB."
        return -1;
    content = open(filepath, "rb").read()
    filename = os.path.basename(filepath)
    timeout = 300
    socket.setdefaulttimeout(timeout)
    v = ThreatBook(API_KEY)
    v.scan(filepath, content)
    print
    v.get(filename, content)

if __name__ == "__main__":
    main()

                    

3. 输出格式

输出 类型 说明
response_code int 可为以下值:
1: 上传成功,正在排队
-1: 出错,具体看verbose_msg的返回
verbose_msg string response_code相应的Verbose信息
resource string 文件的sha256
scan_id string 用于后面取扫描报告用
permalink string 查看扫描报告的URL
sha256 string 文件的sha256值
sha1 string 文件的sha1值
md5 string 文件的md5值
is_white boolean 为true表示是白名单文件,如Windows操作系统文件
white_desc(optional) string 如果是白名单文件,这里是一个关于是哪种白名单文件的描述

4. 输出样例

输入:

Python.exe scan.py D:abc.exe

输出:

{
    "sha1": "a77548413f6f5b7ce099d22958284090e5d622da",
    "response_code": 1,
    "sha256": "4729c99df1029658bd907d798cb3988fb49154f5f7560c52f9621db03418018c",
    "resource": "4729c99df1029658bd907d798cb3988fb49154f5f7560c52f9621db03418018c",
    "is_white": false,
    "verbose_msg": "Your scan request has been submitted and queued, please come back for the report later.",
    "scan_id": "4729c99df1029658bd907d798cb3988fb49154f5f7560c52f9621db03418018c-1465204082074",
    "permalink": "https://x.threatbook.cn/report/scan/4729c99df1029658bd907d798cb3988fb49154f5f7560c52f9621db03418018c-1465204082074",
    "md5": "f38d03b67fe6e55ce7ca74673ee7e906"
}

获取文件扫描结果

根据scan_id获取之前提交的文件的扫描结果或根据文件HASH得到最近的一次结果。。

HTTP 方法:Get

URL:https://x.threatbook.cn/api/v1/file/report

1. 输入参数

输入 类型 说明
apikey string 用户专属apikey
resource string 可为以下值:
  • 文件的md5/sha1/sha256,获取的是这个文件的最近的扫描结果。
  • 之前提交的文件时返回的scan_id。
  • 批量操作,CSV格式的多个(最多4个)的哈希值或scan_id。
field (optional) string

指定需要获得的信息名称。现在支持的字段名包括:static, sandbox;

要获得多于一个字段的信息,输入参数列出多个字段名称,用英文逗号分割;

不指定本参数内容,将不能获得对应的信息。每个字段能获得的具体信息,参见输出参数中对应的名称说明。

2. Python 样例 下载示例

# encoding: UTF-8
#
import httplib, mimetypes
import urllib
import urllib2
import os
import sys
import optparse
import hashlib
import time
# The apikey. 
API_KEY = "PUT YOUR APIKEY HERE"
class ThreatBook(object):
    def __init__(self, api_key):
        super(ThreatBook, self).__init__()
        self.api_key = api_key
    def __repr__(self):
        return "<ThreatBook proxy>"
    def get(self, hash):
        print "Getting the report ...\r\n"
        #time.sleep(10)
        url = "https://x.threatbook.cn/api/v1/file/report"
        parameters = {"resource": hash,
                       "apikey": self.api_key, 
                       "field": "sandbox,static"}
        data = urllib.urlencode(parameters)
        req = urllib2.Request(url, data)
        response = urllib2.urlopen(req)
        ret_json = response.read()
        print "Report(in JSON):\r\n"
        print ret_json
        return 1;
def main():
    parser = optparse.OptionParser(usage = """
    %prog <hash>
Samples:
    %prog b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db
    """)
    (options, arguments) = parser.parse_args()
    if len(sys.argv) < 2:
        parser.print_usage()
        return -1
    hash = arguments.pop(0)
    
    try:
        v = ThreatBook(API_KEY)
        v.get(hash)
    except Exception, e:
        print "ThreatBook returned a non correct response. See the parameter -l"
if __name__ == "__main__":
    main()

3. 输出格式

输出 类型 说明
response_code int 可为以下值:
  • 0: 请求的文件没有结果
  • 1: 扫描已经完成,返回结果
  • 3: 有部分扫描结果
  • -1: 出错,具体看verbose_msg的返回
verbose_msg string response_code相应的Verbose信息
resource string 和传入的resource一致
scan_id string 这次扫描的id
permalink string 查看扫描报告的URL
sha256 string 文件的sha256值
sha1 string 文件的sha1值
md5 string 文件的md5值
scan_date string 扫描时间
positives int 共有多少引擎返回有毒
total int 共有多少引擎返回扫描结果
total2 int 当前后台共部署了多少扫描引擎
scans array 所有引擎的扫描结果,每个item是一个引擎的结果,包括:
  • 引擎名
  • detected: boolean, 为true表示有毒,为false表示没毒或没有检测
  • version: 引擎的版本
  • result: 查到恶意软件名或safe表示没毒,或timeout表示超时.
  • update: 引擎的病毒库的最后更新时间
is_white(optional) boolean 为true表示是白名单文件,如Windows操作系统文件。
white_desc(optional) string 如果是白名单文件,这里是一个关于是哪种白名单文件的描述。
malware_family(optional) string 恶意软件家族
malware_type(optional) string 恶意软件类型
sandbox(optional) object 沙箱运行结果信息,根据文件不同可能包括:
  • 行为分析(ope_list),给出文件在沙箱中的行为分析信息,例如文件、注册表等操作信息;
  • 网络分析(network),给出文件在沙箱中的各种网络行为;
static(optional) object 文件的静态信息,根据文件不同可能包括:
  • PE段信息(pe_sections)
  • 导入dll信息(pe_imports)
  • 证书信息(File Sign)
  • 属性信息(ver_info)等信息

4. 输出样例

输入:

Python.exe report.py                                                                               
 2f835af9497d817bd5a31766c61ab26c7ab86f345676f0d45b60e520d8e24a9c

输出:

{
        "last_submit_time": "2016-06-06 18:46:45",
        "response_code": 1,
        "static": {
            "imphash": "10e0c91a943bd0cc506349eca7326826",
            "File Size": "255872",
            "pe_sections": [
                {
                    "imports": [
                        {
                            "address": "0x4280c8",
                            "name": "GetFileType"
                        }
                    ],
                    [...]
                }
            ]
}

重新扫描

重新扫描已经自己或其他用户提交过的文件

HTTP 方法:post

URL:https://x.threatbook.cn/api/v1/file/rescan

1. 输入参数

输出 类型 说明
response_code Int 用户专属apikey
verbose_msg string response_code相应的Verbose信息
resource string

扫描结束后,发通知(POST)到这个URL,POST的内容如下(为多引擎部分的扫描结果):

  • md5:文件的md5值
  • sha1:文件的sha1值
  • sha256:文件的sha256值
  • scan_id:这次扫描的id,用于后面取扫描报告
  • scan_date:扫描时间
  • scans:所有引擎的扫描结果

2. Python 样例 下载示例

# encoding: UTF-8
#
import httplib, mimetypes
import urllib
import urllib2
import os
import sys
import optparse
import hashlib
import time
# The key for test.
API_KEY = "PUT YOUR APIKEY HERE"
class ThreatBook(object):
    def __init__(self, api_key):
        super(ThreatBook, self).__init__()
        self.api_key = api_key
    def __repr__(self):
        return "<ThreatBook proxy>"
    def rescan(self, hash):
        print "Rescanning ...\r\n"
        #time.sleep(10)
        url = "https://x.threatbook.cn/api/v1/file/rescan"
        parameters = {"resource": hash,
                       "apikey": self.api_key}
        data = urllib.urlencode(parameters)
        req = urllib2.Request(url, data)
        response = urllib2.urlopen(req)
        ret_json = response.read()
        print "response(in JSON):\r\n"
        print ret_json
        return 1;
def main():
    parser = optparse.OptionParser(usage = """
    %prog <hash>
Samples:
    %prog b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db
    """)
    (options, arguments) = parser.parse_args()
    if len(sys.argv) < 2:
        parser.print_usage()
        return -1
    hash = arguments.pop(0)
    
    try:
        v = ThreatBook(API_KEY)
        v.rescan(hash)
    except Exception, e:
        print e
        print "ThreatBook returned a non correct response. See the parameter -l"
if __name__ == "__main__":
    main()  

3. 输出格式

输出 类型 说明
response_code Int 可为以下值:
  • 0: resource对应的hash值在我们的库中没有
  • 1: 成功进入扫描队列
  • -1: 出错,具体看verbose_msg的返回
verbose_msg string response_code相应的Verbose信息
resource string 同输入的resource
scan_id string 用于后面取扫描报告用
permalink string 查看扫描报告的URL
sha256 string 文件的sha256值
sha1 string 文件的sha1值
md5 string 文件的md5值
is_white(optional) boolean 为true表示是白名单文件,如Windows操作系统文件。
white_desc(optional) string 如果是白名单文件,这里是一个关于是哪种白名单文件的描述。

4. 输出样例

Python.exe rescan.py                                                                                 
 b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db   

输入:

{
        "sha1": "6db5cf358d26f6415ddd5aa24ab884f5aac391bc",
        "response_code": 1,
        "sha256": "b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db",
        "resource": "b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db",
        "is_white": false,
        "scan_id": "b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db-1465210386691",
        "permalink": "https:// x.threatbook.cn/report/scan/b76280c2b71b369c8e013651d66d599c615cf83096388c1ad76be6c9725a26db-1465210386691",
        "md5": "85bb66b320ddcdf4cde53593346522f7"
}
域名分析

获取域名对应的IP地址、IP地址相关地理位置信息、当前Whois信息、威胁类型、相关攻击团伙或安全事件信息

HTTP 方法:post

URL:https://x.threatbook.cn/api/v1/domain/query

1. 输入参数

输入 类型 说明
apikey String 用户专属apikey
domain string 要查询的域名
field(optional) string 要查询的字段,以逗号分隔,具体如下,具体含义参照输出格式说明:
  • cur_ips
  • history_ips
  • cur_ips.location(需要先选择cur_ips,将输出cur_ips的位置信息)
  • history_ips.location(需要先选择history_ips,将输出history_ips的位置信息)
  • cur_whois
  • history_whoises
  • tags
  • judgments
  • domains_4_name
  • domains_4_email

2. Python 样例 下载示例

import httplib, mimetypes
import urllib
import urllib2
import os
import sys
import optparse
import hashlib
import time
# The apikey.
API_KEY = "PUT YOUR APIKEY HERE"
class ThreatBook(object):
    def __init__(self, api_key):
        super(ThreatBook, self).__init__()
        self.api_key = api_key
    def __repr__(self):
        return "<ThreatBook proxy>"
    def get(self, domain):
        print "Getting the result ...\r\n"
        url = "https://x.threatbook.cn/api/v1/domain/query"
        parameters = {"domain": domain, "apikey": self.api_key, "field": "cur_ips,cur_ips.location,his_ips,his_ips.location"}
        data = urllib.urlencode(parameters)
        req = urllib2.Request(url, data)
        response = urllib2.urlopen(req)
        ret_json = response.read()
        print "Report(in JSON):\r\n"
        print ret_json
        return 1;
def main():
    parser = optparse.OptionParser(usage = """
    %prog <domain>
Samples:
    %prog manage-163-account.com
    """)
    (options, arguments) = parser.parse_args()
    if len(sys.argv) < 2:
        parser.print_usage()
        return -1
    domain = arguments.pop(0)
    
    try:
        v = ThreatBook(API_KEY)
        v.get(domain)
    except Exception, e:
        print "ThreatBook returned a non correct response. See the parameter -l"
if __name__ == "__main__":
    main()

3. 输出格式

输出 类型 说明
response_code int domains_4_email(optional)
  • array
  • 域名注册邮箱同时注册的其它域名,是一个数组
  • 2: 没有查询到数据
  • -1: 出错,具体看verbose_msg的返回
  • -2: 无效apikey
  • -3: 超过访问限制
verbose_msg string response_code相应的Verbose信息
domain string 同输入的domain
cur_whois(optional) object 这个域名的当前whois信息,是一个JSON对象,字段说明如下 :
  • registrar_name: 域名服务商
  • name_server: 域名服务器(以|分隔)
  • registrant_name: 注册者
  • registrant_email: 注册邮箱
  • registrant_company: 注册机构
  • registrant_address: 地址
  • registrant_phone: 电话
  • cdate: 注册时间
  • udate: 更新时间
  • edate: 过期时间
  • alexa: Alexa排名
history_whoises (optional) array 这个域名的历史whois信息,是一个JSON数组,每一个item是一个JSON对象,字段说明如下:
  • date: 历史whois的时间
  • whois: 是一个JSON对象,字段说明如下 :
  • registrar_name: 域名服务商
  • name_server: 域名服务器(以|分隔)
  • registrant_name: 注册者
  • registrant_email: 注册邮箱
  • registrant_company: 注册机构
  • registrant_address: 地址
  • registrant_phone: 电话
  • udate: 更新时间
  • edate: 过期时间
  • alexa: Alexa排名
cur_ips (optional) array

这个域名的解析的ip信息,是一个JSON数组,每一个item是一个JSON对象,字段说明如下 :

1. ip: ip值

2. location: ip对应的位置信息,json对象,字段说明如下:

  • country: 国家
  • province: 省
  • city: 城市
  • lng: 经度
  • lat: 纬度
history_ips (optional) array

这个域名的历史上解析的ip信息,是一个JSON数组,每一个item是一个JSON对象,字段说明如下:

date: 历史ip的时间

ip: 是一个JSON对象,字段说明如下 :

1. ip: ip值

2. domains: 数组,指向这个ip的其它域名

3. location: ip对应的位置信息,json对象,字段说明如下:

  • country: 国家
  • province: 省
  • city: 城市
  • lng: 经度
  • lat: 纬度
tags(optional) array 相关攻击团伙或安全事件信息,json数组,例如:DarkHotel
judgments(optional) array 从威胁情报分析出来的威胁类型,如 远控,恶意软件等,是一个json数组
intelligences(optional) array 威胁情报,是一个json数组,每个item的字段定义如下:
  • source: 来源
  • find_time: 发现时间
  • confidence: 信心指数
  • intel_types: 类型,是一个数组
samples(optional) array 相关样本,是一个json数组,每个item的字段定义如下:
  • sha256: 文件hash
  • scan_time: 检测时间
  • ratio: 检出率
  • malware_type: 恶意类型(optional)
  • malware_family: 恶意家庭(optional)
domains_4_name(optional) array 域名注册人同时注册的其它域名,是一个数组
domains_4_email(optional) array 域名注册邮箱同时注册的其它域名,是一个数组

4. 输出样例

输入:

Python.exe domainQuery.py netforuser.com

输出:

Getting the result ...
Report(in json)
{"response_code":0,"judgments":["远控"],"domain":"netforuser.com"}
IP分析

获取IP地址相关地理位置信息、绑定的域名信息、威胁类型、相关攻击团伙或安全事件信息

HTTP 方法:post

URL:https://x.threatbook.cn/api/v1/ip/query

1. 输入参数

输入 类型 说明
apikey string 用户专属apikey
ip string 要查询的IP
field(optional) string 要查询的字段,以逗号分隔,如asn,tags。可用参数如下,具体含义参照输出格式说明:
  • asn
  • tags
  • judgments
  • cur_domains

2. Python 样例 下载示例

import httplib, mimetypes
import urllib
import urllib2
import os
import sys
import optparse
import hashlib
import time
# The apikey
API_KEY = "PUT YOUR APIKEY HERE"
class ThreatBook(object):
    def __init__(self, api_key):
        super(ThreatBook, self).__init__()
        self.api_key = api_key
    def __repr__(self):
        return ""
    def get(self, ip):
        print "Getting the result ...\r\n"
        url = "https://x.threatbook.cn/api/v1/ip/query"
        parameters = {"ip": ip, "apikey": self.api_key, "field": "domains"}
        data = urllib.urlencode(parameters)
        req = urllib2.Request(url, data)
        response = urllib2.urlopen(req)
        ret_json = response.read()
        print "Report(in JSON):\r\n"
        print ret_json
        return 1;
def main():
    parser = optparse.OptionParser(usage = """
    %prog 
Samples:
    %prog 82.165.37.26
    """)
    (options, arguments) = parser.parse_args()
    if len(sys.argv) < 2:
        parser.print_usage()
        return -1
    ip = arguments.pop(0)
    
    try:
        v = ThreatBook(API_KEY)
        v.get(ip)
    except Exception, e:
        print "ThreatBook returned a non correct response."
if __name__ == "__main__":
    main()

3. 输出格式

输出 类型 说明
response_code int 可为以下值:
  • 0: 成功
  • 1: 输入的IP格式不正确
  • 2: 没有查询到数据
  • -1: 出错,具体看verbose_msg的返回
  • -2: 无效apikey
  • -3: 超过访问限制
verbose_msg string response_code相应的Verbose信息
asn(optional) object ASN信息,是一个json object, 字段说明如下 :
  • number: ASN号
  • rank: 风险值(0~4,越大代表风险越高)
  • info: 机构名
ip array

ip: 是一个JSON对象,字段说明如下 :

1. ip: ip值

2. domains: 数组,指向这个ip的其它域名(由field输入参数控制)

3. location: ip对应的位置信息,json对象,字段说明如下:

  • country: 国家
  • province: 省
  • city: 城市
  • lng: 经度
  • lat: 纬度
tags(optional) array 相关攻击团伙或安全事件信息,json数组,例如:DarkHotel
judgments(optional) array 从威胁情报分析出来的威胁类型,如远控、僵尸网络、恶意软件、失陷主机、代理等,是一个json数组
intelligences(optional) array 威胁情报,是一个json数组,每个item的字段定义如下:
  • source: 来源
  • find_time: 发现时间
  • confidence: 信心指数
  • intel_types: 类型,是一个数组
samples(optional) array 相关样本,是一个json数组,每个item的字段定义如下:
  • sha256: 文件hash
  • scan_time: 检测时间
  • ratio: 检出率
  • malware_type: 恶意类型(optional)
  • malware_family: 恶意家庭(optional)

4. 输出样例

输入:

Python.exe ipQuery.py 82.165.37.26

输出:

Getting the result ...
Report(in json)
{"response_code":0,"judgments":["僵尸网络"],"ip":"82.165.37.26","location":{"country":"德国","province":"德国","lng":"10.454150","city":"","lat":"51.164181"}}