虹膜调查
API文档
概述
Iris Investigate API非常适合调查和编排人类规模的用例。
这些通常是由分析师按需触发的，他们需要寻找单个指标的额外背景，从一个或多个域名开始的调查可获得最佳结果。
虹膜调查API的主要特点包括:
- 几十个域名属性的每个结果，包括:
- 来自邻近性和威胁概况算法的领域风险评分
- Whois, IP，主DNS，网站和SSL数据
- 大多数属性上连接域的计数
- 域配置文件和轴心搜索的统一API端点
- 支持批处理和分页
- 按身份、IP、名称服务器、邮件服务器、SSL证书等进行搜索
- 提供交互式虹膜网络应用程序
开始虹膜调查API
API端点:
https://api.domaintools.com/v1/iris-investigate/
API认证:
虹膜调查API使用与所有DomainTools API相同的身份验证机制，有一个重要的区别:查询限制源自分配给虹膜调查UI的查询，并与查询共享。
这意味着API用户名必须与DomainTools企业帐户连接，该帐户被授权访问虹膜调查。通常，这发生在由DomainTools企业支持团队设置帐户期间。请确保使用由您的DomainTools联络点颁发给您的组织的正确API用户名和API密钥。
在开发和测试期间必须小心，以确保交互式查询不会因脚本错误而意外耗尽。考虑在项目的测试阶段从免费的样例查询开始。
免费样品查询:
这些查询可用于测试API，不会计入查询限制:
https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com
https://api.domaintools.com/v1/iris-investigate/?ip=199.30.228.112
域名配置文件与虹膜调查API
Iris Investigate API支持使用单个参数(除了身份验证令牌之外)的域概要文件用例。只需在domain参数中传递一个域名，就可以检索虹膜中关于该域的所有可用信息。
例如:
https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com
您还可以在单个批处理中传入一个逗号分隔的最多100个域名列表。API将批处理请求视为单个查询，用于计算和速率限制目的，因此在您有多个域名进行概要分析时，都鼓励进行批处理。
例如:
https://api.domaintools.com/v1/iris-investigate/?domain=domaintools.com,domaintools.net,dailychanges.com
为了获得最佳结果，特别是对于长域名列表，应考虑使用HTTP POST方法而不是GET参数。
Iris Investigate API将为在Iris数据集中找到的每个域名返回一条记录。如果您批量提交了一个域列表，请确保将API响应中返回的域列表与您自己的列表进行比较，以便您可以检测到您请求的域名何时没有在Iris数据集中找到。使用Iris记录中的“domain”属性进行匹配。
虹膜调查API引导枢轴
交互式Iris Investigate产品中最强大的功能之一是Guided Pivots，它可以帮助用户快速识别域名的哪些属性与相对较少的其他域名相连接。计数越小，这些域越有可能是相关的。
Iris Investigate API为域响应中的几乎每个属性、每个域记录交付这些计数，甚至在处理一批域名时也是如此。
这些计数作为属性的属性包含在API响应中，与属性值相邻，以便在集成中更容易利用它们。这也解释了为什么字段的值比您预期的要深一级。例如:
ip: [{address: {value: "199.30.228.112"， count: 3}， asn: [{value: 17318, count: 101}]， country_code: {value: "us"， count: 239988363}， isp: {value: "Domaintools LLC"， count: 108}}]
在这里，我们确定IP地址“199.30.228.112”，ASN“17318”和ISP“Domaintools LLC”作为潜在的支点，或至少作为有意义的分析来帮助分析域名。例如，只有很少其他域指向的IP地址通常表示由同一实体控制的专用主机。
在Iris Investigate UI中，我们使用默认阈值500个连接来决定哪些属性需要引起用户的注意。考虑从集成的相似阈值开始，但是为用户提供选择不同阈值的选项以匹配他们的用例。
注意，空数据元素的计数为0。
搜索和旋转虹膜调查API
Iris调查API也可以用于搜索模式。您可以向API提供一个或多个搜索字段，如IP地址、SSL散列、电子邮件等，而不是域名，Iris将返回与这些参数匹配的记录的任何域名。这允许使用单个API端点对一个或多个字段进行“反向”搜索。
例如:
https://api.domaintools.com/v1/iris-investigate/?ip=199.30.228.112
跨多个参数的查询被解释为逻辑AND查询，这意味着多个参数将把搜索范围缩小到更小的结果集。虹膜调查API目前不支持逻辑或查询;相反，为每个参数提交单独的查询，并将结果集合并到您自己的代码中。
结果集中返回的域记录与查询一个或多个域名返回的记录相同，这提供了一个丰富的结果集，可以显示给最终用户，非常适合进一步的旋转。例如，考虑使用引导的枢轴计数来显示扩展结果集的新方法。或者，您可以根据风险评分(从高到低)进行排序，以将风险最高的域列在前面，向最终用户显示结果。
支持参数
| 参数 | 功能 | 比较 |
|---|---|---|
| 知识产权 | 在主动DNS检查期间，注册域最后指向的IPv4地址 | 反知识产权 |
| 电子邮件 | 来自最近可用的Whois记录，DNS SOA记录或SSL证书的电子邮件地址 | 反向域名查询服务 |
| email_domain | 只有Whois或DNS SOA电子邮件地址的域部分 | 反向域名查询服务 |
| nameserver_host | 名称服务器的完全限定主机名(ns1.domaintools.net) | - |
| nameserver_domain | 名称服务器的注册域部分(domaintools.net) | 反向命名服务器 |
| nameserver_ip | 名称服务器的IP地址 | - |
| 注册商 | 与Whois注册表字段完全匹配 | 反向域名查询服务 |
| 注册人 | Whois注册人字段上的子字符串搜索 | 反向域名查询服务 |
| registrant_org | Whois注册人组织字段上的子字符串搜索 | 反向域名查询服务 |
| mailserver_host | 邮件服务器的完全限定主机名(mx.domaintools.net) | 反向MX |
| tagged_with_any | 在“虹膜调查”平台上已贴上“特定”域名标签/“其中之一”标签的域名 | - |
| tagged_with_all | tagged_with_all | - |
| mailserver_domain | 仅邮件服务器的注册域部分(domaintools.net) | - |
| mailserver_ip | 邮件服务器的IP地址 | - |
| redirect_domain | 查找观察到的域以重定向到另一个域名 | - |
| ssl_hash | SSL证书SHA-1哈希 | - |
| ssl_org | 与SSL证书上的组织名称完全匹配 | - |
| ssl_subject | 来自SSL证书的主题字段 | - |
| ssl_email | SSL证书中的电子邮件地址 | - |
| google_analytics | 域与谷歌分析跟踪代码 | - |
| 广告联盟 | 域名与谷歌AdSense跟踪代码 | - |
| search_hash | 从虹膜UI编码搜索 | - |
作为搜索参数的域标记
虹膜调查API支持检索已经在虹膜调查UI中标记的域的能力。目前，在虹膜调查UI的实例中创建的所有标签都可以通过API访问。
下表总结了使用search参数时的功能:
| 场景 | 样本参数 | 预期的结果 |
|---|---|---|
| 检索与指定标记之一匹配的域 | ? tagged_with_any =看监视器 |
所有被标记为“监视”或“监视”的域 |
| 检索匹配标签列表的域 | ? tagged_with_all =块,危险、邪恶 |
所有被标记为“阻塞”、“危险”和“邪恶”3个标签的域名 |
查询限制和分页
虹膜调查API中的某些查询有可能匹配非常大的一组域。理想情况下，实现将利用Iris中为域名查询返回的计数，以编程方式选择合理的透视点，但这只在从域名开始调查时才实际。对于以上面列出的参数之一开始搜索的情况，必须检查Iris结果，以查看搜索是否超过限制或已进行分页。
例如，考虑以下查询:
https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone
虹膜调查API返回以下响应片段:
response: {limit_exceeded: false, has_more_results: true, message: "There is more data for you to enjoy."， results_count: 500, total_count: 3735, position: "2c056abadfb64b67ba18896af2c5b900"， results: [{domain: "1000miglia. "看”,…
“limit_exceeded”值“false”告诉我们，我们的搜索是在Iris的能力和我们的合同服务水平范围内的，因此我们可以从Iris检索完整的结果集。
“has_more_results”值为“true”表示我们的响应不包括所有匹配我们搜索的域名。我们可以精确地看到“results_count”字段中包含了多少，以及“total_count”字段中有多少是可用的。
要检索完整的结果集，请使用相同的查询参数再次提交查询，但在响应中的position值中添加“position”参数集。
例如:
https://api.domaintools.com/v1/iris-investigate/?nameserver_domain=markmonitor.zone&position=2c056abadfb64b67ba18896af2c5b900
在每个结果集中使用新的位置值重复此模式，直到响应中的has_more_results值设置为“false”。
虹膜搜索过滤器
在某些情况下，通过附加的过滤器来限制Iris结果集可能是有用的，甚至是必要的。这些参数可以添加到虹膜调查API中的任何搜索，尽管它们不能单独使用。
| 活跃的 | 设置为“true”将只返回在全局DNS系统中有条目或已被注册表列出的域。设置为“false”将只返回在全局DNS系统中没有条目且未被注册表列出的域。完全排除过滤器以查找处于这些状态中的域。 |
| data_updated_after | 在该日午夜或之后更新的虹膜记录，格式为YYYY-MM-DD。必须与另一个参数配对。对于监视用例非常有用(参见下面)。 |
| tld | 限制结果只包含特定顶级域中的域(例如" tld=com "或" tld=ru ") |
| create_date | 只包含特定日期创建的域，格式为YYYY-MM-DD |
| expiration_date | 只包含在特定日期到期的域，格式为YYYY-MM-DD |
| tagged_with_any | 只在虹膜调查平台中包含带有“特定”标签/“其中之一”标签的域名 |
| tagged_with_all | 只包含带有筛选条件中指定的所有标记的域 |
| not_tagged_with_any | 在虹膜调查平台中排除所有带有“特定”标签/“其中之一”标签的域 |
| not_tagged_with_all | 在虹膜调查平台中排除所有标有“标签列表”的域 |
域“标签”作为筛选参数
Iris Investigate API支持通过过滤域进一步限制结果集的能力，这些域已经被标记为Iris Investigate UI中的调查的一部分。目前，在虹膜调查UI实例中创建的所有标签都可以通过API访问。
下表总结了使用search参数时的功能:
| 场景 | 样本参数 | 预期的结果 |
|---|---|---|
| 过滤结果集，只显示匹配指定的“标签”之一的域 | ? nameserver_domain = markmonitor.zone&tagged_with_any =观察、监控 |
只列出标记为“监视”或“监视”的域 |
| 过滤结果集，只显示匹配“标签”列表的域 | ? nameserver_domain = markmonitor.zone&tagged_with_all =块,危险、邪恶 |
只列出所有3个标签的域名——“观察”、“危险”和“邪恶” |
| 过滤结果集，排除匹配指定“标签”之一的域 | ? nameserver_domain = markmonitor.zone¬_tagged_with_any =看监视器 |
只列出未标记为' watch '或' monitor '的域 |
| 通过排除域来过滤结果集 | ? nameserver_domain = markmonitor.zone¬_tagged_with_all = zerolisted,安全、可信的 |
只列出未被标记为“零列表”、“安全”和“可信”的域名 |
| 匹配“标签”列表 | - | - |
使用虹膜调查API进行监测
Iris Investigate API可以作为一个强大的监视工具来检测指向特定ip的新域，托管在目标名称服务器上，重定向到特定站点，以及可以在Iris API查询中框架的任何其他条件。甚至可以监视域名的Iris记录中可用属性的变化。
这可以通过将data_updated_after参数添加到任何Iris搜索中，将值设置为当前日期，并每天重复该查询一次以查找新的更新来实现。
一个潜在的实现可能遵循类似于下面的模式:
- 在Iris中创建一个搜索查询，定义要监视的属性。
- 将查询提交给Iris以获得基线。将数据存储在您自己的系统中。
- 每天重新提交相同的查询，但是添加data_updated_after参数，设置为当天的日期。然后:
- 与存储的基线进行比较，以查找添加或删除的域
- 遍历基线快照中已经存在但已经以某种方式更新的域。比较它们的基本记录并注意差异。
- 将添加、删除或更新存储为新的基线，可能保留以前的值以进行历史跟踪
这一功能使得Iris调查API成为DomainTools企业API监视器的引人注目的替代品，目前在其结果中只返回一个域，包括注册人监视器，名称服务器监视器和IP监视器。它还将监视扩展到这些端点之外，包括对SSL属性、跟踪代码、注册器等的监视，并通过tld=过滤器将监视范围缩小到特定的顶级域名。
集成虹膜调查UI和虹膜调查API
虹膜调查平台提供了一个丰富的UI来搜索和透视域名数据。虹膜调查“枢轴引擎”窗格中的几乎所有数据都可以在虹膜调查API中访问，最常见的研究模式可以通过该API轻松完成。
然而，即使在API中有了这些功能，仍然存在一些情况，即用户只能通过Iris Investigate UI中提供的完整的工具和资源集来实现他们的目标。这些场景包括:
- “OR”搜索，或跨多个字段和值的嵌套“AND”和“OR”搜索。
- 对单个域的托管、whois或截屏历史进行特别调查
- 图形可视化和图形启动的旋转
- 被动DNS对ip和主机名的查询
这意味着用户可以在虹膜调查UI中开始他们的调查，然后期望把他们的调查结果带到第三方产品。API中的search_hash参数使这成为可能。下面是它的工作原理。
首先，用户在Iris Investigate UI中执行调查，可能构建一个复杂的查询，以查找给定域名或威胁参与者的所有连接基础设施。他们访问虹膜调查的高级搜索和导出他们的搜索的编码表示。
接下来，用户向您的解决方案提供这个经过编码的字符串，然后使用search_hash参数中的该字符串创建Iris Investigate API搜索。不需要或不支持其他搜索参数(除了应该始终存在的基本授权参数)。Iris API“解包”编码的搜索，再次运行相同的查询，并返回最新的完整结果集。
Iris Investigate API还支持除search_hash参数外的data_updated_after过滤器(参见上面的监视用例)。这使得随着时间的推移以编程方式监视用户虹膜查询的结果成为可能。