YaraFlux MCP Server

YaraFlux MCP Server

YARA ルールを使用したファイル解析機能を LLM に提供する、YARA スキャン用の Model Context Protocol（MCP）サーバーです。

📋 概要

YaraFlux MCP Server を使用すると、AI アシスタントは標準化された Model Context Protocol インターフェースを通じて、YARA ルールベースの脅威分析を実行できます。このサーバーは YARA スキャンを最新の AI アシスタントと統合し、モジュール式アーキテクチャを通じて、包括的なルール管理、安全なスキャン、詳細な結果分析をサポートします。

🧩 アーキテクチャの概要

+------------------------------------------+
|              AI Assistant                |
+--------------------+---------------------+
                    |
                    | Model Context Protocol
                    |
+--------------------v---------------------+
|              YaraFlux MCP Server         |
|                                          |
|  +----------------+    +---------------+ |
|  | MCP Server     |    | Tool Registry | |
|  +-------+--------+    +-------+-------+ |
|          |                     |         |
|  +-------v--------+    +-------v-------+ |
|  | YARA Service   |    | Storage Layer | |
|  +----------------+    +---------------+ |
|                                          |
+------------------------------------------+
          |                   |
 +-----------------+  +---------------+
 | YARA Engine     |  | Storage       |
 | - Rule Compiling|  | - Local FS    |
 | - File Scanning |  | - MinIO/S3    |
 +-----------------+  +---------------+

YaraFlux は、以下の役割を分離したモジュール式アーキテクチャを採用しています。

• MCP 統合レイヤー：AI アシスタントとの通信を処理します
• ツール実装レイヤー：YARA スキャンおよび管理機能を実装します
• ストレージ抽象化レイヤー：柔軟なストレージオプションを提供します
• YARA エンジン統合：YARA を利用してスキャンとルール管理を行います

アーキテクチャ図の詳細については、アーキテクチャのドキュメントをご覧ください。

✨ 機能

• 🔄 モジュール式アーキテクチャ

  • MCP 統合、ツール実装、ストレージを明確に分離
  • 標準化されたパラメーター解析とエラー処理
  • ローカルおよび S3/MinIO に対応した柔軟なストレージバックエンド

• 🤖 MCP 統合

  • 包括的な機能を提供する 19 個の統合済み MCP ツール
  • Claude Desktop との統合に最適化
  • 会話内から直接ファイルを解析
  • 最新の MCP プロトコル仕様に対応

• 🔍 YARA スキャン

  • URL およびファイルコンテンツのスキャン
  • コンテキストを含む詳細な一致情報
  • スキャン結果の保存と取得
  • パフォーマンスを最適化したスキャンエンジン

• 📝 ルール管理

  • YARA ルールの作成、読み取り、更新、削除
  • 詳細なエラー報告を伴うルール検証
  • ThreatFlux リポジトリからルールをインポート
  • ソース別（カスタムまたはコミュニティ）に分類

• 📊 ファイル解析

  • バイナリ解析用の 16 進数表示
  • 設定可能なパラメーターによる文字列抽出
  • ファイルのメタデータとハッシュ情報
  • 安全なファイルのアップロードと保存

• 🔐 セキュリティ機能

  • API アクセス用の JWT 認証
  • 非 root コンテナーでの実行
  • 安全に分離されたストレージ
  • 設定可能なアクセス制御

🚀 クイックスタート

Docker イメージを使用

# Pull the latest Docker image
docker pull threatflux/yaraflux-mcp-server:latest
# Run the container
docker run -p 8000:8000 \
  -e JWT_SECRET_KEY=your-secret-key \
  -e ADMIN_PASSWORD=your-admin-password \
  -e DEBUG=true \
  threatflux/yaraflux-mcp-server:latest
### Using Docker building from source

```bash
# Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/

# Build the Docker image
docker build -t yaraflux-mcp-server:latest .

# Run the container
docker run -p 8000:8000 \
  -e JWT_SECRET_KEY=your-secret-key \
  -e ADMIN_PASSWORD=your-admin-password \
  -e DEBUG=true \
  yaraflux-mcp-server:latest

ソースからインストール

# Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/

# Install dependencies (requires Python 3.13+)
make install

# Run the server
make run

依存関係のロック

Docker イメージと CI の脆弱性スキャンでは、pyproject.toml をもとにコンパイルしたハッシュ固定のロックファイルである requirements-lock.txt と requirements-dev-lock.txt からインストールします（requirements.txt の制約を適用します）。依存関係の唯一の信頼できる情報源は pyproject.toml です。実行時の依存関係は dependencies、開発用の依存関係は dev エクストラに定義します（pip install -e ".[dev]"）。そこまたは requirements.txt の依存関係を変更したら、ロックファイルを再生成してください。

make lock-requirements

変更を加える際は、更新したロックファイルもコミットしてください。ロックファイルと pyproject.toml の内容にずれがあると、CI は失敗します。

🧩 Claude Desktop との統合

YaraFlux は、Model Context Protocol を介して Claude Desktop とシームレスに統合できるよう設計されています。

1. Docker イメージをビルドします。

docker build -t yaraflux-mcp-server:latest .

2. Claude Desktop の設定に追加します（~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "yaraflux-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env",
        "JWT_SECRET_KEY=your-secret-key",
        "--env",
        "ADMIN_PASSWORD=your-admin-password",
        "--env",
        "DEBUG=true",
        "--env",
        "PYTHONUNBUFFERED=1",
        "threatflux/yaraflux-mcp-server:latest"
      ],
      "disabled": false,
      "autoApprove": [
        "scan_url",
        "scan_data",
        "list_yara_rules",
        "get_yara_rule"
      ]
    }
  }
}

3. Claude Desktop を再起動して、サーバーを有効にします。

🛠️ 利用可能な MCP ツール

YaraFlux は、19 個の統合 MCP ツールを公開しています。

ルール管理ツール

• list_yara_rules: フィルタリングオプションを指定して、利用可能な YARA ルールを一覧表示します
• get_yara_rule: 指定した YARA ルールの内容とメタデータを取得します
• validate_yara_rule: 詳細なエラー情報を表示して、YARA ルールの構文を検証します
• add_yara_rule: 新しい YARA ルールを作成します
• update_yara_rule: 既存の YARA ルールを更新します
• delete_yara_rule: YARA ルールを削除します
• import_threatflux_rules: ThreatFlux GitHub リポジトリからルールをインポートします

スキャンツール

• scan_url: 指定した YARA ルールを使用して、URL のコンテンツをスキャンします
• scan_data: 指定したルールを使用して、入力データ（base64 エンコード）をスキャンします
• get_scan_result: 以前のスキャン結果の詳細を取得します

ファイル管理ツール

• upload_file: 解析またはスキャン用のファイルをアップロードします
• get_file_info: アップロードしたファイルのメタデータを取得します
• list_files: アップロードしたファイルをページネーションと並べ替えを指定して一覧表示します
• delete_file: アップロードしたファイルを削除します
• extract_strings: ファイルから ASCII／Unicode 文字列を抽出します
• get_hex_view: ファイルの内容を 16 進数表示で取得します
• download_file: アップロードしたファイルをダウンロードします

ストレージ管理ツール

• get_storage_info: ストレージ使用状況の統計情報を取得します
• clean_storage: ストレージの空き容量を確保するため、古いファイルを削除します

📚 ドキュメント

詳細なドキュメントは docs/ ディレクトリにあります。

• アーキテクチャ図 - システムアーキテクチャを視覚的に表した図
• コード分析 - 詳細なコード構造と推奨事項
• インストールガイド - 詳細なセットアップ手順
• CLI 使用ガイド - コマンドラインインターフェイスのドキュメント
• API リファレンス - REST API エンドポイントと使用方法
• YARA ルールガイド - YARA ルールの作成と管理
• MCP 統合 - Model Context Protocol の統合に関する詳細
• ファイル管理 - ファイル処理機能
• 例 - 実際の使用例

🗂️ プロジェクト構成

yaraflux_mcp_server/
├── src/
│   └── yaraflux_mcp_server/
│       ├── app.py                 # FastAPI application
│       ├── auth.py                # JWT authentication and user management
│       ├── config.py              # Configuration settings loader
│       ├── models.py              # Pydantic models for requests/responses
│       ├── mcp_server.py          # MCP server implementation
│       ├── utils/                 # Utility functions package
│       │   ├── __init__.py        # Package initialization
│       │   ├── error_handling.py  # Standardized error handling
│       │   ├── param_parsing.py   # Parameter parsing utilities
│       │   └── wrapper_generator.py # Tool wrapper generation
│       ├── mcp_tools/             # Modular MCP tools package
│       │   ├── __init__.py        # Package initialization
│       │   ├── base.py            # Base tool registration utilities
│       │   ├── file_tools.py      # File management tools
│       │   ├── rule_tools.py      # YARA rule management tools
│       │   ├── scan_tools.py      # Scanning tools
│       │   └── storage_tools.py   # Storage management tools
│       ├── storage/               # Storage implementation package
│       │   ├── __init__.py        # Package initialization
│       │   ├── base.py            # Base storage interface
│       │   ├── factory.py         # Storage client factory
│       │   ├── local.py           # Local filesystem storage
│       │   └── minio.py           # MinIO/S3 storage
│       ├── routers/               # API route definitions
│       │   ├── __init__.py        # Package initialization
│       │   ├── auth.py            # Authentication API routes
│       │   ├── files.py           # File management API routes
│       │   ├── rules.py           # YARA rule management API routes
│       │   └── scan.py            # YARA scanning API routes
│       ├── yara_service.py        # YARA rule management and scanning
│       ├── __init__.py            # Package initialization
│       └── __main__.py            # CLI entry point
├── docs/                          # Documentation
├── tests/                         # Test suite
├── Dockerfile                     # Docker configuration
├── entrypoint.sh                  # Container entrypoint script
├── Makefile                       # Build automation
├── pyproject.toml                 # Project metadata, runtime deps, and the `dev` extra
├── requirements.txt               # Core dependency floors (also constrains the locks)
├── requirements-lock.txt          # Hash-pinned runtime lock (Docker build + security scan)
└── requirements-dev-lock.txt      # Hash-pinned runtime + dev lock (test image + security scan)

🧪 開発

ローカル開発

# Set up development environment
make dev-setup

# Run tests
make test

# Code quality checks
make lint
make format
make security-check

# Generate test coverage report
make coverage

# Run development server
make run

CI/CD ワークフロー

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています。

• CI テスト: main ブランチと develop ブランチへのすべてのプッシュおよびプルリクエストで実行されます

  • テスト、フォーマット、リンティング、型チェックを実行します
  • Docker イメージをビルドしてテストします
  • テストカバレッジレポートを Codecov にアップロードします

• バージョンの自動インクリメント: main ブランチへのプッシュ時にバージョンを自動でインクリメントします

  • pyproject.toml、setup.py、Dockerfile のバージョンを更新します
  • 新しいバージョンの Git タグを作成します

• リリースの公開: バージョンの自動インクリメントが成功した後に実行されます

  • 複数のステージ向けに Docker イメージをビルドします
  • Git のコミットからリリースノートを生成します
  • 成果物を含む GitHub リリースを作成します
  • Docker イメージを Docker Hub に公開します

これらのワークフローにより、コード品質を確保し、リリースプロセスを自動化します。

ステータスチェック

以下のステータスチェックがプルリクエストで実行されます。

• ✅ フォーマット検証：コードが Black と isort のフォーマット基準に従っていることを確認します
• ✅ Lint 検証：コードの品質とコーディング規約への準拠を検証します
• ✅ テスト実行：機能を検証するため、テストスイート全体を実行します
• ✅ カバレッジレポート：コードベースの十分なテストカバレッジを確認します

🌐 API ドキュメント

対話型 API ドキュメントはこちらから利用できます。

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc

詳細な API ドキュメントについては、API リファレンスをご覧ください。

🤝 貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE ファイルをご覧ください。

💖 寄付または機能のリクエスト

• Patreon
• PayPal