Hybrid Analysis バッチサブミッションスクリプト

このPythonスクリプトは、フォルダを再帰的にスキャンし、実行可能ファイル、スクリプト、ドキュメント、およびその他の関連ファイルを Hybrid Analysis (Falcon Sandbox) に送信して、自動マルウェア解析を行います。

機能

• ディレクトリを再帰的に走査
• サポートされているファイルタイプのみを送信（以下のリストを参照）
• 空のファイル、サイズ超過ファイル、以前に送信済みのファイルをスキップ
• パストラバーサル攻撃を防止 – ファイルがスキャンルート内にあることを確認
• シンボリックリンクをスキップして重複や意図しない送信を回避
• 効率的なAPI通信のために永続的な requests Session を使用
• キャッシュを専用ユーザーディレクトリ (~/.hybrid_analysis_submitter/) に保存し、スキャン対象フォルダを汚染しないようにする
• ローカルSHA-256キャッシュを使用して重複送信を防止
• APIレート制限（429エラー）を適切に処理
• APIクォータが尽きたときに自動停止
• フォルダ、ファイルサイズ制限、環境ID、キャッシュファイル名のコマンドライン設定をサポート
• セキュリティのため、.envファイルからAPIキーを読み取り

必要条件

• Python 3.6+
• 有効な Hybrid Analysis APIキー (無料ティアあり)

インストール

1. このスクリプトをクローンまたはダウンロードしてローカルマシンに配置します。

2. 必要なパッケージをインストール:

pip install requests python-dotenv

3. .envファイルを作成し、スクリプトと同じディレクトリに配置し、APIキーを記入します:

HYBRID_API_KEY=your_api_key_here

APIキーは Hybrid Analysis に登録して取得できます。

使用方法

コマンドラインからスクリプトを実行し、スキャンするフォルダを指定します:

python submit_to_hybrid.py /path/to/folder

コマンドライン引数

例

デフォルト設定でフォルダをスキャン:

python submit_to_hybrid.py C:\suspicious_files

フォルダをスキャンし、サイズ上限を200MBに増やし、別の環境（例: Android）を使用:

python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

カスタムキャッシュファイル名を使用:

python submit_to_hybrid.py ./malware --cache-file my_cache.json

出力例

Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

サポートされているファイルタイプ

• Windows実行可能ファイル (PE): .exe, .scr, .pif, .dll, .com, .cpl
• インストーラ＆パッケージ: .msi
• Windowsスクリプト: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

すべてのサポートされているファイルタイプの公式リストについては、Hybrid Analysis FAQ を確認してください。

動作の仕組み

1. 再帰的な走査 – スクリプトは os.walk() を使用してすべてのサブフォルダを走査します。
2. セキュリティチェック – 各ファイルがスキャンルート内のパスに解決されることを確認し（パストラバーサルを防止）、シンボリックリンクをスキップします。
3. ファイルフィルタリング – ファイル拡張子、サイズ（0バイトまたは --max-file-size を超えるものはスキップ）、および以前に送信されたかどうか（SHA-256キャッシュ）をチェックします。
4. 送信 – 各ファイルは、APIキーを使用した永続的な requests Session を使用して https://hybrid-analysis.com/api/v2/submit/file エンドポイントにアップロードされます。
5. レート制限 – 各送信後、スクリプトは2秒間スリープします。HTTP 429（Too Many Requests）応答を受信した場合、エラーをカウントします。連続3回の429エラーが発生すると、スキャンは自動的に停止します。
6. キャッシュの永続化 – 正常に送信されたファイルは、~/.hybrid_analysis_submitter/ 内のJSONキャッシュファイルに保存され、将来の実行で再送信されないようにします。キャッシュは人間が読みやすいようにソートされて保存されます。

レート制限とクォータ

• Hybrid Analysisの無料アカウントには、時間/日あたりの送信制限があります。
• スクリプトはHTTP 429応答を検出し、3回のエラー後に停止して無限リトライを回避します。
• APIに配慮するため、送信間に2秒の遅延が追加されます。

重要な注意事項

• APIキーは .envファイルからのみ読み取られます – ハードコードしないでください。
• 空のファイル（0バイト）は常にスキップされます。
• --max-file-size より大きいファイルはスキップされます。
• ALLOWED_EXTENSIONS に含まれる拡張子のファイルのみが送信されます。
• シンボリックリンクはスキップされ、重複送信やパスの混乱を防ぎます。
• パストラバーサルは防止されます – 指定されたスキャンディレクトリの外に解決されるファイルはスキップされます。
• キャッシュにより、複数回の実行間での同一ファイルの再送信が防止され、ユーザーディレクトリ（~/.hybrid_analysis_submitter/）に保存されます。
• スクリプトは各HTTPリクエストに120秒のタイムアウトを使用します。
• キャッシュファイルは専用ディレクトリに保存され、スキャンコンテンツと混ざりません。

トラブルシューティング

ライセンス

このスクリプトは、教育およびセキュリティ分析目的で現状のまま提供されます。責任を持って使用し、Hybrid Analysisの利用規約に従ってください。

免責事項

ファイルを第三者サンドボックスに送信すると、機密性の高いコンテンツが露出する可能性があります。アップロードする前に、ファイルを共有する権利があることを確認してください。