AlienSec MCP Server

本番環境対応の AlienVault OTX エンドポイントセキュリティスキャン MCP サーバー（VirusTotal 統合付き）

// セキュリティコミュニティのために制作 — 資金提供により維持されています

概要

AlienSec MCP Server は、AlienVault OTX とオプションの VirusTotal 統合を使用して、包括的なエンドポイントセキュリティスキャン機能を提供する本番グレードの Model Context Protocol (MCP) サーバーです。

このサーバーにより、AI エージェントやアプリケーションは、さまざまなエンドポイントタイプ（macOS PKG、Windows PowerShell、Debian APT、Redhat RPM）に対してセキュリティスキャンを実行し、AlienVault OTX および VirusTotal API から脅威インテリジェンスを取得できます。

Related MCP server: Velociraptor MCP Server

機能

コア機能

• マルチプラットフォームエンドポイントスキャン

  • PKG インストーラーフレーバーを使用した macOS システムのスキャン

  • PowerShell を使用した Windows エンドポイントのスキャン

  • APT を使用した Debian/Ubuntu システムのスキャン

  • RPM を使用した Redhat/CentOS システムのスキャン

• VirusTotal 統合

  • VirusTotal API を使用したファイルと URL のスキャン

  • 既存の分析結果の取得

  • 自動レート制限とサーキットブレーカー保護

  • 複数の API キーサポート（VirusTotal ToS を遵守）

• 脅威インテリジェンス

  • AlienVault OTX パルスの検索

  • パルスの詳細とイベントの取得

  • 侵害インジケーター（IoC）へのアクセス

• データ永続化

  • オプションの暗号化を備えた SQLite データベース

  • タイムスタンプ付きのスキャン結果の保存

  • API リクエストのログ記録

  • サーキットブレーカーイベントの追跡

• 本番対応機能

  • 包括的なエラーハンドリング

  • Pino を使用した構造化ロギング

  • Zod を使用した環境変数の検証

  • 型安全な API スキーマ

  • グレースフルシャットダウン処理

前提条件

システム要件

• Node.js: >= 22.0.0

• npm: >= 8.0.0

• オペレーティングシステム: macOS、Linux、または Windows

• ディスク容量: 依存関係に最低 100MB

必要な API キー

1. AlienVault OTX API キー（必須）

   • https://otx.alienvault.com でサインアップ

   • 設定 > API キー に移動

   • 新しい API キーを生成

2. VirusTotal API キー（オプション、機能拡張用）

   • https://www.virustotal.com でサインアップ

   • API コンソール に移動

   • API キーを生成

   • 注: 無料プランでは 1 日 500 リクエスト、1 分あたり 4 リクエストが可能

インストール

1. リポジトリのクローン

git clone https://github.com/VRIL-LABS/aliensec-mcp-server.git
cd aliensec-mcp-server

2. 依存関係のインストール

npm install

これにより、すべての本番依存関係と開発依存関係がインストールされます。

3. 環境変数の設定

サンプル環境ファイルをコピーし、API キーで更新します:

cp .env.example .env

.env を API キーで編集します:

# Server Configuration
NAME=aliensec-mcp-server
VERSION=1.0.0
DEBUG=false
LOG_LEVEL=info

# AlienVault OTX Configuration (Required)
ALIENVAULT_API_KEY=your_alienvault_api_key_here
ALIENVAULT_BASE_URL=https://api.agent.otxb.io
ALIENVAULT_DEFAULT_REGION=us-east-1

# VirusTotal Configuration (Optional)
VIRUSTOTAL_API_KEYS=key1,key2,key3
VIRUSTOTAL_BASE_URL=https://www.virustotal.com/api/v3
VIRUSTOTAL_RATE_LIMIT_PER_MINUTE=4
VIRUSTOTAL_DAILY_LIMIT=500
VIRUSTOTAL_CIRCUIT_BREAKER_TIMEOUT=300

# Database Configuration
DATABASE_PATH=./data/aliensec.db
DATABASE_ENCRYPTION_KEY=your_encryption_key_here
DATABASE_TIMEOUT=5000

注: VirusTotal ToS は、レート制限を回避するための複数 API キーの使用を禁止しています。この実装はこれらの制限を尊重し、冗長性の目的でのみ複数のキーを使用します。

4.（オプション）SQLite 暗号化依存関係のインストール

Linux/macOS での暗号化データベースサポート用:

# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

使用方法

開発モード

自動リロード付きでサーバーを開発モードで実行:

npm run dev

本番モード

サーバーをビルドして実行:

npm run build
npm start

MCP クライアントでの使用

サーバーは stdio（標準入出力）を介して通信します。MCP クライアントで使用するには:

# Direct execution
node dist/index.js

# Or using the npm script
npm start

MCP クライアント統合の例

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const client = new Client({ name: 'my-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
});

await client.connect(transport);

// Call a scan tool
const result = await client.callTool({
  name: 'scan_macos_pkg',
  arguments: {
    target: '192.168.1.100',
    useVirusTotal: true,
  },
});

console.log(result.content);

利用可能なツール

スキャンツール（5）

VirusTotal ツール（2）

AlienVault OTX ツール（3）

データベースツール（4）

システムツール（1）

ブートストラップコマンド

サーバーは、各エンドポイントフレーバー用に事前設定されたブートストラップコマンドを提供します。以下の <api-key> は解決済みの ALIENVAULT_API_KEY 値であり、TARGET=<target> は target が指定された場合にのみ含まれます。

macOS PKG インストーラー

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=pkg)"

Windows PowerShell

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; API_KEY=<api-key> (new-object Net.WebClient).DownloadString("https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=powershell") | iex; install_agent -apikey <api-key> [-target <target>]

Debian APT

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=apt)"

Redhat RPM

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=rpm)"

プロジェクト構造

aliensec-mcp-server/
├── src/
│   ├── config/
│   │   └── index.ts           # Environment configuration & validation
│   ├── core/
│   │   ├── alienVault.ts      # AlienVault OTX API client
│   │   └── virusTotal.ts      # VirusTotal API client
│   ├── database/
│   │   └── index.ts           # SQLite database with repositories
│   ├── types/
│   │   └── index.ts           # TypeScript type definitions
│   └── index.ts               # Main MCP server entry point
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── eslint.config.js
├── .prettierrc
└── README.md

アーキテクチャ

レイヤード設計

┌─────────────────────────────────────┐
│           MCP Server Layer           │  ← src/index.ts
├─────────────────────────────────────┤
│         Core Service Layer           │  ← src/core/
├─────────────────────────────────────┤
│         Data Access Layer            │  ← src/database/
├─────────────────────────────────────┤
│        Configuration Layer           │  ← src/config/
├─────────────────────────────────────┤
│           Type Definitions           │  ← src/types/
└─────────────────────────────────────┘

主要な設計パターン

1. シングルトンパターン: データベース、AlienVault クライアント、VirusTotal クライアント

2. リポジトリパターン: ScanRepository、CircuitBreakerRepository、APILogRepository

3. サーキットブレーカーパターン: 障害発生時の自動 API キーローテーション

4. トークンバケットレートリミッター: VirusTotal API のレート制限

5. ファクトリーパターン: 依存性注入による MCP サーバー作成

6. ストラテジーパターン: 共通インターフェースを持つさまざまなスキャンフレーバー

データベーススキーマ

サーバーは SQLite を使用し、以下のテーブルを持ちます:

scan_records

検出結果、VirusTotal データ、タイムスタンプを含むすべてのスキャン結果を保存します。

circuit_breaker_events

API キーのサーキットブレーカー状態変更を追跡します。

api_logs

応答時間、ステータスコード、エラーを含むすべての API リクエストをログ記録します。

schema_version

マイグレーション用のデータベーススキーマバージョンを追跡します。

エラーハンドリング

カスタムエラークラス

• AlienSecError: コードと statusCode を持つ基本エラークラス

• AlienVaultAPIError: AlienVault 固有のエラー

• VirusTotalAPIError: レート制限検出付きの VirusTotal 固有のエラー

• DatabaseError: データベース関連のエラー

• ConfigurationError: 設定検証エラー

エラー応答形式

ツールエラーは、isError: true を持つ標準の MCP 結果形状を返します。人間が読めるメッセージは最初のコンテンツブロックであり、error は失敗を引き起こしたコンテキストデータ（スキャン ID、フレーバー、ターゲットなど）の JSON 文字列化されたものを保持します:

{
  "content": [
    { "type": "text", "text": "Scan failed: <error message>" }
  ],
  "isError": true,
  "error": "{\n  \"scanId\": \"...\",\n  \"flavor\": \"pkg\",\n  \"target\": \"...\",\n  \"error\": \"<error message>\"\n}"
}

ロギング

サーバーは構造化ロギングに Pino を使用し、以下のレベルがあります:

• error: 重大な障害

• warn: 警告と潜在的な問題

• info: 通常の操作とステータス更新

• debug: 詳細なデバッグ情報

• trace: 開発用の非常に詳細なロギング

ログは機密データ（API キー）が記録されないように自動的に編集されます。

レート制限とサーキットブレーカー

VirusTotal レート制限

• トークンバケットアルゴリズム: スムーズなレート制限

• 設定可能な制限: 環境変数で設定

• 自動待機: レート制限時の待機オプション

• サーキットブレーカー: 繰り返し失敗する API キーを自動的にブロック

サーキットブレーカー設定

• 失敗しきい値: 連続 5 回の失敗

• リセットタイムアウト: 300 秒（5 分）

• ハーフオープン状態: 完全に再開する前に 1 リクエストでテスト

ToS コンプライアンス

この実装は VirusTotal の利用規約を尊重 します:

• 複数の API キーは 冗長性 のためであり、制限の回避のためではありません

• 各 API キーは個別のレート制限を尊重します

• サーキットブレーカーは失敗時の迅速な再試行を防止します

• 1 日のリクエストカウントによりクォータの枯渇を防止します

開発

テストの実行

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npx vitest run --coverage

リンティングとフォーマット

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

型チェック

npm run typecheck

ビルド検証

# Clean build
npm run clean
npm run build

# Check build output
ls -la dist/

環境変数

セキュリティに関する考慮事項

データ保護

1. データベース暗号化: 保存時の機密データの暗号化にはDATABASE_ENCRYPTION_KEYを使用します

2. APIキーのセキュリティ: APIキーがログに記録されることはありません。環境変数または安全なボールトを使用してください

3. メモリの安全性: 機密文字列は、サーキットブレーカーおよびAPIログテーブルに保存する前にPBKDF2（120,000回の反復）でハッシュ化されます

ネットワークセキュリティ

1. HTTPSのみ: すべてのAPI通信はHTTPSを使用します

2. 証明書の検証: TLS証明書の検証はデフォルトで有効です

3. ユーザーエージェント: カスタムユーザーエージェントがサーバーバージョンを識別します

レート制限

1. クライアント側レート制限: 外部APIへの過剰なリクエストを防ぎます

2. サーキットブレーカー: 連鎖的な障害を防ぎます

3. バックプレッシャー: レート制限時に自動的に待機します

パフォーマンス

最適化

• コネクションプーリング: データベース接続が再利用されます

• 遅延ロード: リポジトリはオンデマンドで作成されます

• インデックス付きクエリ: データベーステーブルには適切なインデックスがあります

• キャッシング: APIキーのハッシュはサーキットブレーカーチェック用にキャッシュされます

• Async/Await: ノンブロッキングI/O操作

ベンチマーク

• スキャンリクエスト: ~100〜500ms（シミュレーション）

• VirusTotalリクエスト: ~200〜1000ms（ネットワーク依存）

• データベース操作: <10ms（ローカルSQLite）

トラブルシューティング

一般的な問題

データベース接続に失敗しました

Error: Failed to connect to database

解決策: データディレクトリが存在し、書き込み権限があることを確認してください:

mkdir -p data
chmod 755 data

ALIENVAULT_API_KEYが見つかりません

Missing required environment variables:
  - ALIENVAULT_API_KEY

解決策: 環境変数を設定してください:

export ALIENVAULT_API_KEY=your_api_key_here
# or add to .env file

VirusTotalのレート制限を超えました

Error: Rate limit exceeded for API key 0

解決策:

• レート制限がリセットされるまで待機します（デフォルト: 4リクエスト/分）

• APIキーを追加します（VIRUSTOTAL_API_KEYSにカンマ区切りで指定）

• wait: trueパラメータを使用して自動待機します

サーキットブレーカーが開いています

Error: API key 0 is blocked by circuit breaker

解決策: サーキットブレーカーのタイムアウトが期限切れになるまで待機します（デフォルト: 5分）。タイムアウト後、サーキットは自動的に再開します。

デバッグモード

詳細なトラブルシューティングのためにデバッグログを有効にします:

DEBUG=true LOG_LEVEL=debug npm run dev

コントリビューション

プルリクエスト

1. リポジトリをフォークします

2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）

3. 変更をコミットします（git commit -m 'Add amazing feature'）

4. ブランチにプッシュします（git push origin feature/amazing-feature）

5. プルリクエストを開きます

コミットメッセージのガイドライン

• Conventional Commits形式を使用します

• タイプをプレフィックスとして付けます: feat:、fix:、docs:、style:、refactor:、test:、chore:

• 件名は72文字未満に保ちます

• 必要に応じて本文に詳細な説明を記載します

コードレビュー

• すべてのPRは少なくとも1人のメンテナーによる承認が必要です

• CI/CDパイプラインが成功する必要があります（lint、型チェック、テスト）

• コードは既存のパターンとスタイルに従う必要があります

ライセンス

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

謝辞

• Model Context Protocol: https://modelcontextprotocol.io

• AlienVault OTX: https://otx.alienvault.com

• VirusTotal: https://www.virustotal.com

• TypeScript: https://www.typescriptlang.org

• Zod: https://github.com/colinhacks/zod

• Pino: https://github.com/pinojs/pino

• better-sqlite3-multiple-ciphers: https://github.com/m4heshd/better-sqlite3-multiple-ciphers

参考

• AlienVault OTXドキュメント

• VirusTotal APIドキュメント

• Model Context Protocol仕様

• MCP TypeScript SDK

セキュリティコミュニティのために❤️を込めて作られました