Laraguard Mcp

Laraguard MCP

A security audit MCP server for Laravel projects — built with TypeScript and stdio transport.

---

Overview

Laraguard MCP is a standalone Model Context Protocol (MCP) server that performs security audits on Laravel projects. It is implemented in pure TypeScript using the official @modelcontextprotocol/sdk and communicates over stdio, making it natively compatible with any MCP-capable IDE or client (Cursor, Claude Desktop, VS Code MCP extensions, etc.).

The server analyses a Laravel project as an external target — it does not require Laravel to be running. It returns structured JSON findings categorised by severity, covering configuration issues, risky code patterns, and dependency hygiene.

---

Features

• 🔍 Static code scanning — 15+ rules covering SQL injection, RCE, hardcoded credentials, weak crypto, mass assignment, and LFI
• 🎭 Blade XSS scanner — detects unescaped {!! !!} output and raw input rendering in templates
• 🛣️ Route & middleware audit — flags admin routes without auth, API routes without auth:sanctum, login routes without throttle, and CSRF exceptions
• 📦 Dependency CVE feed — queries the OSV.dev API for real CVEs across all composer.lock packages
• ⚙️ Configuration audit — inspects .env (DEBUG, APP_KEY, APP_ENV, secure cookies) and config/cors.php
• 🗂️ Project metadata — reads composer.json to identify Laravel and PHP version constraints
• 💥 Active attack simulation — fires HTTP probes (SQL injection, XSS, CSRF, auth bypass, rate limiting) against a running app
• 🔒 Path traversal prevention — strict allowlist enforcement for all file operations
• ✂️ Secret redaction — sensitive values are masked in textual output before reaching the MCP client
• 🚀 stdio transport — zero-config network; works inside any IDE that supports MCP

---

MCP Tools

The server exposes 8 tools. All static tools accept a single path parameter. attack_simulate additionally requires a baseUrl.

Tool	Input	Description
project_info	path	Returns metadata from composer.json: project name, Laravel/PHP version constraints, engine info.
dependency_audit	path	Parses composer.lock and queries OSV.dev for real CVEs with severity and fix versions.
config_audit	path	Inspects .env (DEBUG, APP_KEY, APP_ENV, session cookies) and config/cors.php (wildcard origins).
code_scan	path	15+ static pattern rules across all PHP files — credentials, weak crypto, mass assignment, RCE, LFI, SQL injection.
blade_scan	path	Scans resources/views/ Blade templates for unescaped output ({!! !!}) and XSS-prone patterns.
route_audit	path	Audits route files and middleware for missing auth, missing throttle, and CSRF exception wildcards.
attack_simulate	path + baseUrl	Fires 6 live HTTP probes against a running app: SQL injection, XSS, CSRF, auth bypass, rate limiting, error disclosure.
full_audit	path	Runs dependency_audit + config_audit + code_scan + blade_scan + route_audit in parallel and returns a consolidated report.

Code Scan — Detected Patterns

Pattern	Severity	Finding Type
->whereRaw(	High	SQL_INJECTION
DB::raw(	Medium	RAW_SQL_USAGE
unserialize(	Critical	UNSAFE_UNSERIALIZE
shell_exec( / exec( / system( / passthru(	Critical	RCE_RISK
eval(	Critical	EVAL_USAGE
password = 'literal'	Critical	HARDCODED_PASSWORD
api_key = 'literal'	Critical	HARDCODED_API_KEY
Long hardcoded tokens/secrets	High	HARDCODED_SECRET
md5(	High	WEAK_HASH_MD5
sha1(	Medium	WEAK_HASH_SHA1
protected $guarded = []	High	MASS_ASSIGNMENT_UNGUARDED
file_get_contents($request…)	Critical	PATH_TRAVERSAL_RISK
include/require($request…)	Critical	LFI_RISK

Audit Report Schema

Every tool returns a structured JSON report:

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

---

Architecture

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.)

Runtime stack:

Component	Technology
Runtime	Node.js 20+
Language	TypeScript 5.x
Protocol	Model Context Protocol (MCP)
Transport	stdio
Schema validation	Zod
MCP SDK	@modelcontextprotocol/sdk

---

Requirements

• Node.js 20 or higher
• npm 10 or higher

Verify your environment:

node -v
npm -v

---

Installation

Clone the repository and install dependencies:

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

---

Configuration

Copy the example environment file and customise it:

cp .env.example .env

Environment Variables

Variable	Default	Description
MCP_BASE_PATH	—	Single allowed root path for project scanning.
MCP_BASE_PATHS	—	Comma-separated list of allowed root paths. Takes precedence over MCP_BASE_PATH.
MCP_MAX_FILES	5000	Maximum number of files to enumerate per scan.
MCP_MAX_FILE_SIZE_BYTES	300000	Maximum file size (in bytes) to read per file.
MCP_TIMEOUT_SECONDS	30	Logical timeout for audit operations.

Priority order: MCP_BASE_PATHS → MCP_BASE_PATH → current working directory.

Example .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

---

Development

Available Scripts

Command	Description
npm run dev	Runs the MCP server directly from TypeScript source using tsx (recommended for development)
npm run build	Compiles TypeScript to dist/
npm run start	Runs the compiled server from dist/index.js
npm run check	Type-checks the project without emitting output

Running in Development Mode

npm run dev

Building for Production

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

---

Integration with MCP Clients

Generic MCP Configuration (JSON)

Add the following to your MCP client's configuration file, replacing the path with the absolute path to your installation:

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

Using Development Mode (tsx)

If you prefer to run without building first:

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

Open Settings → MCP and paste the JSON block above. Cursor will detect the server on the next reload.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add the laraguard entry under mcpServers.

---

Tool Usage Reference

project_info

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

Returns basic project metadata without performing any security checks. Use it to confirm the target is a valid Laravel project and inspect framework and PHP version constraints before auditing.

---

dependency_audit

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

Parses composer.lock, extracts all locked package names and versions, and queries the OSV.dev batch API for known CVEs. Each vulnerability is returned as a finding with:

• CVE/GHSA identifier and summary
• Severity (mapped from CVSS score)
• Affected package version and recommended fix version
• Direct link to the advisory page

---

config_audit

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

Check	File	Severity
APP_DEBUG=true	.env	High
APP_ENV=local	.env	Medium
APP_KEY= (empty)	.env	Critical
SESSION_SECURE_COOKIE=false	.env	Medium
Wildcard CORS origin ('*')	config/cors.php	Medium

---

code_scan

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

Performs line-by-line static analysis across all PHP files. Returns every matching finding with file path, line number, and evidence snippet. See the Code Scan — Detected Patterns table above for the full rule set.

---

blade_scan

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

Scans all .blade.php files under resources/views/ for XSS-prone output patterns:

Check	Severity
{!! $variable !!} — unescaped variable	High
{!! request( !!} / {!! old( !!} — raw user input	Critical
echo $_GET / echo $_POST in blade PHP blocks	High

---

route_audit

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

Reads routes/web.php, routes/api.php, and app/Http/Middleware/VerifyCsrfToken.php:

Check	File	Severity
Admin/dashboard route without auth middleware	routes/web.php	Critical
API route without auth:sanctum / auth:api	routes/api.php	High
Login/register route without throttle middleware	Route files	Medium
Wildcard pattern in VerifyCsrfToken::$except	VerifyCsrfToken.php	High

---

attack_simulate

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

⚠️ Only use against local or staging environments. Never run against production.

Fires 6 live HTTP probes against the running application:

Probe	Method & Endpoint	What it Tests
error_disclosure	GET /__invalid_route__	Framework/stack-trace info leakage
sql_injection_login	POST /login with SQLi payload	SQL injection in login form
reflected_xss	GET /search?q=<script>…	Reflected XSS in search/query params
csrf_not_enforced	POST /login without CSRF token	CSRF token enforcement (expects HTTP 419)
auth_bypass	GET /api/user without auth header	Unauthenticated access to protected API
rate_limit	10× rapid POST /login	Brute-force rate limiting (expects HTTP 429)

The report includes a probes metadata array with the status code, duration, and triggered state for every probe.

---

full_audit

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

Runs dependency_audit, config_audit, code_scan, blade_scan, and route_audit in parallel and merges all findings into a single consolidated report. The metadata includes per-section summaries.

---

Security Design

Laraguard MCP implements the following controls to ensure it operates safely even when handling untrusted project paths:

• Strict path allowlisting — all file access is validated against MCP_BASE_PATHS / MCP_BASE_PATH; path traversal attempts are rejected immediately.
• File count limit — configurable cap (MCP_MAX_FILES) prevents runaway enumeration on large monorepos.
• File size limit — configurable cap (MCP_MAX_FILE_SIZE_BYTES) prevents memory exhaustion from binary or generated files.
• Directory and extension exclusions — vendor/, node_modules/, .git/, and binary file types are excluded from scans.
• Secret redaction — sensitive values (passwords, tokens, keys) are masked in textual output before being returned to the MCP client.
• Attack simulation guard — attack_simulate always targets only the explicitly provided baseUrl; no automated discovery or production detection is performed.

---

Important Notes

• Laraguard MCP analyses a Laravel project as an external auditor — the Laravel application itself does not need to be running for static tools.
• attack_simulate requires the application to be running and should never target production.
• The server is framework-agnostic at the transport level: any client that supports MCP stdio can use it.
• All findings are informational. Always combine automated scanning with manual code review and dedicated DAST/SAST tooling (OWASP ZAP, Burp Suite) for production security assessments.

---

License

This project is licensed under the MIT License. See LICENSE for details.