API文档

虹膜检测

> > > 虹膜检测

概述


介绍

虹膜检测可以防止恶意域名冒充您的品牌和域名，因此您可以保护您的组织，您的客户和您的商标。您还可以防御供应链攻击，其中恶意域冒充知名技术供应商，甚至冒充您经常合作的合作伙伴。乐动首页虹膜检测通过发现全球出现的模仿你的品牌的新域名来做到这一点。您可以从DNS、Whois和DomainTools风险评分中快速看到关键信息，轻松访问威胁级别。虹膜检测还监视域随着时间的推移，所以你可以看到它们是如何演变的，然后让你采取必要的行动。

关于虹膜检测接口

为了方便，通过Detect UI执行的许多操作都可以以编程方式安排。检测api可以进一步自动化您的工作流程，并将虹膜检测的数据输入到您现有的应用程序中。

通过api支持的功能:

  • 读:检索数据
  • 写:进行更改，如向监视列表添加域或升级域以进行进一步操作。

API在1.0版本中不支持

  • 监视器创建:所有监视器需要通过虹膜检测UI创建。由于该任务的性质以及它的可迭代性，目前将不通过编程访问来支持它。
  • 截图:目前不支持通过API获取截图。
  • 基于事件的更新:没有办法“订阅”更改，所有的更新都需要通过“拉”动作来检索。

开始

虹膜检测要求企业帐户登录DomainTools，您的帐户必须包括虹膜检测访问权限。此外，用户权限控制用户是否可以管理监视器、分类域或升级域。默认情况下，用户对应用程序具有只读访问权限。要使用检测API，您还需要您的用户名以及API密钥。

API的限制

具有特殊利率限制的端点

  • 域:可以以每小时最多一次的频率查询每个域端点域/新而且域/关注调用。
  • 获取完整域列表的分页请求不受限制。例如，如果每小时对新域的调用返回的值超过限制对于在单个响应中返回的域，可以使用抵消变量来完成结果，而不受每小时限制的影响。

在集成工作中绕过速率限制

在集成域API端点期间，包括预览请求中的参数将把响应限制为10个域，但允许每分钟最多30个请求。这使得在开发和测试期间能够快速迭代。

身份验证

我们建议采用以下方法进行身份验证:

  • 使用HTTPS (HTTP over SSL)而不是HTTP进行身份验证。
  • 使用HMAC签名查询代替Open Key身份验证。
  • 使用SHA-256 HMAC进行签名查询，而不是MD5或SHA-1。
  • 确保一个安全的过程来保护你的API凭证。

授权

根据您的帐户类型，您可以只检索最新发现的域，或将所述域添加到监视列表中，以进行持续监视和分析。

  • 只读权限:该帐户将没有权限添加/删除到watchlist端点。
  • 读写权限:该帐户将拥有现有的所有权限。

查找和重置API密钥

找到或重置DomainTools API键通过//www.xylmmw.com：

登录到DomainTools API仪表板。只有API所有者帐户可以重置API密钥。有两个地方可以访问它:

  • 选择账户菜单并选择API管理菜单项以访问API仪表板。
  • 在我的账户部分中,选择查看API仪表板链接，该链接位于帐户摘要选项卡中。

DomainTools我的帐户图像

  1. 在API产品信息选项卡，进入API用户名部分获取用户名。
  2. 在同一个选项卡中，你可以找到你的API密匙．
  3. 重置你的API密钥:
    • 选择重置API密匙．
    • 创建新密钥将导致现有密钥立即被丢弃。此操作无法撤消。
      使用旧键发出的任何请求将不再对该用户进行验证。

选择重置按钮来确认。

保护API凭证

您的帐户将为所有使用您的用户名和密钥进行认证的查询收取费用，即使您稍后确定请求是欺诈的或未经授权的使用。我们建议采取以下步骤来保护您的API凭据:

  • 对于支持请求，不要发送完整的API密匙DomainTools支持。
  • 对请求使用hmac签名的方法。这确保了用户和令牌不会作为URL的一部分发送。
  • 当需要时，重置API密钥。
  • 不要将它们放在公共存储库中，例如git存储库。

HMAC-Signed认证URI /参数

参数/ URI 价值
URI API端点的URI。它位于api.domaintools.com之后，例如/v1/yourdomain.com/whois。

检查每个DomainTools API产品的用户指南，以获得正确的URI结构。
api_username 你的API的用户名。
时间戳 当前时间戳，ISO 8601格式。时间戳应该包含时区偏移量，如下所示:
2020 - 02 - 01 - t14:37:59 - 0800
2020 - 02 - 01 - t22:37:59z
2020 - 02年- 02 - t10:37:59 + 1200
签名 您的请求的HMAC签名。
推荐使用SHA-256 HMAC协议。支持MD5 HMAC和SHA-1 HMAC。
只对URL路径签名。

构建hmac签名的身份验证请求

对HMAC

推荐使用HMAC(散列消息认证码)认证方案。它遵循RFC2104中概述的原则，提供了一个简单但安全的方法来保护你的API密钥。

关于HMAC算法

HMAC哈希算法支持MD5、SHA-1和SHA-256。我们推荐SHA256 HMAC，作为SHA1的继承者。尽管NIST对哈希函数的策略仍然允许HMAC SHA-1，参见NIST证监会中的哈希函数页面。总的来说，SHA-256 HMAC也是比MD5 HMAC更安全的选择(例如，对抗暴力攻击)。

关于应该使用什么加密函数，请检查您自己的遵从性义务或指南。例如，参见NISTFIPS 140-2为必须使用FIPS 140-2兼容算法的组织提供更多信息的指南。

创建hmac签名认证请求

要创建签名，构建一个包含API用户名、ISO 8601格式的时间戳和请求的URI的字符串。然后使用HMAC函数对该字符串与API密钥进行签名以生成签名。步骤如下。

  • 添加你的api_username。

API用户名是被授予访问相关DomainTools API产品(又名API端点)的帐户。如果此用户名没有访问权限，将返回错误消息。

  • 一个时间戳。

散列的时间戳值和时间戳参数必须相同。确保您的服务器时间是准确的，并始终使用新的时间戳。

  • 添加请求URI。

有关端点的URI格式，请参阅各个API产品的用户指南。

  • 添加主机。

主机是API端点服务器。在这种情况下，确实如此api.domaintools.com．

  • 使用合适的HMAC算法。

哈希算法支持MD5、SHA-1、SHA-256。有关更多信息，请参阅HMAC算法部分。

下面是一个示例，用于返回一个SHA-256 HMAC签名哈希请求，包含您的api_username, timestamp, URI, api_key。您可能会在首选的编程语言中发现对HMAC身份验证的内置支持。

返回hash_hmac('sha256'， $this->api_username。美元的时间戳。美元的uri, $ this - > api_key);
  • 结果是请求在一段时间后过期，最重要的是，在clear中不包含您的身份验证密钥。

无论使用哪种编程语言，生成的url通常都是类似的。

安全注意

确保您当前的语言版本支持所需的HMAC(和其他相关的)扩展和库。例如，hmac签名URL失败将导致URL没有签名值，如下所示:

http://api.domaintools.com/v1/yourdomain.com/whois

API端点列表

监控列表

正如名称所指定的，这个端点允许用户检索您的帐户的监视器和各自的id。方法检索各个监视器的新发现或最近更改的域，可以使用监视器idmonitor_id变量。另一方面，您还可以在单个请求中跨所有监视器请求新的或更改的域，方法是不指定monitor_id变量。由于域端点被限制为每小时一个查询请求，为所有监视器执行请求允许每小时检索所有监视器的结果。如果对集成很重要，仍然可以使用监视器端点帮助将域映射到它们的监视器。的include_counts变量将显示每个监视器的New、Changed等的数量。

可以使用诸如术语、创建日期、创建人等选项对结果进行排序和排序。必需的和可选的参数概述如下。

的/忽略端点允许您查看您忽略的域。

端点URL

https://api.domaintools.com/v1/iris-detect/domains/new/

https://api.domaintools.com/v1/iris-detect/domains/watched/

https://api.domaintools.com/v1/iris-detect/domains/ignored/

方法

得到

参数

有条件的要求

的名字 类型 有效值 默认值 笔记
datetime_counts_since datetime 有条件地要求，如include_counts参数包括

iso - 8601日期/时间格式

可选

的名字 类型 有效值 默认值 笔记
include_counts 保龄球 假 包括新、监视、更改和升级域的每个监视器的计数
排序 string [] Term, created_date, domain_counts_changed, domain_counts_discovered 术语 提供用于对监视器列表进行排序的选项。
订单 字符串 asc, desc desc 为选定的排序选项切换排序。
抵消 int 0 - 100000 0 用于超出限制的分页请求。
限制 int 500 如果include_counts=true，则限制为最大100个

示例使用

检索所有有计数的监视器

GET https://api.domaintools.com/v1/iris-detect/monitors/?datetime_counts_since=2022-01-14%2016:27:31&include_counts=true &api_username=<用户名>&api_key=

域

Domains端点使用户能够检索与特定监视器或所有监视器的域相关的详细信息。端点可以用来查看:

  • 新发现的领域
  • 最近更改的域(应用程序跟踪的关键DNS和Whois数据的更改)
  • 最近在应用程序中升级的域，升级是针对内部的
    或将域名发送到谷歌的钓鱼保护服务。升级就可以
    直接在应用程序UX或通过API触发(在下面的“升级”一节中介绍)。

有许多可选参数可用于根据需要筛选结果。

的/新端点可以为在虹膜检测中创建的监视器提供新发现的域。

的/看Endpoint将从监视器的监视域列表中为域提供最近更改的域。(域可以选择从虹膜检测UX或通过API观看，下文将进行讨论。)

的/看endpoint也可以用于查询已升级为阻塞或谷歌安全浏览的域。(域可以从虹膜检测UX或通过API升级，下文将讨论)。

端点URL：

https://api.domaintools.com/v1/iris-detect/domains/new/

https://api.domaintools.com/v1/iris-detect/domains/watched/

方法

得到

参数

要求

没有一个

可选

的名字 类型 有效值 默认值 笔记
monitor_id 字符串 监视器响应中的监视器ID—仅在为特定监视器请求域时使用。
escalation_types string [] 封锁,google_safe 筛选特定的升级类型
顶级域名 string [] 筛选特定的顶级域名
risk_score_ranges string [] 0-0, 1-39, 40-69, 70-99, 100-100 筛选具有不同范围风险评分的域。
mx_exists 布尔 域当前是否在DNS中有MX记录。
domain_state 字符串 活跃,不活跃的
discovered_since datetime iso - 8601日期/时间格式 与/新端点来控制发现新域的时间范围。
changed_since datetime iso - 8601日期/时间格式 与/看端点来控制更改被监视域的DNS或Whois字段的时间框架。
escalated_since datetime iso - 8601日期/时间格式 与/看端点来控制域最近升级的时间范围。
搜索 字符串 一个“包含”搜索域名。
排序 string [] domain_discovered、domain_changed risk_score 域列表响应的排序顺序。
订单 字符串 asc, desc 用于排序的排序选项
include_domain_data 布尔 包括DNS和Whois细节。
抵消 int 0 - 100000 0 用于超出限制的分页请求。
限制 int One hundred.
50如果include-domain-data = true		 One hundred.
50如果include-domain-data = true		 限制结果的大小。
预览 布尔 在API实现和测试期间使用。

包括with value = 1将限制结果为10，但不受每小时的限制。

示例使用

注意日期/时间格式遵循ISO-8601。不包含时区指示符将假定为太平洋时区。

在本文档的附录中可以找到响应数据的示例。

以毫秒精度检索太平洋标准时间的特定日期/时间以来新发现的域

得到https://api.domaintools.com/v1/iris detect/domains/new/?discovered_since=2022 - 01 - 12% 2000:00.000000 % 20-08:00&api_username = <用户名> api_key = < API key >

检索自给定日期/时间以来更改的所有被监视域

得到https://api.domaintools.com/v1/iris detect/domains/new/?discovered_since=2022 - 01 - 08% 2000:00 % 20-08:00&api_username = <用户名> api_key = < APIkey >

检索自太平洋标准时间的特定日期/时间以来已升级为内部阻塞的域

得到https://api.domaintools.com/v1/iris detect/domains/watched/?escalated_since=2022 - 01 - 11% 2016:00:00 % 20-08:00&api_username = <用户名> api_key = < API key > &escalation_types[] =屏蔽

从监视列表中添加和删除

分析和分类新发现的域是一项应该定期进行的活动，所以新域只显示最近发现的域。分类选项包括:

  • 添加到监视列表:添加一个域到监视列表将从新建中删除它，并允许跟踪域最近在DNS或Whois中更改的时间。被关注的域名将有截图捕获每天，所以你可以看到网页如何演变的时间。
  • Ignore:如果某个域明显为假阳性，则忽略该域，将其从New中删除，并将其置于Ignored之下。这个决定总是可以被逆转，并且可以将域从Ignored移到watching。

端点URL:https://api.domaintools.com/v1/iris-detect/domains/

方法

补丁

参数

要求

的名字 类型 有效值 默认值 笔记
watchlist_domain_ids string [] 被分类的域ID(s)。
状态 字符串 看,忽略 将域添加到监视列表或忽略和静音这些域的警报。

可选

没有一个

示例使用

将域添加到监视列表

URL:

https://api.domaintools.com/v1/iris-detect/domains/?api_username= <用户名> api_key = < API key >

身体:

｛“watchlist_domain_ids”：［“域ID > <”),“状态”：“看”｝

从监视列表中删除域

URL

https://api.domaintools.com/v1/iris-detect/domains/?api_username= < username&api_key = < API key >

身体:

｛“watchlist_domain_ids”：［“域ID > <”),“状态”：“忽略”｝

升级

该API支持两种升级活动，如下所示。

升级一个新域也将添加它，以观察变化。

  • 域名可以发送到谷歌的钓鱼保护团队。如果谷歌同意该域是恶意的，它
    将在Chrome浏览器中被屏蔽。这一列表也被苹果公司用于他们的Safari浏览器
    浏览器和火狐。
  • 如果域要在内部网络防御基础设施中被阻断，则可以将域标记为阻断。
    将域加载到公司的防火墙和其他系统需要通过API进乐动体育官网下载行
    查询与客户端的系统操作相结合。
  • 升级请求API调用的限制
    • 阻塞域:每个请求最多支持100个域。
    • 谷歌网络钓鱼防护:每次请求最多支持10个域。
    • 每分钟限制30个请求(每个请求可以包括以上的多个域)。

端点URL：https://api.domaintools.com/v1/iris-detect/escalations/

方法

帖子

参数

要求

的名字 类型 有效值 默认值 笔记
watchlist_domain_ids string [] 待升级域ID(s)
escalation_type 字符串 封锁,google_safe

可选

没有一个

示例使用

升级到谷歌安全浏览

URL:

https://api.domaintools.com/v1/iris-detect/escalations/?api_username= <用户名> api_key = < API key >

身体:

｛“watchlist_domain_ids”：［“域ID > <”),“escalation_type”：“google_safe”｝

升级内部阻塞

URL:

https://api.domaintools.com/v1/iris-detect/escalations/?api_username= <用户名> api_key = < API key >

身体:

｛“watchlist_domain_ids”：［“域ID > <”),“escalation_type”：“封锁”｝

附录1:API响应示例

监视器列表响应示例

这是一个从查询到Monitor List端点的响应示例，前面是请求:

请求示例

得到https://api.domaintools.com/v1/iris detect/monitors/?datetime_counts_since=2022 - 01 - 20% 2011:03:21&include_counts = true&api_username = <用户名> api_key = < API key >

反应的例子

下面是响应的示例，包括每个监视器的计数:

｛“total_count”：16，“抵消”：0，“限制”：500，“监控”：［｛“术语”：“domaintools”，“match_substring_variations”：真正的，“nameserver_exclusions”：[]，“text_exclusions”：[]，“id”：“JKwjv5Xp8x”，分配”created_date”：“2022 - 01 - 15 t00:32:04.418134 + 00:00”，“updated_date”：“2022 - 01 - 15 t00:32:04.418134 + 00:00”，“状态”：“活跃”，“状态”：“完成”，“domain_counts”：｛“新”：2，“看”：5，“升级”：1，“改变”：2}，“created_by”：“<用户名>”｝］｝

域列表响应示例

以下示例用于查询域/新端点，对于查询已更改的域或自给定日期/时间以来已升级的域，域/已更改端点的结果将是相同的。

请求示例

该请求包括布尔变量，以包括DNS和Whois的关键字段的域数据。

得到https://api.domaintools.com/v1/iris detect/domains/new/?discovered_since=2022 - 01 - 20% - 20% - 2009:40:12.000000 % 20-08:00&api_username = <用户名> api_key = < API key > &include_domain_data = 1

反应的例子

这是一个响应示例，包括DNS和Whois数据的详细信息。注意“risk_score_status”:“临时”字段，用于指示响应的部分示例，包括DNS和Whois数据的详细信息。风险评分状态表示评分是临时的还是满分。新发现的域名将只有初始接近或钓鱼评分，并指定为临时评分。24-36小时后，计算一个完整的风险评分，并添加恶意软件和垃圾邮件评分值。

｛“watchlist_domains”：［｛“状态”：“新”，“域”：“bestanbanks.in”，“状态”：“活跃”，“discovered_date”：“2022 - 01 - 20 - t20:26:14.378000 + 00:00”，“changed_date”：“2022 - 01 - 20 - t20:27:58.000000 + 00:00”，“risk_score”：67，“risk_score_status”：“临时”，“risk_score_components”：｛“距离”：21，“threat_profile”：｛“网络钓鱼”：67｝}，“mx_exists”：真正的，“tld”：“在”，“id”：“8 avjyb1xaj”，“升级”：［｛“escalation_type”：“封锁”，“id”：“p6db6jQbVJ”，“创建”：“2022 - 01 - 07 - t16:44:40.491903 + 00:00”，“created_by”：“<用户名>”｝),“monitor_ids”：［“Y41pGXBjEq”),“name_server”：［｛“主机”：“dimitris.ns.cloudflare.com”}，｛“主机”：“zainab.ns.cloudflare.com”｝),“registrant_contact_email”：［“请与上述注册主任联系”),“注册”：“GoDaddy.com,有限责任公司”，“create_date”：20220120，“知识产权”：［｛“country_code”：“我们”，“知识产权”：“172.67.192.30”，“服务提供商”：“CloudFlare公司。”}，｛“country_code”：“我们”，“知识产权”：“104.21.81.241”，“服务提供商”：“CloudFlare公司。”｝),“mx”：［｛“主机”：“mx1.hostinger.in”}，｛“主机”：“mx2.hostinger.in”｝］｝),“total_count”：1，“数”：1，“抵消”：0，“限制”：One hundred.｝

添加待监控域示例

此请求用于将域添加到帐户的监视列表中。方法可用于忽略域的类似请求“状态”:“忽略”而不是“状态”:“看着”．

请求示例

请求URL:

补丁https://api.domaintools.com/v1/iris-detect/domains/?api_username= <用户名> api_key = < API key >

请求主体:

｛“watchlist_domain_ids”：［“AaLMA1oOE0”),“状态”：“看”｝

反应的例子

｛“watchlist_domains”：［｛“状态”：“看”，“域”：“facebook - 09835. - pl”，“discovered_date”：“2022 - 01 - 20 - t18:35:29.801000 + 00:00”，“changed_date”：“2022 - 01 - 20 - t18:57:34.000000 + 00:00”，“id”：“AaLMA1oOE0”，“assigned_by”：“<用户名>”，“assigned_date”：“2022 - 01 - 20 - t22:27:39.000000 + 00:00”｝］｝

升级阻塞域示例

这个请求是为了升级一个域来进行内部阻塞。方法将域升级为谷歌的类似请求:“escalation_type google_safe”而不是“escalation_type”:“封锁”．

请求示例

URL请求:

文章https://api.domaintools.com/v1/iris-detect/escalations/?api_username= <用户名> api_key = < API key >

请求主体:

｛“watchlist_domain_ids”：［“AaLMA1gOE0”),“escalation_type”：“封锁”｝响应例子｛“升级”：［｛“watchlist_domain_id”：“AaLMA1gOE0”，“escalation_type”：“封锁”，“id”：“BWdgkK8g6p”，分配”created_date”：“2022 - 01 - 20 - t23:25:48.990908 + 00:00”，“updated_date”：“2022 - 01 - 20 - t23:25:48.990908 + 00:00”，“created_by”：“<用户名>”｝］｝
一般信息
产品
DomainTools标志
定价 联系 登录 支持 请求一个演示

©2022 DomainTools

DomainTools®和DomainTools™由DomainTools所有，版权所有。

隐私政策|加州的隐私请注意
不要出售我的个人信息|服务条款|网站地图