restfulHarvest: theHarvesterをAPIで使いこなす 🕵️‍♀️

OSINTツールtheHarvesterの強力な機能をRESTful API経由で利用する方法

はじめに：theHarvesterとrestfulHarvestとは？

現代のサイバーセキュリティにおいて、情報収集は非常に重要なプロセスです。特に、攻撃対象の外部脅威ランドスケープを理解するためのオープンソースインテリジェンス（OSINT）は、ペネトレーションテストやレッドチーム演習の初期段階で不可欠となります。

theHarvester は、まさにこのOSINT収集を目的とした強力なツールです。Edge-Securityチームによって開発され、Pythonで書かれたこのツールは、ドメインに関連する電子メールアドレス、サブドメイン、IPアドレス、従業員名などの情報を、検索エンジンやPGPキーサーバー、その他の公開されている様々なソースから収集します。2021年4月頃には既に多くのデータソースに対応しており、現在も活発に開発が続けられています。

theHarvesterは非常に多機能ですが、基本的にはコマンドラインインターフェース（CLI）ツールとして利用されます。しかし、自動化されたワークフローや他のツールとの連携を考えると、プログラム経由でtheHarvesterの機能を利用したいというニーズが出てきます。

そこで登場するのが restfulHarvest です。これはtheHarvesterに同梱されているツールで、theHarvesterの機能をRESTful APIサーバーとして公開します。これにより、HTTPリクエストを通じてtheHarvesterの機能を利用できるようになり、スクリプトからの呼び出しや他のアプリケーションへの組み込みが格段に容易になります。🎉

この記事では、restfulHarvestの基本的な使い方から、APIを利用した情報収集の方法までを詳しく解説していきます。

restfulHarvestの機能と利点

restfulHarvestは、theHarvesterのコア機能をラップし、シンプルなWeb APIとして提供します。主な機能と利点は以下の通りです。

プログラムからのアクセス: Pythonスクリプト、シェルスクリプト、その他のプログラミング言語からHTTPリクエストを送るだけで、theHarvesterのスキャンを実行できます。
自動化の促進: 定期的なドメイン監視や、セキュリティインシデント対応の自動化フローに組み込むことが容易になります。
柔軟な連携: SIEM、SOARプラットフォーム、カスタムダッシュボードなど、他のセキュリティツールやシステムと連携させやすくなります。
リモート実行: 別のマシンでrestfulHarvestサーバーを実行し、ネットワーク経由でtheHarvesterの機能を利用することも可能です（セキュリティ設定に注意が必要です）。

基本的に、theHarvesterがCLIでできる情報収集タスク（指定したドメインに対するサブドメイン検索、メールアドレス収集など）を、API経由で指示し、結果をJSON形式などで受け取ることができます。

前提条件とインストール

restfulHarvestを利用するための前提条件は、基本的にtheHarvesterが正しくインストールされ、動作することです。

theHarvesterのインストール:
- Kali Linux: theHarvesterはKali Linuxの多くのエディション（default, large, everything, headlessなど）にデフォルトで含まれています。もしインストールされていない場合や最新版にしたい場合は、以下のコマンドでインストール/アップデートできます。
```
sudo apt update && sudo apt install theharvester
```
- 他のLinuxディストリビューションやmacOS: Python (3.11以上推奨) とpipがインストールされている環境が必要です。GitHubリポジトリからクローンしてインストールするのが一般的です。
```
git clone https://github.com/laramies/theHarvester.git
cd theHarvester
python3 -m venv theHarvester-env
source theHarvester-env/bin/activate
pip install -r requirements.txt
```
  Homebrew (macOS) でもインストール可能です: `brew install theharvester`
- Docker: Dockerイメージも提供されています。`docker run -it –rm secsi/restfulharvest` のようなコマンドで直接restfulHarvestを実行することも可能です。
Python環境: theHarvesterおよびrestfulHarvestはPythonで書かれています。依存関係（`python3-fastapi`, `python3-uvicorn` など多数）が正しくインストールされている必要があります。`apt`や`pip`でのインストール時に通常は自動で解決されます。
APIキー（オプション）: theHarvesterは多くの情報ソースを利用しますが、一部のソース（Bing API, GitHub, Shodan, Censys, SecurityTrailsなど）はAPIキーの設定が必要です。APIキーを使用することで、より多くの情報を取得できたり、レートリミットを緩和できたりします。APIキーは `api-keys.yaml` ファイル（通常は `~/.theHarvester/` やリポジトリ直下）に設定します。restfulHarvest経由でこれらのソースを利用する場合も、同様にAPIキーの設定が必要です。設定方法の詳細はtheHarvesterのWikiを参照してください。

⚠️ 注意: restfulHarvest自体はtheHarvesterパッケージに含まれる実行ファイル（またはスクリプト）なので、theHarvesterがインストールされていれば、通常は追加のインストール作業は不要です。

restfulHarvestサーバーの起動 🚀

restfulHarvestサーバーを起動するのは非常に簡単です。ターミナルを開き、以下のコマンドを実行します。

restfulHarvest

デフォルトでは、サーバーはローカルホスト（`127.0.0.1`）のポート `5000` で起動します。

INFO:     Uvicorn running on http://127.0.0.1:5000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxxxx] using StatReload
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

いくつかのオプションを指定して起動することも可能です。ヘルプメッセージ (`restfulHarvest -h`) で確認できます。

restfulHarvest -h

usage: restfulHarvest [-h] [-H HOST] [-p PORT] [-l LOG_LEVEL] [-r]

options:
  -h, --help            show this help message and exit
  -H HOST, --host HOST  IP address to listen on default is 127.0.0.1
  -p PORT, --port PORT  Port to bind the web server to, default is 5000
  -l LOG_LEVEL, --log-level LOG_LEVEL
                        Set logging level, default is info but
                        [critical|error|warning|info|debug|trace] can be set
  -r, --reload          Enable automatic reload used during development of the
                        api.

例えば、特定のIPアドレス（例: `192.168.1.100`）とポート `8080` で起動したい場合は、以下のようにします。

restfulHarvest -H 192.168.1.100 -p 8080

🛑 セキュリティ警告: サーバーを `0.0.0.0` や外部からアクセス可能なIPアドレスで公開する場合、適切なファイアウォール設定や認証メカニズムを導入しないと、誰でもAPIにアクセスできてしまう可能性があります。開発やテスト目的以外では、localhost (`127.0.0.1`) での利用を推奨します。

APIの使い方 📡

restfulHarvestサーバーが起動したら、HTTPリクエストを送ることでtheHarvesterの機能を利用できます。APIはFastAPIフレームワークをベースに構築されており、Swagger UIによるインタラクティブなドキュメントも提供されています。

APIドキュメントへのアクセス

サーバー起動後、Webブラウザで `http://<サーバーIP>:<ポート>/docs` にアクセスすると、Swagger UIが表示されます。デフォルト設定（localhost:5000）の場合は `http://127.0.0.1:5000/docs` です。

このUI上で、利用可能なAPIエンドポイントの一覧、各エンドポイントが受け付けるパラメータ、リクエスト/レスポンスの形式などを確認できます。また、UIから直接APIを試すことも可能です。これはAPIの動作を理解するのに非常に役立ちます。👍

主要なAPIエンドポイント

restfulHarvestのAPIの中心となるのは、theHarvesterのスキャンを開始するためのエンドポイントです。バージョンや実装によって若干異なる可能性はありますが、一般的には以下のようなエンドポイントが提供されます。

スキャン開始 (例: POST /api/v1/scan または POST /scan):
- このエンドポイントに対してPOSTリクエストを送ることで、新しいスキャンタスクを開始します。
- リクエストボディ（通常はJSON形式）で、ターゲットドメイン (`domain`) や使用するデータソース (`sources`) などを指定します。
- レスポンスとして、スキャン結果そのもの、またはスキャン状況を確認するためのタスクIDなどが返される場合があります（非同期処理の場合）。
結果取得 (例: GET /api/v1/results/{task_id} または設計による):
- 非同期でスキャンが実行される場合、この種のエンドポイントでスキャン結果を取得します。
- スキャン開始時に返されたタスクIDなどを使って、特定のスキャンの結果（発見されたメールアドレス、ホスト名、IPアドレスなど）を問い合わせます。

正確なエンドポイント名やパスは、起動したサーバーの `/docs` で確認するのが最も確実です。

API利用例 (`curl` を使用)

ここでは、コマンドラインツールの `curl` を使ってAPIを利用する例を示します。サーバーが `http://127.0.0.1:5000` で動作していると仮定します。

例1: `example.com` ドメインを `google` と `bing` ソースでスキャンする

`/docs` を確認し、スキャン開始エンドポイントが POST /api/v1/scan で、以下のようなJSONボディを受け付けるとします。

{
  "domain": "example.com",
  "sources": "google,bing",
  "limit": 500
}

この場合、`curl` コマンドは以下のようになります。

curl -X POST http://127.0.0.1:5000/api/v1/scan \
-H "Content-Type: application/json" \
-d '{
  "domain": "example.com",
  "sources": "google,bing",
  "limit": 500
}'

上記のコマンドは、指定されたエンドポイントにPOSTリクエストを送信します。-H オプションでリクエストヘッダー（ここでは `Content-Type`）を指定し、-d オプションでリクエストボディ（JSONデータ）を指定しています。

サーバーからのレスポンスは、APIの設計によります。直接結果が返ってくるか、あるいはタスクIDなどが返され、別途結果取得のエンドポイントを叩く必要があるかもしれません。

API利用例 (Python `requests` ライブラリを使用)

PythonスクリプトからAPIを利用する場合は、requests ライブラリを使うのが便利です。

import requests
import json

# restfulHarvestサーバーのアドレス
api_endpoint = "http://127.0.0.1:5000/api/v1/scan" # 実際の/docsで確認したエンドポイントに置き換えてください

# スキャンパラメータ
scan_data = {
    "domain": "example.com",
    "sources": "duckduckgo,linkedin", # 利用可能なソースを指定
    "limit": 200
}

headers = {
    "Content-Type": "application/json"
}

try:
    # POSTリクエストを送信
    response = requests.post(api_endpoint, headers=headers, json=scan_data)
    response.raise_for_status() # HTTPエラーがあれば例外を発生させる (e.g., 4xx, 5xx)

    # レスポンスをJSONとして解析
    results = response.json()

    # 結果を表示 (レスポンスの形式はAPI設計によります)
    print(json.dumps(results, indent=2, ensure_ascii=False))

except requests.exceptions.RequestException as e:
    print(f"APIリクエスト中にエラーが発生しました: {e}")
except json.JSONDecodeError:
    print(f"APIレスポンスのJSON解析に失敗しました: {response.text}")

このPythonスクリプトは、指定されたドメインとソースでスキャンを実行し、サーバーからのレスポンス（スキャン結果やタスク情報など）をJSON形式で受け取り、整形して表示します。エラーハンドリングも含まれています。

利用可能なデータソース（`-b` オプションで指定するもの）は、theHarvester本体のヘルプ (`theHarvester -h`) や、GitHubリポジトリのドキュメントで確認できます。代表的なものには `baidu`, `bing`, `binaryedge`, `bufferoverun`, `censys`, `crtsh`, `duckduckgo`, `github-code`, `google`, `hunter`, `intelx`, `linkedin`, `netlas`, `securityTrails`, `shodan`, `virustotal`, `zoomeye` などがあります。一部はAPIキーが必要です。🔑

実践的な利用シナリオ 💡

restfulHarvestは、以下のようなシナリオで特に役立ちます。

自動ドメイン監視: 定期的に自社ドメインや監視対象ドメインに対してtheHarvesterスキャンを実行し、新たに公開されたサブドメインやメールアドレスを検出するスクリプトを作成する。
カスタムOSINTツールの開発: 他のOSINTツールや独自の情報ソースと組み合わせて、より包括的な情報収集ツールを構築する際のバックエンドとして利用する。
セキュリティ運用への統合: 新しいサブドメインが発見された場合にアラートを生成したり、発見されたメールアドレスをフィッシング訓練の対象リストに追加したりするなど、セキュリティ運用プロセス（SecOps）に組み込む。
ペネトレーションテストの効率化: テスト対象のドメイン情報をプログラム経由で迅速に収集し、レポート作成や次の攻撃フェーズの準備に利用する。

API経由で利用できることで、手動でのコマンド実行と比較して、再現性、拡張性、統合性が大幅に向上します。

注意点とセキュリティ

restfulHarvestを利用する際には、以下の点に注意が必要です。

APIキーの管理: theHarvesterが利用する外部サービスのAPIキーは、api-keys.yaml ファイルで管理されます。このファイルが外部に漏洩しないように、適切な権限設定と管理を行ってください。
APIサーバーの公開範囲: 前述の通り、restfulHarvestサーバーを外部ネットワークに公開する場合は、認証やアクセス制御の仕組みを検討してください。FastAPI自体や、リバースプロキシ（Nginxなど）レベルでの認証設定が考えられます。
レートリミット: theHarvesterが利用する各情報ソースには、多くの場合レートリミット（利用回数制限）が存在します。API経由で頻繁にスキャンを実行すると、これらの制限に抵触する可能性があります。必要に応じてスキャン間隔を調整したり、有料プランのAPIキーを利用したりすることを検討してください。一部ソース（例: hunter）は無料プランでは結果数が制限されるため、theHarvesterの`-l`オプションに相当するパラメータをAPIで指定する必要があるかもしれません。
法的・倫理的側面: theHarvesterおよびrestfulHarvestは強力な情報収集ツールですが、その利用は常に法的および倫理的な範囲内に留める必要があります。許可なく他者のドメインに対して過度なスキャンを行うことは、利用規約違反や法的な問題を引き起こす可能性があります。必ず許可された範囲内で、責任ある利用を心がけてください。⚖️

まとめ

restfulHarvestは、強力なOSINTツールであるtheHarvesterの機能を、柔軟性の高いRESTful APIとして提供します。これにより、theHarvesterの持つ情報収集能力を、自動化されたスクリプトや他のシステムから簡単に利用できるようになります。

サーバーの起動は簡単で、APIドキュメントも提供されるため、比較的容易に利用を開始できます。`curl`やPythonの`requests`ライブラリを使えば、すぐにAPI経由での情報収集を試すことができます。

セキュリティやレートリミット、法的側面に注意しつつ、restfulHarvestを活用することで、OSINT活動やセキュリティ監視の効率化、自動化を大きく進めることができるでしょう。是非、試してみてください！🚀

参考情報

Kali Linux Tools – theHarvester: https://www.kali.org/tools/theharvester/
theHarvester GitHub Repository: https://github.com/laramies/theHarvester
theHarvester Wiki (APIキー設定など): https://github.com/laramies/theHarvester/wiki