微步在线云API
我的API

资产测绘查询

资产测绘查询 API 支持通过统一的资产测绘查询语句检索互联网资产，返回 IP、端口、协议、域名、网页标题、HTTP 状态码、应用组件、Banner、证书及相关指纹 Hash 等信息。

该接口适用于外部攻击面发现、互联网资产梳理、告警上下文补全和威胁基础设施拓线等场景。

请求方法
请求地址： https://api.threatbook.cn/v3/internet_assets/query

请求方式：GETPOST

使用说明
  • GET 请求通过 URL parameters 传递 apikey 和 syntax。
  • POST 请求使用 application/json，syntax 放入 JSON 请求体；apikey 可放入 JSON 请求体或 URL parameters。
  • 查询语句未声明 before 或 after 时，默认查询最近 3 个月的数据；声明任一时间条件时，以用户指定的时间范围为准。
  • 结果按最近扫描时间倒序排列，单次最多返回最近的 100 条，total_count 表示全部命中数量。
  • syntax 的字段、运算符和组合规则请前往“查看详细语法说明”。
查询语法范围限制

为避免端口、地域、状态码、时间等低选择性条件产生大范围扫描，每个能够独立扩大结果范围的查询分支都必须包含至少一个使用 = 或 == 的正向锚点字段。使用 != 的排除条件不能作为锚点。

场景正向锚点字段
IP、域名ip、ipv6、domain、root_domain、dns
应用指纹app、apply、app_category、server、protocol、service
Header、Banner、TLS、SSHheader、banner、jarm、ja3s、ja4s、ja4x、ssh_finger_md5、ssh_finger_sha256、plugins、plugins.values
证书cert.hash、cert.value、cert.subject.org、cert.issuer.org
ASN、组织、备案asn、asn_org、asn_name、icp、icp_name、icp_company、whois_company、whois_email
内容与 Hashbody、title、psr、icon_hash、ssdeep_hash、html_hash、body_hash、dom_hash、js_hash、header_hash、banner_hash、sitemap_hash、robots_hash
漏洞vul_id

port、地域字段、status_code、after、before、exists、icp_type、owner 以及其他未列入上表的字段只能用于限定查询范围，不能单独查询。

  • A && B：任意一侧存在正向锚点即可，另一侧仅用于缩小查询范围。
  • A || B：每个能够独立成立的 OR 分支都必须包含正向锚点；若外层通过 AND 提供公共锚点，该锚点同时约束 OR 两侧。
  • 括号表达式按完整组合关系递归判断。

例如，ip="1.1.1.1" && country="中国"、ip="1.1.1.1" || domain="example.com" 可以查询；port="80"、icp_type="企业"、root_domain!="example.com"、ip="1.1.1.1" || port="80" 会被拦截。

请求参数说明
序号参数名称必选类型描述
1apikey是stringAPI 请求的唯一标识。GET 通过 URL parameters 传递；POST 可放入 JSON 请求体或 URL parameters。
2syntax是string资产测绘查询语句。GET 通过 URL parameters 传递并进行 URL Encode；POST 放入 JSON 请求体。可前往 “查看详细语法说明”。
3page否int查询页码，从 1 开始，默认值为 1。
4size否int单页返回数据条数。当 include 不包含 header 和 banner 时支持 1~100（默认 100 条）；当 include 包含 header 或 banner 时支持 1~50（默认 50 条）。
5include否string / array返回字段选择列表。GET 请求通过 URL parameters 传递逗号分隔字符串（如 include=domain,header,banner）；POST 请求在 JSON 请求体中传递字符串数组（如 ["domain", "header", "banner"]）。支持的值包括：domain、header、banner、cert、application、component、page_info、hash。如果不传则对应字段不返回。
响应参数说明
序号参数路径类型描述
1response_codeint响应状态码。成功为 0，无结果为 2，其他状态参见响应状态码说明。
2verbose_msgstring响应状态说明。成功为 OK，无结果为 No Data。
3dataobject | nullMCP 资产测绘业务返回结构；请求失败时可为 null。
4data.total_countint全部命中的测绘结果数量。
5data.pageint当前返回的页码（从 1 开始）。
6data.sizeint当前分页大小（单页返回的最大记录数）。
7data.messagestring查询结果数量、分页情况或无结果说明。
8data.dataarray当前页测绘查询结果，按最近扫描时间倒序排列。
9data.data[].idstring测绘数据唯一标识 ID，可用于检索单条数据详情。
10data.data[].ipobjectIP 地址及相关情报。
11data.data[].ip.ipstringIP 值。
12data.data[].ip.verdictstringIP 地址相关情报判定。
13data.data[].ip.locationobjectIP 地理位置。
14data.data[].ip.location.countrystring国家。
15data.data[].ip.location.regionstring省或区域。
16data.data[].ip.location.citystring城市。
17data.data[].ip.ispstringISP 运营商。
18data.data[].ip.asnobjectIP 相关 ASN 信息。
19data.data[].ip.asn.numberstringASN 号码。
20data.data[].ip.asn.namestringAS 名称或归属网络运营商。
21data.data[].ip.asn.organisationstringAS 注册机构。
22data.data[].portstring开放端口。
23data.data[].protocolstring协议名称。
24data.data[].protocol_typestring协议类型，例如 tcp 或 udp。
25data.data[].tunnelstring传输隧道类型，例如 ssl。
26data.data[].domainobject域名及相关情报。
27data.data[].domain.domainstring域名值。
28data.data[].domain.verdictstring域名相关情报判定。
29data.data[].domain.icpobjectICP备案信息。
30data.data[].domain.icp.ownerstring域名归属。
31data.data[].domain.icp.company_namestring备案单位。
32data.data[].domain.icp.company_typestring备案单位性质。
33data.data[].domain.icp.site_licensestring备案编号。
34data.data[].domain.icp.site_namestring网站名称。
35data.data[].domain.icp.main_pagestring网站主页。
36data.data[].domain.icp.verify_timestring备案审核时间。
37data.data[].web_titlestring网页标题；命中敏感内容时返回空字符串。
38data.data[].status_codestringHTTP 响应状态码。
39data.data[].headerstringHTTP 响应头完整文本；命中敏感内容时返回空字符串。
40data.data[].hoststring主机名。
41data.data[].applicationstring应用。
42data.data[].componentstring[]组件列表。
43data.data[].page_infoobject[]页面内嵌技术栈与组件精细识别信息列表。
44data.data[].page_info[].categorystring[]页面技术栈分类。
45data.data[].page_info[].namestring识别到的技术栈或组件名称。
46data.data[].bannerstring协议 Banner；命中敏感内容时返回空字符串。
47data.data[].certobject证书信息。
48data.data[].cert.user_namestring证书使用者。
49data.data[].cert.user_organizationstring证书使用者单位名称。
50data.data[].cert.user_locationstring证书使用者国家或地区。
51data.data[].cert.issuer_namestring证书颁发者名称。
52data.data[].cert.issuer_organizationstring证书颁发者单位名称。
53data.data[].cert.issuer_locationstring证书颁发者国家或地区。
54data.data[].cert.fingerprintstring证书指纹。
55data.data[].cert.purposestring证书用途。
56data.data[].cert.statusstring证书状态，例如正常或过期。
57data.data[].cert.beginstring证书开始时间。
58data.data[].cert.endstring证书失效时间。
59data.data[].cert.serial_numberstring证书序列号。
60data.data[].cert["cert.is_trust"]bool证书是否可信。true 代表可信，false 代表不可信。
61data.data[].hashobject网站、Banner、SSH 和 TLS 等指纹 Hash。
62data.data[].hash.html_hashstring网站完整源码 Hash。
63data.data[].hash.body_hashstring网页 Body 源码 Hash。
64data.data[].hash.dom_hashstring网页 DOM 树 Hash。
65data.data[].hash.html_header_hashstring网页 Head 源码 Hash。
66data.data[].hash.sitemap_hashstring网站 Sitemap Hash。
67data.data[].hash.robots_hashstring网站 Robots Hash。
68data.data[].hash.icon_hashstring网站图标 Hash。
69data.data[].hash["icon-mm3h-hash"]string网站图标 mm3h Hash。
70data.data[].hash.icon_dhashstring网站 Favicon 图标相似性 dHash。
71data.data[].hash.header_hashstringHTTP 响应头 Hash。
72data.data[].hash.ssdeep_hashstring网页源码 Ssdeep Hash。
73data.data[].hash.banner_hashstringBanner 指纹。
74data.data[].hash.ssh_finger_md5stringSSH MD5 指纹。
75data.data[].hash.ssh_finger_sha256stringSSH SHA256 指纹。
76data.data[].hash.jarmstringJARM 指纹。
77data.data[].hash.ja3sstringJA3S 指纹。
78data.data[].hash.ja4xstringJA4X 指纹。
79data.data[].hash.ja4sstringJA4S 指纹。
80data.data[].last_scan_timetimestamp最近扫描时间。
81data.permalinkstringX 资产测绘对应查询结果页链接。
GET 请求示例

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

Python
import requests

url = "https://api.threatbook.cn/v3/internet_assets/query"
params = {
    "apikey": "请替换apikey",
    "syntax": 'ip="47.99.241.172"'
}

response = requests.get(url, params=params)
print(response.json())
POST 请求示例

以下示例将 apikey 和 syntax 一并放入 JSON 请求体：

Python
import requests

url = "https://api.threatbook.cn/v3/internet_assets/query"
payload = {
    "apikey": "请替换apikey",
    "syntax": 'ip="47.99.241.172"'
}

response = requests.post(url, json=payload)
print(response.json())

POST 请求也可以通过 URL parameters 传递 apikey，JSON 请求体仅保留 syntax：

curl --request POST \
  'https://api.threatbook.cn/v3/internet_assets/query?apikey=请替换apikey' \
  --header 'Content-Type: application/json' \
  --data '{"syntax":"ip=\"47.99.241.172\""}'

若 JSON 请求体和 URL parameters 同时传入 apikey，两处值必须一致。

响应规则
  • 支持通过 page 和 size 分页查询：
    • 当 include 不包含 header 和 banner 时，单页最大支持返回 100 条数据（size 默认 100）。
    • 当 include 包含 header 或 banner 任意大文本字段时，单页最大支持返回 50 条数据（size 默认 50）；若传入 size > 50 系统自动限制为 50 条。
  • 支持通过 include 参数按需选择返回字段（支持 domain、header、banner、cert、application、component、page_info、hash）；若不传则对应字段不返回，仅返回基础固定字段。
  • 无结果时返回 response_code=2、verbose_msg="No Data"，业务结果数组为空；未指定时间条件时提示“近3个月内未查询到相关结果”，已指定时间条件时提示“指定时间范围内未查询到相关结果”。
  • 仅 web_title、banner、header 执行敏感过滤；命中敏感内容时对应字段返回空字符串。
  • app_category 命中不支持的组件类型时，返回 response_code=-1、data=null，并提示“当前组件类型不支持查询”。
  • 查询语句的任一独立分支缺少正向锚点时，返回 response_code=-1、verbose_msg="查询条件过于宽泛"、data=null；该请求不发起资产查询，也不消耗调用额度。语法结构错误仍按无效参数处理。
响应示例（JSON）
{
  "response_code": 0,
  "verbose_msg": "OK",
  "data": {
    "total_count": 851,
    "page": 1,
    "size": 100,
    "message": "查询到851个相关测绘结果，当前返回第1页共100个测绘结果",
    "data": [
      {
        "id": "d0f8a9e1c2b34a5e6f7d8c9b0a1e2f3a",
        "ip": {
          "ip": "47.99.241.172",
          "verdict": "未知",
          "location": {
            "country": "中国",
            "region": "浙江省",
            "city": "杭州市"
          },
          "isp": "阿里云",
          "asn": {
            "number": "37963",
            "name": "ALIBABA-CN-NET",
            "organisation": "Hangzhou Alibaba Advertising Co.,Ltd."
          }
        },
        "port": "8000",
        "protocol": "HTTP",
        "protocol_type": "tcp",
        "tunnel": "ssl",
        "domain": {},
        "web_title": "金蝶云星空 管理中心",
        "status_code": "200",
        "header": "Server: cPanel\nHost: 47.99.241.172:8000\nContent-Type: text/html; charset=\"utf-8\"\nVary: Accept-Encoding\nWww-Authenticate: Basic realm=\"Restricted Area\"\nExpires: Fri, 01 Jan 1990 00:00:00 GMT\nDate: Thu, 10 Feb 2022 12:15:21 GMT\nPersistent-Auth: false\nCache-Control: no-cache, no-store, must-revalidate, private\n",
        "host": "",
        "application": "Microsoft IIS httpd",
        "component": [
          "Microsoft-ASP.NET",
          "金蝶云星空"
        ],
        "page_info": [
          {
            "category": [
              "Other Network Security"
            ],
            "name": "Baidu站长平台"
          },
          {
            "category": [
              "Security"
            ],
            "name": "HSTS"
          }
        ],
        "banner": "HTTP/1.1 200 OK",
        "cert": {
          "user_name": "example.com",
          "issuer_name": "Example CA",
          "fingerprint": "88d4a0f7c1c5cb460181ab8b26db016e14af37d8",
          "status": "正常",
          "cert.is_trust": true
        },
        "hash": {
          "body_hash": "b87ddb81fe6f3392ccaf5104f21f3f5f",
          "dom_hash": "cde3d2ae4849354d68dd2f891135fdef",
          "icon_hash": "825af13371930eeb2f85cf075fa25b68",
          "icon-mm3h-hash": "-1629133697",
          "icon_dhash": "17331559359943652072"
        },
        "last_scan_time": 1742500000
      }
    ],
    "permalink": "https://x.threatbook.com/v5/survey?q=ip%3D%2247.99.241.172%22"
  }
}
云API是北京微步在线科技有限公司旗下产品了解微步在线《用户服务条款》《数据保护政策》联系我们：api@threatbook.cn
Copyright © ThreatBook.CN All Rights Reserved. 京ICP备15044984号-4 北京微步在线科技有限公司 京公网安备11010802025715号