exfil-scan

LLM出力やAI生成コンテンツをスキャンし、ユーザー、ログ、下流システムに届く前にデータ漏えい（exfiltration）の兆候を検出します。

1) exfil-scan が存在する理由

現代のLLMアプリケーションは、機密性の高いプロンプト、内部ドキュメント、APIレスポンス、ユーザーデータを日常的に処理します。 これにより、新たなセキュリティ境界が生まれます。それは出力レイヤーです。

EchoLeak系の攻撃（CVE-2025-32711を含む）は、隠蔽または難読化されたペイロードが生成テキストに埋め込まれ、ツール、リンク、パースチェーンを通じてデータを外部に持ち出すために利用されることを実証しました。

従来のスキャナは、ファイル、依存関係、ランタイムトラフィックに焦点を当てています。 生成されたモデル出力を専用に検査することはありません。

exfil-scan は「LLMレスポンス用ウイルススキャナ」を提供します。

• プレーンテキスト、JSON、Markdown、ログを検査します
• 疑わしい漏えいパターンを6つのクラスに分類して特定します
• 重要度と場所を添えて検出結果を報告します
• CI/CDやローカル開発者のワークフローにシームレスに統合します

2) 検出対象

3) 機能のハイライト

• 3つの感度プロファイル: low、medium、high
• YAML設定ファイルによる上書きサポート
• stdin、単一ファイル、ディレクトリからの入力
• text、json、markdown、html形式の出力
• 自動化のための安定した終了コード
• 他ツールへの組み込みに適したクリーンなPython API

4) インストール

ソースからインストール

git clone https://github.com/your-org/exfil-scan.git
cd exfil-scan
pip install -e .

標準的なpipインストール（公開時）

pip install exfil-scan

開発用インストール

pip install -e ".[dev]"
pytest

5) クイックスタート

パイプされたLLM出力をスキャン

echo 'api_key: sk-ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' | exfil-scan

単一ファイルをスキャン

exfil-scan --input output.txt

ディレクトリを再帰的にスキャン

exfil-scan --directory ./model-logs --recursive

6) CLIオプションリファレンス

注意:

• --input と --directory はどちらか一方のみ使用してください。
• パスが指定されない場合、ツールは stdin から読み取ります。
• 検出結果がある場合、プロセスは終了コード 1 で終了します。

7) 出力形式ごとの使用例

プレーンテキスト出力

exfil-scan --input suspicious.txt --format text

期待される形式:

exfil-scan report
=================
Scanned targets: 1
Total findings: 2

1. [HIGH] metadata_leaks/known_token_format:openai_key
   Location: suspicious.txt:1:10
   Description: Matched known credential/token format (openai_key).

JSON出力

exfil-scan --input suspicious.txt --format json

期待される構造:

{
  "finding_count": 2,
  "scanned_targets": ["suspicious.txt"],
  "findings": [
    {
      "category": "metadata_leaks",
      "rule": "known_token_format:openai_key",
      "severity": "HIGH",
      "description": "Matched known credential/token format (openai_key).",
      "location": "suspicious.txt:1:10",
      "snippet": "..."
    }
  ]
}

HTML出力

exfil-scan --directory ./outputs --recursive --format html --output report.html

期待される動作:

• 検出結果テーブルを含むスタンドアロンHTMLページを生成
• 安全にレンダリングするためコンテンツをエスケープ
• 重要度、カテゴリ、ルール、場所、説明を含む

Markdown出力

exfil-scan --input suspicious.txt --format markdown --output report.md

期待される形式:

# exfil-scan Report

- Scanned targets: 1
- Total findings: 2

8) 設定と感度

リポジトリには default-config.yaml が同梱されています。--config で独自のファイルを指定できます。

感度のチューニング:

• low: 誤検知が少なく、しきい値が大きい
• medium: バランスの取れたデフォルト
• high: より微妙なパターンを検出

CLIでの感度上書き:

exfil-scan --input out.txt --sensitivity high

9) カスタムパターンとポリシーチューニング

独自のトークン形式やメタデータキーを追加できます:

sensitivity: medium
rules:
  metadata_keys:
    - api_key
    - db_password
    - internal_token
  token_patterns:
    custom_jwt: "\\beyJ[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\b"
    corp_secret: "\\bcorp_[A-Za-z0-9]{24,}\\b"

その後、次のように実行します:

exfil-scan --input response.log --config ./my-config.yaml

10) アーキテクチャ概要

モジュールの責務:

• exfil_scan/cli.py: 引数解析、入力選択、出力レンダリング、終了処理
• exfil_scan/config.py: デフォルト値、YAML読み込み、再帰的マージ、プロファイル正規化
• exfil_scan/scanner.py: 6つの検出エンジン、検出結果データクラス、レポート整形
• tests/test_scan.py: 検出および出力形式の回帰テスト

実行フロー:

1. CLIが引数を解析します。
2. 設定がデフォルト値とオプションの上書きを読み込みます。
3. スキャナがstdin/ファイル/ディレクトリからテキストを読み取ります。
4. 有効な各カテゴリが独立して実行されます。
5. 検出結果は重要度順に並べられ、レンダリングされます。
6. 終了コードが自動化向けに合格/不合格/エラーを伝えます。

11) 終了コード

これによりCI統合が簡単になります:

exfil-scan --directory ./artifacts --recursive --format json --output exfil-report.json

何らかの検出があった場合、終了コード 1 に基づいてジョブを即座に失敗させることができます。

12) テスト

テストを実行:

pytest

テストカバレッジには以下が含まれます:

• 6つの検出カテゴリすべて
• 4つの出力モードすべてにおけるレポート整形
• 安定した動作のためのルールレベルのアサーション

13) セキュリティに関する注意事項

exfil-scan はヒューリスティックスキャナです。 コンテンツの安全性を証明するのではなく、リスクを低減し、不審な出力を可視化することを目的としています。

推奨される導入パターン:

1. CI上でテストプロンプトとフィクスチャ出力に対してスキャナを実行する
2. 生成されたレスポンスに対して本番ガードレールでスキャナを実行する
3. 検出結果をアナリストのトリアージとテレメトリに送る
4. 誤検知のレビューに基づいて設定しきい値を継続的に調整する

14) ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。 完全な条件については LICENSE を参照してください。

15) 貢献

貢献は歓迎します。 PRを開く際は、以下を含めてください:

• 明確な再現手順
• 期待される動作と実際の動作
• 新しい検出ロジックのテスト
• 新しいルールを導入する際のドキュメント更新