Laraguard MCP

Laraguard MCP

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

 ](https://nodejs.org/)   ](./package.json)

______________________________________________________________________

概述

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

服务器将Laravel项目分析为 外部目标 --它不需要Laravel运行。它返回按严重性分类的结构化JSON结果，涵盖配置问题、风险代码模式和依赖卫生。

______________________________________________________________________

特性

• 🔍 静态代码扫描 --超过15条规则，涵盖SQL注入、RCE、硬编码凭据、弱加密、大规模分配和LFI
• 🎭 Blade XSS扫描仪 --检测未扫描 {!! !!} 模板中的输出和原始输入渲染
• 🛣️ 路由和中间件审计 -标记不带身份验证的管理路由、不带身份证明的API路由：制裁、不带节流的登录路由和CSRF异常
• 📦 依赖CVE提要 --查询 OSV.dev API适用于所有实际CVE composer.lock 包裹
• ⚙️ 配置审核 --检查 .env （调试、APP_KEY、APP_ENV、安全Cookie）以及 config/cors.php
• 🗂️ 项目元数据 --阅读 composer.json 识别Laravel和PHP版本约束
• 💥 主动攻击模拟 --对正在运行的应用程序启动HTTP探测（SQL注入、XSS、CSRF、身份验证旁路、速率限制）
• 🔒 路径遍历预防 --对所有文件操作严格执行allowlist
• ✂️ 秘密编辑 --敏感值在到达MCP客户端之前在文本输出中被屏蔽
• 🚀 stdio传输 --零配置网络；适用于任何支持MCP的IDE

______________________________________________________________________

MCP工具

服务器暴露 8工具。所有静态工具都接受一个 path 参数。 attack_simulate 另外需要a baseUrl.

代码扫描——检测到的模式

审核报告架构

每个工具都返回一个结构化的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或以上
• 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_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

生产大楼

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"
      }
    }
  }
}

光标IDE

打开 设置→ MCP 并粘贴上面的JSON块。Cursor将在下次重新加载时检测服务器。

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）并添加 laraguard 进入下 mcpServers.

______________________________________________________________________

工具使用参考

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" }

______________________________________________________________________

code_scan

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

对所有PHP文件执行逐行静态分析。返回每个匹配的结果，包括文件路径、行号和证据片段。请参阅 代码扫描——检测到的模式 上表显示了完整的规则集。

______________________________________________________________________

blade_scan

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

扫描全部 .blade.php 文件下 resources/views/ 对于易发生XSS的输出模式：

______________________________________________________________________

route_audit

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

倒像 routes/web.php, routes/api.php，以及 app/Http/Middleware/VerifyCsrfToken.php:

______________________________________________________________________

attack_simulate

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

⚠️ 仅用于本地或临时环境。永远不要违背生产。

对正在运行的应用程序启动6个实时HTTP探测：

该报告包括 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)防止大型monorepos上的枚举失控。
• 文件大小限制 --可配置上限(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许可证。参见 许可证 了解详情。