Laraguard Mcp

Laraguard MCP

用于 Laravel 项目的安全审计 MCP 服务——使用 TypeScript 和 stdio 传输构建。

---

概述

Laraguard MCP 是一个独立的 模型上下文协议（MCP） 服务，用于对 Laravel 项目执行安全审计。它使用官方 @modelcontextprotocol/sdk 以纯 TypeScript 实现，并通过 stdio 通信，因此可原生兼容任何支持 MCP 的 IDE 或客户端（Cursor、Claude Desktop、VS Code MCP 扩展等）。

该服务将 Laravel 项目作为外部目标进行分析——无需运行 Laravel。它会返回按严重程度分类的结构化 JSON 检测结果，涵盖配置问题、高风险代码模式和依赖项卫生状况。

---

功能

• 🔍 静态代码扫描 — 15 多条规则，涵盖 SQL 注入、RCE、硬编码凭据、弱加密、批量赋值和 LFI
• 🎭 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 文件应用 15 多条静态模式规则——凭据、弱加密、批量赋值、RCE、LFI、SQL 注入。
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，提取所有锁定的包名称和版本，并查询 OSV.dev 批量 API，以查找已知 CVE。每个漏洞都会作为一条发现返回，其中包含：

• 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。