Laraguard Mcp

Laraguard MCP

Laravel プロジェクト向けのセキュリティ監査 MCP サーバーです。TypeScript と stdio トランスポートで構築されています。

---

概要

Laraguard MCP は、Laravel プロジェクトのセキュリティ監査を実施するスタンドアロンの Model Context Protocol (MCP) サーバーです。公式の @modelcontextprotocol/sdk を使用して純粋な TypeScript で実装され、stdio 経由で通信するため、MCP 対応の IDE やクライアント（Cursor、Claude Desktop、VS Code MCP 拡張機能など）とネイティブに互換性があります。

このサーバーは Laravel プロジェクトを外部の監査対象として解析するため、Laravel の実行は不要です。設定の問題、リスクのあるコードパターン、依存関係の適切性を対象に、重大度別に分類された構造化 JSON の検出結果を返します。

---

機能

• 🔍 静的コードスキャン — SQL インジェクション、RCE、ハードコードされた認証情報、脆弱な暗号化、マスアサインメント、LFI を対象とする 15 以上のルール
• 🎭 Blade XSS スキャナー — テンプレート内のエスケープされていない {!! !!} 出力や、生の入力値の描画を検出
• 🛣️ ルートとミドルウェアの監査 — 認証のない管理者ルート、auth:sanctum のない API ルート、スロットリングのないログインルート、CSRF の例外を検出
• 📦 依存関係の CVE フィード — OSV.dev API を照会し、すべての composer.lock パッケージに関する実際の CVE を取得
• ⚙️ 設定監査 — .env（DEBUG、APP_KEY、APP_ENV、セキュア Cookie）と config/cors.php を検査
• 🗂️ プロジェクトメタデータ — composer.json を読み取り、Laravel と PHP のバージョン制約を特定
• 💥 攻撃のアクティブシミュレーション — 実行中のアプリに HTTP プローブ（SQL インジェクション、XSS、CSRF、認証バイパス、レート制限）を送信
• 🔒 パストラバーサル防止 — すべてのファイル操作で厳格な許可リストを適用
• ✂️ シークレットの秘匿化 — MCP クライアントに渡す前に、テキスト出力内の機密値をマスク
• 🚀 stdio トランスポート — ネットワーク設定は不要。MCP をサポートするあらゆる IDE 内で動作

---

MCP ツール

このサーバーは 8 つのツールを公開します。静的ツールはすべて、単一の path パラメーターを受け取ります。attack_simulate ではさらに baseUrl が必要です。

ツール	入力	説明
project_info	path	composer.json からプロジェクト名、Laravel／PHP のバージョン制約、エンジン情報などのメタデータを返します。
dependency_audit	path	composer.lock を解析し、OSV.dev を照会して、重大度と修正バージョンを含む実際の CVE を取得します。
config_audit	path	.env（DEBUG、APP_KEY、APP_ENV、セッション Cookie）と config/cors.php（ワイルドカードのオリジン）を検査します。
code_scan	path	すべての PHP ファイルを対象に、認証情報、脆弱な暗号化、マスアサインメント、RCE、LFI、SQL インジェクションなど、15 以上の静的パターンルールでスキャンします。
blade_scan	path	resources/views/ の Blade テンプレートをスキャンし、エスケープされていない出力（{!! !!}）や XSS を引き起こしやすいパターンを検出します。
route_audit	path	ルートファイルとミドルウェアを監査し、認証の欠如、スロットリングの欠如、CSRF 例外のワイルドカードを検出します。
attack_simulate	path + baseUrl	実行中のアプリに 6 種類の HTTP プローブを送信します。SQL インジェクション、XSS、CSRF、認証バイパス、レート制限、エラー情報の漏えいが対象です。
full_audit	path	dependency_audit + config_audit + code_scan + blade_scan + route_audit を並列実行し、統合レポートを返します。

コードスキャン — 検出されるパターン

パターン	重大度	検出タイプ
->whereRaw(	高	SQL_INJECTION
DB::raw(	中	RAW_SQL_USAGE
unserialize(	重大	UNSAFE_UNSERIALIZE
shell_exec( / exec( / system( / passthru(	重大	RCE_RISK
eval(	重大	EVAL_USAGE
password = 'literal'	重大	HARDCODED_PASSWORD
api_key = 'literal'	重大	HARDCODED_API_KEY
ハードコードされた長いトークン／シークレット	高	HARDCODED_SECRET
md5(	高	WEAK_HASH_MD5
sha1(	中	WEAK_HASH_SHA1
protected $guarded = []	高	MASS_ASSIGNMENT_UNGUARDED
file_get_contents($request…)	重大	PATH_TRAVERSAL_RISK
include/require($request…)	重大	LFI_RISK

監査レポートのスキーマ

各ツールは、構造化された JSON レポートを返します。

{
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0,
    "info": 1
  },
  "findings": [
    {
      "severity": "high",
      "type": "SQL_INJECTION",
      "title": "Potential SQL injection via whereRaw",
      "file": "app/Http/Controllers/UserController.php",
      "line": 42,
      "evidence": "->whereRaw('email = ' . $email)",
      "recommendation": "Avoid raw SQL with user input. Use parameter binding/query builder."
    }
  ],
  "metadata": {
    "scannedPath": "/absolute/path/to/laravel-project",
    "engine": "Laraguard MCP",
    "version": "3.0.0",
    "timestamp": "2025-01-01T00:00:00.000Z",
    "durationMs": 312
  }
}

---

アーキテクチャ

src/
├── index.ts      — MCP server bootstrap and tool registration
├── config.ts     — Environment variable loading and validation
├── security.ts   — Path allowlist enforcement and secret redaction
├── files.ts      — Safe file enumeration and reading
├── tools.ts      — Audit tool implementations
├── reports.ts    — Report aggregation and severity summarization
└── types.ts      — Domain types (Finding, AuditReport, Severity, etc.)

実行環境のスタック：

コンポーネント	テクノロジー
ランタイム	Node.js 20+
言語	TypeScript 5.x
プロトコル	Model Context Protocol (MCP)
トランスポート	stdio
スキーマ検証	Zod
MCP SDK	@modelcontextprotocol/sdk

---

要件

• Node.js 20 以上
• npm 10 以上

環境を確認します。

node -v
npm -v

---

インストール

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/ecr17dev/Laraguard-MCP.git
cd "Laraguard MCP"
npm install

---

設定

環境設定ファイルのサンプルをコピーし、必要に応じてカスタマイズします。

cp .env.example .env

環境変数

変数	デフォルト	説明
MCP_BASE_PATH	—	プロジェクトのスキャンで許可される単一のルートパスです。
MCP_BASE_PATHS	—	許可されるルートパスをカンマ区切りで指定したリストです。MCP_BASE_PATH より優先されます。
MCP_MAX_FILES	5000	スキャンごとに列挙するファイルの最大数です。
MCP_MAX_FILE_SIZE_BYTES	300000	ファイルごとに読み込むファイルサイズの上限（バイト単位）です。
MCP_TIMEOUT_SECONDS	30	監査操作の論理タイムアウトです。

優先順位： MCP_BASE_PATHS → MCP_BASE_PATH → 現在の作業ディレクトリ。

.env の例

# Allow scanning two project roots
MCP_BASE_PATHS="/Users/yourname/projects/my-laravel-app,/srv/workspaces/api"

# Scan limits
MCP_MAX_FILES=5000
MCP_MAX_FILE_SIZE_BYTES=300000
MCP_TIMEOUT_SECONDS=30

---

開発

利用可能なスクリプト

コマンド	説明
npm run dev	tsx を使用して TypeScript ソースから MCP サーバーを直接実行します（開発時に推奨）。
npm run build	TypeScript を dist/ にコンパイルします。
npm run start	コンパイル済みのサーバーを dist/index.js から実行します。
npm run check	出力を生成せずに、プロジェクトの型をチェックします。

開発モードでの実行

npm run dev

本番環境向けのビルド

npm run check   # Validate types first
npm run build   # Emit to dist/
npm run start   # Run compiled output

---

MCP クライアントとの連携

汎用 MCP 設定（JSON）

以下を MCP クライアントの設定ファイルに追加し、パスをインストール先の絶対パスに置き換えます。

{
  "mcpServers": {
    "laraguard": {
      "command": "node",
      "args": ["/absolute/path/to/Laraguard MCP/dist/index.js"],
      "env": {
        "MCP_BASE_PATHS": "/absolute/path/to/your-laravel-project"
      }
    }
  }
}

開発モード（tsx）の使用

先にビルドせずに実行する場合は、次のようにします。

{
  "mcpServers": {
    "laraguard": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/Laraguard MCP/src/index.ts"],
      "env": {
        "MCP_BASE_PATHS": "/absolute/path/to/your-laravel-project"
      }
    }
  }
}

Cursor IDE

Settings → MCP を開き、上記の JSON ブロックを貼り付けます。Cursor は次回の再読み込み時にサーバーを検出します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）を編集し、mcpServers の下に laraguard エントリを追加します。

---

ツール使用リファレンス

project_info

{ "path": "/absolute/path/to/laravel-project" }

セキュリティチェックを実行せずに、プロジェクトの基本メタデータを返します。対象が有効な Laravel プロジェクトであることを確認し、監査前にフレームワークと PHP のバージョン要件を調べるために使用します。

---

dependency_audit

{ "path": "/absolute/path/to/laravel-project" }

composer.lock を解析し、ロックされているすべてのパッケージ名とバージョンを抽出して、既知の CVE について OSV.dev のバッチ API に問い合わせます。各脆弱性は、次の情報を含む検出結果として返されます。

• CVE/GHSA 識別子と概要
• 重大度（CVSS スコアからマッピング）
• 影響を受けるパッケージのバージョンと推奨修正バージョン
• アドバイザリーページへの直接リンク

---

config_audit

{ "path": "/absolute/path/to/laravel-project" }

チェック	ファイル	重要度
APP_DEBUG=true	.env	高
APP_ENV=local	.env	中
APP_KEY=（空）	.env	重大
SESSION_SECURE_COOKIE=false	.env	中
CORS オリジンのワイルドカード（'*'）	config/cors.php	中

---

code_scan

{ "path": "/absolute/path/to/laravel-project" }

すべての PHP ファイルに対して、行ごとの静的解析を実行します。一致した検出結果をすべて、ファイルパス、行番号、証拠となるスニペットとともに返します。ルールの全一覧については、上記のコードスキャン — 検出パターンテーブルを参照してください。

---

blade_scan

{ "path": "/absolute/path/to/laravel-project" }

resources/views/ 配下にあるすべての .blade.php ファイルをスキャンし、XSS を引き起こす可能性のある出力パターンを検出します。

チェック	重要度
{!! $variable !!} — エスケープされていない変数	高
{!! request( !!} / {!! old( !!} — 生のユーザー入力	重大
Blade の PHP ブロック内の echo $_GET / echo $_POST	高

---

route_audit

{ "path": "/absolute/path/to/laravel-project" }

routes/web.php、routes/api.php、および app/Http/Middleware/VerifyCsrfToken.php を読み込みます。

チェック	ファイル	重要度
auth ミドルウェアのない管理者／ダッシュボードルート	routes/web.php	重大
auth:sanctum / auth:api のない API ルート	routes/api.php	高
throttle ミドルウェアのないログイン／登録ルート	ルートファイル	中
VerifyCsrfToken::$except 内のワイルドカードパターン	VerifyCsrfToken.php	高

---

attack_simulate

{
  "path": "/absolute/path/to/laravel-project",
  "baseUrl": "http://localhost:8000"
}

⚠️ ローカル環境またはステージング環境に対してのみ使用してください。本番環境では絶対に実行しないでください。

実行中のアプリケーションに対し、6 件の HTTP プローブを実行します。

プローブ	メソッドとエンドポイント	テスト内容
error_disclosure	GET /__invalid_route__	フレームワーク情報／スタックトレース情報の漏えい
sql_injection_login	SQLi ペイロードを使用した POST /login	ログインフォームの SQL インジェクション
reflected_xss	GET /search?q=<script>…	検索／クエリパラメーターの反射型 XSS
csrf_not_enforced	CSRF トークンなしの POST /login	CSRF トークンの強制（HTTP 419 を想定）
auth_bypass	認証ヘッダーなしの GET /api/user	保護された API への未認証アクセス
rate_limit	10 回連続で実行する POST /login	ブルートフォース攻撃に対するレート制限（HTTP 429 を想定）

レポートには、各プローブのステータスコード、所要時間、トリガー状態を含む probes メタデータ配列が含まれます。

---

full_audit

{ "path": "/absolute/path/to/laravel-project" }

dependency_audit、config_audit、code_scan、blade_scan、route_audit を並列で実行し、すべての検出結果を単一の統合レポートにまとめます。メタデータには、セクションごとの概要が含まれます。

---

セキュリティ設計

Laraguard MCP は、信頼できないプロジェクトパスを扱う場合でも安全に動作するよう、以下の制御を実装しています。

• 厳格なパス許可リスト — すべてのファイルアクセスは MCP_BASE_PATHS / MCP_BASE_PATH に照らして検証されます。パストラバーサルの試みは直ちに拒否されます。
• ファイル数の上限 — 設定可能な上限（MCP_MAX_FILES）により、大規模なモノレポでの際限のない列挙を防ぎます。
• ファイルサイズの上限 — 設定可能な上限（MCP_MAX_FILE_SIZE_BYTES）により、バイナリファイルや生成ファイルによるメモリ枯渇を防ぎます。
• ディレクトリと拡張子の除外 — vendor/、node_modules/、.git/、およびバイナリファイル形式はスキャン対象から除外されます。
• シークレットのマスキング — MCP クライアントに返す前に、テキスト出力内の機密値（パスワード、トークン、キー）をマスキングします。
• 攻撃シミュレーションの保護 — attack_simulate の対象は、明示的に指定された baseUrl のみに限定されます。自動検出や本番環境の判定は行われません。

---

重要な注意事項

• Laraguard MCP は、Laravel プロジェクトを外部監査人の立場から分析します。静的ツールを使う場合、Laravel アプリケーション自体を起動しておく必要はありません。
• attack_simulate の実行には、アプリケーションが起動している必要があり、本番環境を対象にしてはいけません。
• サーバーはトランスポート層でフレームワークに依存しません。MCP stdio に対応するクライアントであれば、どれでも使用できます。
• すべての検出結果は参考情報です。本番環境のセキュリティ評価では、自動スキャンに手動でのコードレビューと専用の DAST／SAST ツール（OWASP ZAP、Burp Suite）を必ず組み合わせてください。

---

ライセンス

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