微步在线云API
我的API

IP 信誉

针对入站场景的IP进行分析， 能够提供IP的地理位置、ASN信息，通过判定规则精准判别IP是否恶意、风险严重级别、可信度级别；识别威胁类型，如：漏洞利用（exploit）、傀儡机（Zombie）等及相关安全事件或团伙标签。

提示：为什么IP信誉和IP分析/X页面的判定结果不一致？

  • IP信誉接口是面向入站IP风险的精准识别，会结合历史过期情报参与判定，同时只会检出入站相关的风险如扫描、漏洞利用等。远控、恶意软件等失陷情报不会检出，数据接入要求为入站访问相关IP。应用场景是实现自动化的告警降噪和威胁检测场景，侧重情报检出的覆盖。
  • X的web页面查询与IP分析接口是全维度威胁情报标签检出，没有接入数据访问方向的要求（不区分出、入站），侧重当前有效情报和线索的研判、分析追踪，并提供原始情报信息。使用场景偏人工分析，进行告警研判和威胁分析。
调用脚本
调用脚本下载Run In Postman
请求方法
请求地址： https://api.threatbook.cn/v3/scene/ip_reputation

请求方式：POSTGET

使用说明

适用场景： 该接口适用于入站访问源 IP 的风险识别，可用于告警筛选降噪、入站攻击精细化封禁、反爬虫等自动化检测与处置场景。相关场景示例可参考：告警筛选降噪、入站攻击精细化封禁、反爬虫。

使用建议： 建议在接入前确认待查询 IP 来自入站访问日志、WAF/IPS/防火墙告警、业务访问日志等入站侧数据。该接口侧重入站风险判定，适合用于自动化告警降噪、风险分级和策略辅助；如需进行不区分出入站方向的完整情报研判，可结合 IP 分析接口使用。

响应字段解读建议： 建议优先综合参考 is_malicious、confidence_level、severity 和 judgments 判断是否存在明确风险及处置优先级；再结合 tags_classes、asn、scene、feature、entity、hist_behavior、evaluation 等字段补充理解风险来源、基础设施属性和历史行为。自动化处置时不建议仅依据单一字段直接封禁，应结合客户业务日志、资产重要性和误报容忍度设置策略阈值。

请求参数说明
序号参数名称必选类型描述
1apikey是stringAPI请求的身份识别标识。
2resource是string要查询的IP地址。支持IPv4、IPv6查询。可同时查询100个，以逗号分隔。
3lang可选string返回结果语言。不输入该参数时，默认返回英文。
取值二者选其一：
  • zh：所有返回结果内容中文显示。
  • en：所有返回结果内容英文显示。
4realtime_verdict可选boolean支持控制是否将历史过期情报纳入最终判定；不输入该参数时，默认包含历史过期情报。
  • true代表只返回当前有效情报
  • false代表返回包含历史过期情报。
响应参数说明
序号参数名称类型描述使用说明
1response_codeint响应正常会返回"0"。其他Response code及对应msg描述参见"响应Code和Msg对照表"用于判断本次请求是否成功。业务系统应先判断该字段，再解析 data 内的业务结果；非 0 时建议按异常请求处理。
2verbose_msgstring响应正常会返回"Ok"。其他Response code及对应msg描述参见"响应Code和Msg对照表"用于展示或记录接口返回说明，适合写入调用日志和错误排查信息；自动化流程建议以 response_code 为主要判断依据。
3ipsmap查询的IP信誉情况，是一个JSON Map，key是ip，value是一个JSON对象，字段说明见下"4~10"项所述。批量查询时按 IP 读取对应结果，建议结合单个 IP 下的恶意判定、可信度、严重级别和威胁类型综合判断。
4basicobjectbasic返回是一个JSON对象，字段说明如下：
  • carrier: 运营商/服务商
  • location: ip对应的位置信息，JSON对象，说明如下：
    • country: 国家
    • country_code: 国家代码
    • province: 省
    • city: 城市
    • lng: 经度
    • lat: 纬度
用于补充 IP 的运营商和地理位置背景，适合告警富化和误报排查，不建议单独作为风险判断依据。
5is_maliciousboolean是否为恶意IP。布尔类型，true代表恶意，false代表非恶意。入站风险识别的核心结论字段。为 true 时建议结合可信度、严重级别和业务日志决定告警升级、拦截或人工复核。
6confidence_levelstring可信度。通过情报来源及可信度模型判别出来的恶意可信度程度，分"low（低）"，"medium（中）"，"high（高）" 三档来标识。用于衡量恶意结论的可靠程度。自动化处置建议优先采用 high，medium/low 更适合作为复核或观察线索。
7severitystring严重级别。 表示该情报的危害程度，分为"critical（严重）"，"high（高）"，"medium（中）"，"low（低）"，"info（无危胁）"5种程度类型。用于判断处置优先级。critical/high 可优先进入高等级告警或封禁策略，medium/low 建议结合资产和业务影响评估。
8judgmentsarray从威胁情报中分析，提取出来的综合判定威胁类型，JSON数组。
  1. 该接口中判定为恶意的类型含：
    • Spam：垃圾邮件
    • Zombie：傀儡机
    • Scanner：扫描
    • Exploit：漏洞利用
    • Botnet：僵尸网络
    • Brute Force：暴力破解
      Brute Force子类相关，参见：" 威胁类型全集"中描述。
  2. 该接口中判定为非恶意的类型含：
    • Whitelist：白名单。
    • Info：基础信息。
用于理解风险类型，如扫描、漏洞利用、暴力破解等，可映射到不同的告警分类和防护动作。
9tags_classesarray相关攻击团伙或安全事件信息，JSON数组，每个item包含字段说明如下：
  • tags_type：标签类别，如"industry(行业)"、"gangs（团伙）"、"virus_family（家族）"等。
  • tags：具体的攻击团伙或安全事件标签，例如：Mirai等。
用于补充攻击团伙、安全事件或家族标签，适合人工研判、事件关联和报告呈现。
10asnobjectasn信息。一个JSON对象，包含：
  • number: ASN号码
  • info: AS名称
  • rank: 风险值（0~4，越大代表风险越高）
用于识别 IP 所属网络和基础设施背景，rank 可作为网络环境风险的辅助参考。
11update_timestring情报的最近更新时间。用于判断情报新鲜度。较新的情报更适合支撑当前处置，较旧情报建议结合实时日志复核。
12scenestring应用场景。如：企业专线，数据中心等。全集请见："应用场景分类"。用于理解 IP 的常见应用场景，如企业专线、数据中心等，适合辅助解释访问来源和策略分层。
13featurearray资产特征。"定制版套餐"专享。一个JSON数组，包含：用于补充资产特征，适合做精细化策略、画像展示和风险解释。
14entityarray归属实体。"定制版套餐"专享。一个JSON数组，包含：用于识别 IP 归属实体，适合做归属判断、白名单校验和事件报告补充。
15hist_behaviorarray攻击行为。"定制版套餐"专享。一个JSON数组，包含：
  • category：分类。具体分类说明参见"IP信誉 · 高级字段分类说明"
  • tag_name：具体的攻击行为标签
  • tag_desc：标签对应的描述
  • vuln_id：当分类为"漏洞利用"时，有具体的漏洞编号信息
用于了解该 IP 的历史攻击行为，为风险研判和取证提供补充信息，不建议仅凭该字段对当前访问进行拦截或处置。
16evaluationobject影响评估。"定制版套餐"专享。一个JSON对象，包含：
  • active：活跃度。包含high（高）、medium（中）、low（低）
  • honeypot_hit：布尔值。蜜罐是否捕获过，true代表被蜜罐捕获过、false代表未被蜜罐捕获过
用于判断活跃度和蜜罐命中情况，适合支撑告警置信度和处置优先级。
17fraudarray欺诈作弊行为。"定制版套餐"专享。一个JSON数组，包含：
  • tag_name：具体的欺诈作弊行为标签
  • tag_desc：标签对应的描述
适合反爬、反欺诈、风控等场景识别作弊行为，可作为业务风控策略的辅助字段。
18permalinkstringIP对应的情报查询结果页链接用于跳转到 X 情报中心的情报详情页，适合人工复核、报告留存和协同分析，不建议作为自动化风险判断依据。
请求示例

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

Python
import requests

url = "https://api.threatbook.cn/v3/scene/ip_reputation"

query = {
  "apikey":"请替换apikey",
  "resource":"159.203.93.255"
}

response = requests.request("GET", url, params=query)

print(response.json())
响应示例（JSON）
{
    "data":{
        "121.207.85.140": {
            "basic": {
                "carrier": "China Telecom",
                "location": {
                    "country": "China",
                    "country_code": "CN",
                    "province": "Fujian",
                    "lng": "118.55754",
                    "city": "Quanzhou City",
                    "lat": "24.902359"
                }
            },
            "asn": {
                "number": 4134,
                "rank": 4,
                "info": "CHINANET-BACKBONE"
            },
            "confidence_level": "high",
            "is_malicious": true,
            "severity": "medium",
            "judgments": [
                "Dynamic IP",
                "Zombie",
                "Spam",
                "IoT Device"
            ],
            "update_time": "2024-10-17 14:29:48",
            "scene": "Residence",
            "tags_classes": [],
            "entity":[],
            "evaluation":{
                "active":"low",
                "honeypot_hit":true
            },
            "feature":[],
            "hist_behavior":[{
                "category":"扫描",
                "tag_desc":"端口扫描是一种确定网络上哪些端口处于打开状态并且可以接收或发送数据的方法。它还是将数据包发送到主机上的特定端口并分析响应以识别漏洞的过程。",
                "tag_name":"端口扫描",
                "vuln_id":[]
                }
            ],
            "permalink":"https://x.threatbook.com/v5/ip/121.207.85.140"
        }
    },
    "response_code": 0,
    "verbose_msg": "Ok",
}
云API是北京微步在线科技有限公司旗下产品了解微步在线《用户服务条款》《数据保护政策》联系我们：api@threatbook.cn
Copyright © ThreatBook.CN All Rights Reserved. 京ICP备15044984号-4 北京微步在线科技有限公司 京公网安备11010802025715号