YaraFlux MCP サーバー
YARA スキャン用のモデル コンテキスト プロトコル (MCP) サーバー。LLM に YARA ルールを使用してファイルを分析する機能を提供します。
📋 概要
YaraFlux MCPサーバーは、AIアシスタントが標準化されたモデルコンテキストプロトコルインターフェースを介して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リポジトリからルールをインポートする
- ソースによる分類（カスタム vs. コミュニティ）
- 📊ファイル分析
- バイナリ解析のための16進表示
- 設定可能なパラメータによる文字列抽出
- ファイルのメタデータとハッシュ情報
- 安全なファイルのアップロードと保存
- 🔐セキュリティ機能
- APIアクセスのためのJWT認証
- 非ルートコンテナ実行
- 安全なストレージ分離
- 設定可能なアクセス制御
🚀 クイックスタート
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
🧩 クロード デスクトップ統合
YaraFlux は、モデル コンテキスト プロトコルを通じて Claude Desktop とシームレスに統合できるように設計されています。
- Docker イメージをビルドします。
docker build -t yaraflux-mcp-server:latest .
- 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"
]
}
}
}
- サーバーをアクティブにするには、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/ディレクトリにあります。
🗂️ プロジェクト構造
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 and dependencies
├── requirements.txt # Core dependencies
└── requirements-dev.txt # Development dependencies
🧪 開発
地域開発
# 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 テスト: メイン ブランチと開発ブランチへのすべてのプッシュ リクエストとプル リクエストで実行されます。
- テスト、フォーマット、リンティング、型チェックを実行します
- Dockerイメージのビルドとテスト
- テストカバレッジレポートをCodecovにアップロードします
- バージョン自動増分: メインブランチへのプッシュ時にバージョンを自動的に増分します
- pyproject.toml、setup.py、Dockerfile のバージョンを更新します
- 新しいバージョンのgitタグを作成する
- リリースの公開: バージョンの自動増分が成功した後にトリガーされます
- 複数のステージのDockerイメージをビルドする
- Gitコミットからリリースノートを生成する
- 成果物を含むGitHubリリースを作成する
- Docker イメージを Docker Hub に公開します
これらのワークフローはコードの品質を保証し、リリース プロセスを自動化します。
ステータスチェック
プル リクエストでは次のステータス チェックが実行されます。
- ✅フォーマット検証: コードが Black および isort フォーマット標準に準拠していることを確認します
- ✅ Lint検証: コードの品質とコーディング標準への準拠を検証します
- ✅テスト実行: 完全なテストスイートを実行して機能を検証します
- ✅カバレッジレポート: コードベースの十分なテストカバレッジを保証します
🌐 APIドキュメント
インタラクティブな API ドキュメントは次の場所で入手できます。
詳細な API ドキュメントについては、 API リファレンスを参照してください。
🤝 貢献する
貢献を歓迎します！お気軽にプルリクエストを送信してください。
- リポジトリをフォークする
- 機能ブランチを作成します（
git checkout -b feature/amazing-feature ） - 変更をコミットします (
git commit -m 'Add some amazing feature' ) - ブランチにプッシュする (
git push origin feature/amazing-feature ) - プルリクエストを開く
📄 ライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。
💖 寄付または機能のリクエスト