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.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
project.txt		project.txt
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Laraguard MCP

Overview

Features

MCP Tools

Code Scan — Detected Patterns

Audit Report Schema

Architecture

Requirements

Installation

Configuration

Environment Variables

Example .env

Development

Available Scripts

Running in Development Mode

Building for Production

Integration with MCP Clients

Generic MCP Configuration (JSON)

Using Development Mode (tsx)

Cursor IDE

Claude Desktop

Tool Usage Reference

project_info

dependency_audit

config_audit

code_scan

blade_scan

route_audit

attack_simulate

full_audit

Security Design

Important Notes

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Example `.env`

`project_info`

`dependency_audit`

`config_audit`

`code_scan`

`blade_scan`

`route_audit`

`attack_simulate`

`full_audit`

Packages