注意:在 PyDat 5 开发过程中,内部操作的方向发生了变化,导致 PyDat 项目退役。虽然已完成大量工作以最终确定 PyDat 5 的功能,但某些功能仍未得到充分测试。
WhoDat 项目是一个用于 whoisxmlapi 数据或任何存在于 ElasticSearch 中的 whois 数据的接口。它集成了 whois 数据、当前 IP 解析和被动 DNS。除了为分析师提供交互式、可旋转的应用程序进行研究外,它还有一个 API,支持以 JSON 格式输出。
WhoDat 最初由 Chris Clark 编写。原始实现使用 PHP,可在本仓库的 legacy_whodat 目录下获取。Wesley Shields 和 Murad Khan 使用 Python 从头重写了代码,可在 pydat 目录下获取。
PHP 版本保留给希望运行它的人,但其功能不如 Python 实现完整或可扩展,并且不受支持。
有关 PHP 实现的更多信息,请参阅 readme。有关 Python 实现的更多信息,请继续阅读...
pyDat 是 Chris Clark 的 WhoDat 代码的 Python 实现。它旨在更加可扩展,并具有比 PHP 实现更多的功能。
pyDat 是一个 Python 3.6+ 应用程序,运行需要以下条件:
为了帮助正确填充数据库,提供了一个名为 pydat-populator 的程序来自动填充数据。
请注意,来自 whoisxmlapi 的数据似乎并不总是一致的,因此在摄取数据时应小心谨慎。
需要进行更多测试以确保所有数据被正确摄取。
任何设置数据库的人,在运行脚本之前应阅读脚本的可用标志,确保已根据自己的设置进行了调整。
以下是 pydat-populator -h 的输出:
usage: pydat-populator [-h] [-c CONFIG] [--debug] [--debug-level DEBUG_LEVEL]
[-x EXCLUDE [EXCLUDE ...]] [-n INCLUDE [INCLUDE ...]]
[--ignore-field-prefixes [IGNORE_FIELD_PREFIXES [IGNORE_FIELD_PREFIXES ...]]]
[-e EXTENSION] [-v] [-s] [--pipelines PIPELINES]
[--shipper-threads SHIPPER_THREADS]
[--fetcher-threads FETCHER_THREADS]
[--bulk-ship-size BULK_SHIP_SIZE]
[--bulk-fetch-size BULK_FETCH_SIZE]
[-u [ES_URI [ES_URI ...]]] [--es-user ES_USER]
[--es-pass ES_PASSWORD] [--cacert ES_CA_CERT]
[--es-disable-sniffing] [-p ES_INDEX_PREFIX]
[--rollover-size ES_ROLLOVER_DOCS] [--ask-pass]
[-r | --config-template-only | --clear-interrupted-flag]
[-f INGEST_FILE | -d INGEST_DIRECTORY] [-D INGEST_DAY]
[-o COMMENT]
optional arguments:
-h, --help 显示此帮助信息并退出
-c CONFIG, --config CONFIG
用于环境参数配置的配置文件位置(示例 yaml 文件在 /backend 中)
--debug 启用调试日志
--debug-level DEBUG_LEVEL
调试日志级别 [0-3](默认:1)
-x EXCLUDE [EXCLUDE ...], --exclude EXCLUDE [EXCLUDE ...]
更新条目时要排除的键列表
-n INCLUDE [INCLUDE ...], --include INCLUDE [INCLUDE ...]
更新条目时要包含的键列表(与 -x 互斥)
--ignore-field-prefixes [IGNORE_FIELD_PREFIXES [IGNORE_FIELD_PREFIXES ...]]
在提取和插入 ElasticSearch 时忽略的字段(在 whois 数据中)列表
-e EXTENSION, --extension EXTENSION
扫描 CSV 文件时仅解析具有给定扩展名的文件(默认:csv)
-v, --verbose 详细输出
-s, --stats 运行后打印统计信息
-r, --redo 尝试重新导入失败的导入或导入更多数据,使用之前运行存储的元数据
--config-template-only
配置 ElasticSearch 模板并退出
--clear-interrupted-flag
强制清除中断标志(不推荐)
-f INGEST_FILE, --file INGEST_FILE
输入的 CSV 文件
-d INGEST_DIRECTORY, --directory INGEST_DIRECTORY
递归搜索 CSV 文件的目录——与 '-f' 选项互斥
-D INGEST_DAY, --ingest-day INGEST_DAY
用于元数据的日期,格式为 'YYYY-MM-dd',例如 '2021-01-01'。默认为今天日期,使用 'YYYY-MM-00' 表示季度摄取,例如 2021-04-00
-o COMMENT, --comment COMMENT
与元数据一起存储的注释
Performance Options:
--pipelines PIPELINES
管道数量(默认:2)
--shipper-threads SHIPPER_THREADS
每个管道生成多少个线程用于发送批量 ES 消息。集群越大,可以增加此值,默认为 1
--fetcher-threads FETCHER_THREADS
生成多少个线程用于搜索 ES。集群越大,可以增加此值,默认为 2
--bulk-ship-size BULK_SHIP_SIZE
批量 Elasticsearch 请求的大小(默认:10)
--bulk-fetch-size BULK_FETCH_SIZE
一次搜索的文档数(默认:50),请注意,此值将乘以您拥有的索引数,例如,如果您有 10 个 pydat-<number> 索引,则会产生 500 个文档的请求
Elasticsearch Options:
-u [ES_URI [ES_URI ...]], --es-uri [ES_URI [ES_URI ...]]
ElasticSearch 服务器的位置(例如,foo.server.com:9200)可以接受多个端点
--es-user ES_USER 启用基本认证时 ElasticSearch 的用户名
--es-pass ES_PASSWORD
启用基本认证时 ElasticSearch 的密码
--cacert ES_CA_CERT 启用 https 支持的 CA 证书包路径
--es-disable-sniffing
禁用 ES 嗅探,在 ssl 主机名验证无法正常工作时有用
-p ES_INDEX_PREFIX, --index-prefix ES_INDEX_PREFIX
在 ElasticSearch 中使用的索引前缀(默认:pydat)
--rollover-size ES_ROLLOVER_DOCS
设置创建新索引之前的文档数量,默认值为 5000 万,请注意这是模糊的,因为索引计数不会持续更新,因此应合理地低于每个 ES 分片的 20 亿,并应考虑您的 ES 配置
--ask-pass 提示输入 ElasticSearch 密码
请注意,向数据库添加新版本数据时,应使用 -x 标志排除不重要跟踪变化的字段,或使用 -n 标志包含需要审查的特定字段。这将显著减少版本之间存储的数据量。您只能同时使用 -x 或 -n,不能同时使用,但可以根据您的环境选择最适合的一个。例如,如果您每天收到更新,您可能决定对于每日更新只关心 contactEmail 是否更改,但每季度您可能希望仅排除您认为不重要的某些字段。
为了节省重复使用标志的时间,pydat-populator 支持配置文件。
请查看 示例配置 以了解如何创建配置文件。
pyDat 本身不提供任何数据。您必须在 ElasticSearch 数据存储中提供自己的 whois 数据。
pydat-populator -u localhost:9200 -f ~/whois/data/1.csv -v -s -x Audit_auditUpdatedDate,updatedDate,standardRegUpdatedDate,expiresDate,standardRegExpiresDate
PyDat 5 是一个分离的后端/前端应用程序,使用 Python Flask 提供 REST API,使用 ReactJS 提供交互式 Web UI。使用该应用的最简单方式是构建 Docker 镜像。
cd pydat/
docker build -t mitrecnd/pydat:5
创建的镜像会将前端组件编译并安装到后端,从而允许部署完整应用。
然后可以通过创建部署配置文件并使用 docker-compose 来部署应用:
version: '3'
services:
pydat:
image: mitrecnd/pydat:5
volumes:
- "./config.py:/opt/pydat/config.py:ro"
ports:
- 127.0.0.1:8888:8888
通过复制 config_example.py 文件作为 config.py 到与 docker-compose.yml 相同的目录来生成配置文件。
Python 后端也可以使用 pip 安装。如果您希望本地运行数据填充功能,这很有用。请注意,这不包含任何前端组件,因为它们未预编译。如果您希望手动编译和安装前端,请参考 dockerfile。
cd pydat/backend/
pip install ./
安装该包将允许您访问上面引用的 pydat-populator 程序。
PyDat 5 引入了更新的 REST API,但仍维护一组 v1 API 端点,以近似 Pydat 4 返回的输出。由于 pyDat 4 和 5 之间的一些结构变化,输出不会完全相同。
v1 端点暴露以下端点:
api/v1/metadata/
api/v1/metadata/<version>/
元数据端点返回数据库中可用数据的元数据。指定版本将返回该特定版本的元数据。
api/v1/domain/<domainName>/
api/v1/domain/<domainName>/latest/
api/v1/domain/<domainName>/<version>/
api/v1/domain/<domainName>/<version1>/<version2>/
api/v1/domain/<domainName>/diff/<version1>/<version2>/
域名端点允许您获取特定域名的信息。默认情况下,它将返回数据库中任何版本的域名信息。您可以指定更多信息来获取特定版本的域名信息或获取最新条目。您还可以获取两个版本之间的差异以查看更改内容。
api/v1/domains/<searchKey>/<searchValue>/
api/v1/domains/<searchKey>/<searchValue>/latest/
api/v1/domains/<searchKey>/<searchValue>/<version>/
api/v1/domains/<searchKey>/<searchValue>/<version1>/<version2>/
域名搜索端点允许您根据指定的键搜索域名。当前支持以下键:
domainName
registrant_name
contactEmail
registrant_telephone
与域名端点类似,您可以指定查找数据的版本。
示例查询:
curl http://pydat.myorg.domain/ajax/domain/google.com/latest/
curl http://pydat.myorg.domain/ajax/domains/domainName/google.com/
api/v1/query
此端点通过 GET 请求接受 4 个参数:
query - 用于搜索 ES 的查询
size - 返回的元素数量(即页面大小)
page - 要返回的页面,结合使用 size 可以分块获取结果
unique - 尝试返回每个 domainName 的最新条目
关于 unique 参数的注意事项:如果使用 unique 参数,请注意分页将被禁用,但 size 参数仍将用于控制返回结果的数量。
v2 端点暴露以下端点:
api/v2/metadata
api/v2/metadata/<version>
这些端点与其 v1 对应端点类似,但响应格式不同。
api/v2/resolve/<domain>
这是一个新端点,允许将域名解析为 IP 地址。请注意,此功能可由后端禁用。在调用之前,请调用 /settings 端点以确保此功能已启用。
api/v2/domains/diff [POST]
此端点允许获取两个域名版本之间的差异以查看更改内容。它期望以下形式的 JSON 请求:
{
domain: "mydomain.example",
version1: 1,
version2: 2
}
api/v2/domain [POST]
此端点返回给定域名的信息,并期望以下形式的 JSON 请求:
{
value: "mydomain.example",
version: 1, # 可选
chunk_size: 50, # 可选
offset: 0 # 可选
}
api/v2/query [POST]
此端点支持“高级”查询语法功能。它期望以下形式的 JSON 请求:
{
query: "myquery",
chunk_size: 50, # 可选
offset: 0, #可选
unique: false, # 可选
sort_keys: [ # 可选
"domainName",
"registrant_name",
"contactEmail",
"standardRegCreatedDate",
"registrant_telephone",
"dataVersion",
"_score",
]
}
api/v2/info
此端点提供 Elastic 集群的健康信息。
api/v2/settings
此端点主要用于前端动态确定后端应用程序启用了哪些功能。
不幸的是,由于数据在 Elastic 中存储方式的结构性变化,pyDat 5 与 pydat 4 不向后兼容。 这意味着数据需要重新摄入到 ElasticSearch 集群中才能与 pyDat 5 一起使用。
pyDat 版权归 The MITRE Corporation 2021 所有。
PHP 实现版权归 Chris Clark 2013 所有。联系他请发送邮件至 [email protected]。
PHP 和 Python 版本采用相同许可证。
pyDat 是自由软件:您可以重新分发和/或修改它,前提是遵守 GNU 通用公共许可证的条款,无论是许可证的第 3 版,还是(由您选择)任何更高版本。
pyDat 的分发希望它有用,但不提供任何保证;甚至没有暗示的适销性或特定用途的保证。有关详细信息,请参阅 GNU 通用公共许可证。
您应该已经随 pyDat 收到了一份 GNU 通用公共许可证的副本。如果没有,请访问 http://www.gnu.org/licenses/。
经批准公开发布;分发无限期 14-1633