malware-analysis

目的

このスキルを使用すると、OpenClawは提供されたサンプルに対してマルウェア分析を実行できます。バイナリの逆アセンブルやシグネチャ照合などの静的手法と、サンドボックスでの実行や挙動の監視などの動的手法を用いて、脅威を検出し、侵害の痕跡（IOC）を抽出して、レポートを生成します。

使用する場面

不審なファイルへのインシデント対応、ゼロデイマルウェアの特定を目的とした脅威ハンティング、またはマルウェアの挙動を把握するためのリバースエンジニアリングのワークフローで、このスキルを使用してください。ファイルハッシュ、バイナリサンプル、またはネットワークキャプチャがあり、IDA ProやVolatilityなどの手動ツールを使わずに自動分析したい場合に適用します。

主な機能

• 静的解析：PE/ELFファイルを解析し、文字列を抽出して、YARAルールと照合し、シグネチャを確認します。
• 動的解析：隔離されたVMでサンプルを実行し、API呼び出し（Windows APIフックなどを使用）を監視して、永続化の仕組みを検出します。
• 脅威レポート：IPアドレス、ドメイン、レジストリキーなどのIOCを含むJSONレポートを出力します。
• 外部フィードとの連携：VirusTotalなどにAPI経由で問い合わせて、情報を照合します。
• カスタムルールのサポート：ユーザー定義のYARAルールをファイルから読み込み、対象を絞った検出を行います。

使用パターン

OpenClawのCLIまたはAPIからこのスキルを呼び出します。必ず、$MALWARE_API_KEY環境変数を使用して認証してください。CLIでは、必須フラグを指定して「analyze」などのサブコマンドを使用します。コードではOpenClaw SDKをインポートし、パラメーターを指定してメソッドを呼び出します。使用例：ファイルを読み込み、分析タイプを指定して、非同期の結果を処理します。ファイル形式が原因で分析に失敗した場合は、メタデータの抽出にフォールバックします。

主なコマンド/API

簡単なタスクにはOpenClaw CLIを使用します。

• コマンド：oc malware analyze --file /path/to/sample.exe --type static --yara-rules rules.yar
  • フラグ：--file（必須、サンプルへのパス）、--type（staticまたはdynamic）、--yara-rules（任意、YARAファイルへのパス）。
• コマンド：oc malware dynamic --file sample.zip --timeout 300 --output report.json
  • フラグ：--timeout（秒単位。例：5分の場合は300）、--output（JSONレポートの出力先）。

API連携の場合：

• エンドポイント：POST /api/malware/analyze
  • 本文：{ "file": "base64encoded_sample", "type": "dynamic", "rules": ["rule1", "rule2"] }のようなJSON
  • ヘッダー：Authorization: Bearer $MALWARE_API_KEY
  • レスポンス：{ "ioc": ["192.168.1.1"], "behavior": "network exfiltration" }のようなキーを含むJSON

SDK（Python）の使用例：

import openclaw
client = openclaw.Client(api_key=os.environ['MALWARE_API_KEY'])
result = client.analyze(file_path='sample.exe', analysis_type='static')
print(result['threats'])  # Output: list of detected threats

カスタム設定用の構成形式（config.yamlなどのYAMLファイル）：

apiKey: $MALWARE_API_KEY
sandbox:
  url: https://sandbox.openclaw.ai
  timeout: 600
yaraRules: /path/to/rules.yar

連携に関する注意事項

エージェントのスクリプトにモジュールとして追加し、このスキルをOpenClawのワークフローに組み込みます。実行前に、環境で$MALWARE_API_KEYを設定してください。たとえば、大規模なブルーチームのパイプラインでは、出力（検出した文字列を逆コンパイラーに渡すなど）を引き渡して、「reverse-engineering」スキルと連携させます。SDKのイベントフックを使用すると、次のようにリアルタイムで更新を受け取れます。

client.on_analysis_complete(lambda data: process_iocs(data['ioc']))

OpenClawのバージョン>=2.5との互換性を確保してください。外部ツールを使用する場合は、出力をこのスキルのJSON形式にマッピングします（例：{ "file_hash": "sha256_value" }）。

エラー処理

無効なファイル形式やAPIエラーなどの一般的なエラーを捕捉できるよう、呼び出しは必ずtry-exceptブロックで囲んでください。CLIの場合：終了コードを確認します（例：認証エラーの場合はコード1）。APIの場合：HTTPレスポンスを解析します（例：$MALWARE_API_KEYがない場合は401、不正な形式の入力の場合は400）。例：

try:
    result = client.analyze(file_path='invalid.file', type='static')
except openclaw.AuthError as e:
    print(f"Auth failed: {e} — Ensure $MALWARE_API_KEY is set")
except openclaw.FileError as e:
    fallback_to_hash_analysis(e.file_path)  # Custom function for metadata only

エラーコードなどの詳細とともにエラーを記録し、一時的な問題（ネットワークエラーなど）が発生した場合は、指数バックオフを使用して最大3回まで再試行します。

具体的な使用例

1. PE ファイルの静的解析：埋め込まれた文字列やシグネチャを調べるために Windows 実行ファイルを解析するには、次のコマンドを実行します：oc malware analyze --file suspicious.exe --type static --yara-rules default.yar。これにより、"cmd.exe" などの文字列や "Trojan.Downloader" などの脅威を含む JSON レポートが出力されます。コードでは、SDK を使用してレポートを処理し、IOC が既知の脅威と一致した場合にアラートを発します。

2. スクリプトの動的解析：スクリプトベースのマルウェアの可能性を行動面から解析するには、次を実行します：oc malware dynamic --file script.py --timeout 120 --output results.json。これにより、スクリプトがサンドボックス内で実行され、外部への接続が監視され、"connects to 1.2.3.4" のような動作が記録されます。ワークフローで results.json を解析して IP アドレスをブロックすることで連携できます。

グラフの関係

• 関連先：ブルーチームクラスター（例：侵入検知スキルとデータを共有）。
• リンク先：リバースエンジニアリング（ファイルハッシュを入力）、サイバーセキュリティ（脅威インテリジェンスツールに出力）。
• 依存先：認証サービス（$MALWARE_API_KEY 経由）。
• 接続経路：データフロー用の OpenClaw API エンドポイント。