
Pivotable Reverse WhoIs / PDNS Fusion、Registrant Tracking & Alerting を備え、さらに自動クエリ用API (JSON/CSV/TXT)
注意: PyDat 5 の開発中、内部の運用方針が変更され、PyDat プロジェクトは廃止されました。PyDat 5 の機能を完成させるための多くの作業は行われましたが、一部の機能は完全にテストされていません。
WhoDat プロジェクトは、whoisxmlapi データ、または ElasticSearch に保存されている任意の whois データのためのインターフェースです。whois データ、現在の IP 解決、パッシブ DNS を統合します。アナリストが調査を行うためのインタラクティブでピボット可能なアプリケーションを提供するだけでなく、JSON 形式での出力を可能にする API も備えています。
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 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 のいずれかのみ使用でき、両方を同時に使用することはできませんが、環境に最適な方を選択できます。 例えば、毎日更新を受け取る場合、連絡先メールアドレスが変更されたかどうかのみを気にすることに決めるかもしれませんが、四半期ごとには、重要でない特定のフィールドのみを除外したいかもしれません。
繰り返しフラグを使用する手間を省くため、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 は、REST API を提供するために Python Flask を使用し、インタラクティブな Web UI を提供するために 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 を導入していますが、Pydat 4 から返される出力に近似するために v1 の API エンドポイントセットを維持しています。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>/
ドメインエンドポイントを使用すると、特定のドメイン名に関する情報を取得できます。デフォルトでは、データベースで見つかったドメインの任意のバージョンの情報が返されます。より詳細な情報を指定して、特定のバージョンのドメイン情報を取得したり、最新のエントリを取得したりできます。また、2 つのバージョンのドメイン間の差分を取得して、変更内容を確認することもできます。
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]
このエンドポイントは、2 つのバージョンのドメイン間の差分を取得して変更内容を確認できるようにします。以下の形式の 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 との下位互換性がありません。つまり、pyDat 5 で使用するには、データを新たに ElasticSearch クラスターに取り込む必要があります。
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/ を参照してください。
Approved for Public Release; Distribution Unlimited 14-1633