mitrecnd/whodatПивотный обратный WhoIs / Объединение PDNS с отслеживанием регистрантов и оповещением плюс API для автоматизированных запросов (JSON/CSV/TXT)
ПРИМЕЧАНИЕ: В ходе разработки PyDat 5 внутренние операции изменили направление, что привело к закрытию проекта PyDat. Хотя было проделано много работы для завершения возможностей PyDat 5, некоторые возможности остаются не полностью протестированными.
Проект WhoDat представляет собой интерфейс для данных whoisxmlapi или любых whois-данных, хранящихся в ElasticSearch. Он объединяет whois-данные, текущие разрешения IP и пассивный DNS. Помимо предоставления интерактивного, сводного приложения для аналитиков, оно также имеет API, который позволяет выводить данные в формате JSON.
WhoDat изначально был написан Chris Clark. Оригинальная реализация на PHP доступна в этом репозитории в каталоге legacy_whodat. Код был полностью переписан Wesley Shields и Murad Khan на Python и доступен в каталоге pydat.
PHP-версия оставлена для тех, кто хочет её запустить, но она не обладает такой же полнотой функций или расширяемостью, как реализация на Python, и не поддерживается.
Для получения дополнительной информации о реализации на PHP см. readme. Для получения дополнительной информации о реализации на Python читайте дальше...
pyDat — это реализация на Python кода WhoDat от Chris Clark. Он разработан так, чтобы быть более расширяемым и иметь больше функций, чем реализация на 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 show this help message and exit
-c CONFIG, --config CONFIG
location of configuration file for
environmentparameter configuration (example yaml file
in /backend)
--debug Enables debug logging
--debug-level DEBUG_LEVEL
Debug logging level [0-3] (default: 1)
-x EXCLUDE [EXCLUDE ...], --exclude EXCLUDE [EXCLUDE ...]
list of keys to exclude if updating entry
-n INCLUDE [INCLUDE ...], --include INCLUDE [INCLUDE ...]
list of keys to include if updating entry (mutually
exclusive to -x)
--ignore-field-prefixes [IGNORE_FIELD_PREFIXES [IGNORE_FIELD_PREFIXES ...]]
list of fields (in whois data) to ignore when
extracting and inserting into ElasticSearch
-e EXTENSION, --extension EXTENSION
When scanning for CSV files only parse files with
given extension (default: csv)
-v, --verbose Be verbose
-s, --stats Print out Stats after running
-r, --redo Attempt to re-import a failed import or import more
data, uses stored metadata from previous run
--config-template-only
Configure the ElasticSearch template and then exit
--clear-interrupted-flag
Clear the interrupted flag, forcefully (NOT
RECOMMENDED)
-f INGEST_FILE, --file INGEST_FILE
Input CSV file
-d INGEST_DIRECTORY, --directory INGEST_DIRECTORY
Directory to recursively search for CSV files --
mutually exclusive to '-f' option
-D INGEST_DAY, --ingest-day INGEST_DAY
Day to use for metadata, in the format 'YYYY-MM-dd',
e.g., '2021-01-01'. Defaults to todays date, use
'YYYY-MM-00' to indicate a quarterly ingest, e.g.,
2021-04-00
-o COMMENT, --comment COMMENT
Comment to store with metadata
Performance Options:
--pipelines PIPELINES
Number of pipelines (default: 2)
--shipper-threads SHIPPER_THREADS
How many threads per pipeline to spawn to send bulk ES
messages. The larger your cluster, the more you can
increase this, defaults to 1
--fetcher-threads FETCHER_THREADS
How many threads to spawn to search ES. The larger
your cluster, the more you can increase this, defaults
to 2
--bulk-ship-size BULK_SHIP_SIZE
Size of Bulk Elasticsearch Requests (default: 10)
--bulk-fetch-size BULK_FETCH_SIZE
Number of documents to search for at a time (default:
50), note that this will be multiplied by the number
of indices you have, e.g., if you have 10
pydat-<number> indices it results in a request for 500
documents
Elasticsearch Options:
-u [ES_URI [ES_URI ...]], --es-uri [ES_URI [ES_URI ...]]
Location(s) of ElasticSearch Server (e.g.,
foo.server.com:9200) Can take multiple endpoints
--es-user ES_USER Username for ElasticSearch when Basic Auth is enabled
--es-pass ES_PASSWORD
Password for ElasticSearch when Basic Auth is enabled
--cacert ES_CA_CERT Path to a CA Certicate bundle to enable https support
--es-disable-sniffing
Disable ES sniffing, useful when ssl
hostnameverification is not working properly
-p ES_INDEX_PREFIX, --index-prefix ES_INDEX_PREFIX
Index prefix to use in ElasticSearch (default: pydat)
--rollover-size ES_ROLLOVER_DOCS
Set the number of documents after which point a new
index should be created, defaults to 50 million, note
that this is fuzzy since the index count isn't
continuously updated, so should be reasonably below 2
billion per ES shard and should take your ES
configuration into consideration
--ask-pass Prompt for ElasticSearch password
Обратите внимание, что при добавлении новой версии данных в базу данных вам следует использовать либо флаг -x для исключения определенных полей, которые не важны для отслеживания изменений, либо флаг -n для включения конкретных полей, подлежащих проверке. Это значительно уменьшит объем данных, хранящихся между версиями. Вы можете использовать только либо -x, либо -n, но не оба одновременно, вы можете выбрать то, что лучше подходит для вашего окружения. Например, если вы получаете ежедневные обновления, вы можете решить, что для ежедневных обновлений вас интересует только изменение contactEmail, но каждый квартал вы можете, наоборот, исключить только некоторые поля, которые не считаете важными.
Чтобы сэкономить время при повторяющемся использовании флагов, pydat-populator принимает файл конфигурации. Посмотрите пример конфигурации для примера создания файла конфигурации.
pyDat сам по себе не предоставляет никаких данных. Вы должны предоставить свои собственные whois-данные в хранилище данных ElasticSearch.
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 для интерактивного веб-интерфейса. Самый простой способ использовать приложение — собрать образ 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, но сохраняет набор конечных точек API v1, чтобы приблизить вывод, который возвращался из 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
Эта конечная точка принимает 4 параметра через GET-запрос:
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, # Optional
chunk_size: 50, # Optional
offset: 0 # Optional
}
api/v2/query [POST]
Эта конечная точка поддерживает возможность 'расширенного' синтаксиса запросов. Она ожидает JSON-запрос следующего вида:
{
query: "myquery",
chunk_size: 50, # Optional
offset: 0, #Optional
unique: false, # Optional
sort_keys: [ # Optional
"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.
Вы должны были получить копию Стандартной общественной лицензии GNU вместе с pyDat. Если нет, см. http://www.gnu.org/licenses/.
Одобрено для публичного выпуска; распространение без ограничений 14-1633