SaaS版本API

一. 产品介绍

威胁猎人IP画像是一款针对业务安全场景的IP产品，整体为业务安全场景设计，精准识别网络黑产在薅羊毛、网络爬虫、恶意引流等业务场景中使用的各类恶意IP资源，帮助厂商从IP维度识别对抗。

• 高解释性：风险判定逻辑为某IP在某时间是否被网络黑产持有，或某IP在某时间是否由明确的恶意工具发起明确恶意行为。判定逻辑具有高解释性。
• 高时效性：由于IP资源的特殊性，多数IP（正常用户流量，非机房）在不同时间会被多个不同用户使用。IP被网络黑产持有的逻辑也是相同的，产品采用秒级更新，保证风险判定的时效性问题。
• 方便可用的风险量化标准：产品提供该IP命中的各类风险标签，同时也提供一个直接的风险分值来量化风险。

二. 使用说明

2.1 RESTful API交付方式

IP画像部署在云端，通过HTTPS的RESTful接口查询使用。每个注册客户会分配一个snuser和snkey（配置管理 (opens new window)页面可以查看）。

IP画像服务端对查询请求实行IP白名单机制，（客户可以在个人中心的“配置管理 (opens new window)”页面管理自己的IP地址白名单，）只有白名单中IP地址允许查询。如果出口IP是IP段，添加IP超过五分钟未生效，可向运维询问企业出口IP段，并添加至IP段至白名单。

（注：需要先申请获取产品使用权限后，才能成功添加IP）

2.2 查询接口

请求说明

请求详情	说明
请求地址	https://ipdata.yazx.com/api/ip/v2/check/
请求方法	POST
并发	100
默认QPS	1000 (实时查询)
延时情况	200ms以内

POST参数示例

{
     'snuser': 'test',
     'data': 'RG/yb3B0sxFbJyvGCHnHVutkcZ3l2MhShhMKu3hvxH1Kwc/7CJgy0uXr
                 SZ2+SPz5X/iPRNZwznsorzZ2pJu/bxjMObTpOik3DiN2M3TQNspSZjon1M
                 /0UlJpoxiqb+2kvhQmsaoqK3Qkry6U0NMs9GlHXKIP4aj1igG3oXQezgRJh
                 KAGQ7ELvLCjQk47ha4oUHCJaYuHye44lN11XkDFax1fJljMsGWEPbP1AcZP
                 pxZH/A=='
}

请求参数说明

请求参数	类型	说明
snuser	String	用户ID
data	String	由AES的CFB加密的json数据，密钥是SNKEY

data明文请求示例

{"ip": "122.241.179.74", "attack_time": 1706062488}

data内容字段说明

参数名称	类型类型	是否必传	说明
ip	String	是	所查询的IP
attack_time	Int	否	时间戳，精确到秒，不传则默认为当前时间。目前仅支持查询一个月内IP的风险分数。

返回示例

{
     'status': 200,
     'errmsg': 'OK',
     'data': 'MDEyMzQ1Njc4OWFiY2RlZhn/Cky2Sca6Gk
           +yvC5l4HwqYTpwGHn9ZW+or7oqlh+B1iZlDBBAdB3qNdcj3GEkCuNBB6/
           N5NgF7LZfYyML221NQpLTPsvgU7AmSW39KfjecivUUk1lEWUC8eTmpc24GKw6
           VfBZUuFyzqOqK5spwyz6NcfaISI3yv992rDkrSojFfZXK/1hLMJ3NAb4FU7hc
           TTBeTDXQdiqR3nELZcNhChBED3DC02nNISecNHjXxAkdnzWPyzS7smr1H9F9r
           h3PnyYu/GA5boclROza8OYrltryWiWcO6+dskqHFuPyaHhUaOH2kcgSqDAxyt
           OJMQacDc2Zh5dM0G0I7AFAZv/5OBsKFrNnVM3GD4cZzpLbyQiwVWPal+7pHgk
           74RyCT+3oahWsvq8QFrOKGhbp59GRUbHJbYAFcvFRMCKsdXh/M76DHHZp6T5+
           BlFAWGplTC0WHtMgesrD+NIvKFparIHQSeBW8N+WlcSqnD+wgBqRrJXIL9Ex92
           rDkHa+JFl2d/TfzYO7owXkUlA2Tazt3ntCbaiNGc9N+TybnsW4CSjpwKdOmCej
           IQUZ29/umlnXjJWcuhNTRYtQ9sE9XEyGICCNrLegx9'
}

返回明文示例

{
    "ip":"122.241.179.74",
    "exist":true,
    "type":"家庭宽带",
    "location":{
        "country":"中国",
        "province":"浙江省",
        "city":"丽水市",
        "district":"龙泉市",
        "owner":"中国电信",
        "latitude":28.0478,
        "longitude":119.071,
        "ad_code":"331181",
        "continent":"亚洲"
    },
    "score_tag":{
        "name":"代理",
        "time":"2024-01-23T23:43:27+08:00"
    },
    "risk_score":94,
    "risk_level":"高",
    "tags": [
        {
            "name": "代理",
            "time": "2024-01-23T23:43:27+08:00"
        },
        {
            "name": "秒拨",
            "time": "2024-01-08T16:01:02+08:00"
        }
    ]
}

返回内容字段说明：

字段	类型	说明	描述
ip	String	IP	所查询的IP
exist	Bool	是否在风险库中	true表示在历史风险库中，false表示不在库中
type	String	IP类型	IP类型包含以下6个类型： 家庭宽带：此类IP被普通的住宅用户使用，通常覆盖多个小区 数据中心：此类IP被IDC公司或运营商在数据中心使用 移动网络：此类IP被3G/4G等手机移动网络的网络出口IP 企业专线：此类IP一般被企业使用，覆盖范围为企业所处区域 校园单位：此类IP被学校单位使用 未知：未识别的ip类型
location	Object	详细地理信息	country 国家 province 省份 city 城市 district 区 owner 运营商(IP所属AS的注册机构) latitude 纬度 longitude 经度 ad_code 行政区划代码 continent 大洲
score_tag	Object	风险标签及时间	用于计算分数的风险标签
score_tag.name	String	风险标签	风险标签包含以下8个类型： 代理：该IP在该时间点被网络黑产作为代理IP使用。 秒拨：该IP在该时间点是网络黑产提供的秒拨IP资源（秒拨IP指，黑产利用家庭宽带拨号在一定时间内持有作恶的IP）。 开源情报：从开源渠道收集记录的被公开风险信息的IP。 劫持共用代理：指的是代理平台传播各种带有后门木马的软件，正常用户下载使用了这类包含木马的软件后，自己的IP就会被软件暗中劫持，变为代理平台可利用的代理IP资源，这类型的IP为好人坏人同时在进行使用。 搜索引擎爬虫：指的是各大搜索引擎网站对网站进行蜘蛛爬取时所使用的IP。 VPN：指的是VPN软件使用的静态代理IP资源，和秒拨代理的区别在于VPN使用的静态代理IP多为机房IP，且变化不频繁，数量少，而秒拨代理使用的多为家庭宽带类型IP，变化频繁、数量多。 云服务：指的是各大云服务器厂商提供的云函数SCF出口IP，有部分黑产会在云厂商提供的云函数中搭建恶意脚本执行攻击，但也有很多程序员在正常使用云函数服务，这类型的IP为好人坏人同时在进行使用。 云手机：指的是国内主流云手机服务平台提供的云手机服务中的IP，攻击者可能利用云手机的群控配置执行批量攻击，借此掩盖其真实源IP。 注：无风险标签时返回空字符串。
score_tag.time	String	作恶时间	作恶时间，格式为RFC3339 注：无风险标签时返回"0001-01-01T00:00:00Z"。
risk_score	integer	风险分数	范围0-99，得分越高被黑产持有的概率也就越高
risk_level	String	风险等级	高、中、低、无
tags	List	近期所有风险标签及时间	该IP的风险标签列表
tags.name	String	风险标签	风险标签包含以下8个类型： 代理：该IP在该时间点被网络黑产作为代理IP使用。 秒拨：该IP在该时间点是网络黑产提供的秒拨IP资源（秒拨IP指，黑产利用家庭宽带拨号在一定时间内持有作恶的IP）。 开源情报：从开源渠道收集记录的被公开风险信息的IP。 劫持共用代理：指的是代理平台传播各种带有后门木马的软件，正常用户下载使用了这类包含木马的软件后，自己的IP就会被软件暗中劫持，变为代理平台可利用的代理IP资源，这类型的IP为好人坏人同时在进行使用。 搜索引擎爬虫：指的是各大搜索引擎网站对网站进行蜘蛛爬取时所使用的IP。 VPN：指的是VPN软件使用的静态代理IP资源，和秒拨代理的区别在于VPN使用的静态代理IP多为机房IP，且变化不频繁，数量少，而秒拨代理使用的多为家庭宽带类型IP，变化频繁、数量多。 云服务：指的是各大云服务器厂商提供的云函数SCF出口IP，有部分黑产会在云厂商提供的云函数中搭建恶意脚本执行攻击，但也有很多程序员在正常使用云函数服务，这类型的IP为好人坏人同时在进行使用。 云手机：指的是国内主流云手机服务平台提供的云手机服务中的IP，攻击者可能利用云手机的群控配置执行批量攻击，借此掩盖其真实源IP。 注：无风险标签时返回空字符串。
tags.time	String	作恶时间	作恶时间，格式为RFC3339 注：无风险标签时返回"0001-01-01T00:00:00Z"。

三. 使用建议

针对产品对IP给出的风险分数，用户可以根据以下说明进行处置：

风险分数	风险等级	说明	处置建议
(100,90]	高	该IP当前被黑产持有	根据业务需求进行拦截或标记、触发严格验证等，推荐较高强度的风控处理手段。
(90,70]	中	该IP被黑产持有的概率远高于被正常用户持有	推荐中等强度、对用户体验影响较小的风控处理手段。
(70,10]	低	该IP被黑产持有的概率仍然高于被正常用户持有，但存在一定比例的IP已经流回到正常用户	推荐较弱强度，对用户体验无影响的风控处理手段，或对相关账号进行标记，如爬虫场景中若某一账号多次关联风险IP，一些IP处于低风险，但该账号一定是高风险。
0	无	无风险，白名单或近一周未曾参加过黑产活动	建议放行，不做处理。

用户可以根据不同的业务场景和风险容忍度，并结合实际测试和使用效果，灵活调整各风险等级对应的风险分数阈值。该产品也可作为成熟风控系统的第三方外部数据补充，以支撑更精准的风险判断。IP画像主要可用于识别CC攻击、暴破撞库、虚假注册、恶意爬虫、以及营销活动薅羊毛等作恶风险，但不局限于上述风险。

四. 风险标签说明

（1）场景适配使用

解决某一场景的特定问题时可以参考标签使用，如爬虫场景通常会命中代理、秒拨标签。

（2）数据打标

在数据分析中，可以根据标签命中情况对数据进行打标、分类、筛选等。

五. 错误码表

status	errmsg
200	返回正常
10000	服务内部错误，请联系管理员
10001	请求体解析错误
10002	请求参数错误
10003	用户或密钥错误
10004	IP不在白名单，请登录控制台添加IP白名单，5分钟生效
10005	服务不存在
10006	账号已过期
10007	请求次数不足
10008	无效IP
10009	attackTime必须小于3000000000
10010	attackTime传入的时间必须在30天内
10011	账号已无法请求该服务
10012	请求频率过快

六. DEMO示例

• Go
• Java
• Python