GuardianMCP

# GuardianMCP 🛡️ Your vigilant security companion that automatically guards your projects against vulnerabilities. GuardianMCP is an MCP (Model Context Protocol) server that scans project dependencies for known security vulnerabilities using the OSV.dev database. Works with **Cursor**, **VS Code**, **Claude Desktop**, and other MCP-compatible IDEs. ## Features - **Automatic vulnerability scanning** for npm and Composer dependencies - **Real-time alerts** for CRITICAL and HIGH severity issues - **Three scan modes**: full, summary, critical-high-only - **Auto-trigger support** via IDE rules (on install, commit, build) - **Multi-language keyword detection** (English, Latvian, French, Spanish, German, Russian, etc.) - **Docker support** for containerized deployment - **Detailed reports** with remediation guidance and CVE links - **Fast & lightweight** using OSV.dev API - **Secure by design** - 0 vulnerabilities, minimal dependencies ## Security Status    **Latest security audit:** All dependencies scanned, 0 vulnerabilities found **Node.js:** Latest LTS (22.x) with security updates **Regular updates:** Weekly dependency checks and monthly security reviews See [SECURITY.md](SECURITY.md) for detailed security policy and audit information. ## Quick Start Choose your preferred method: ### Option 1: npm (Recommended for most users) ```bash npm install -g guardian-mcp ``` ### Option 2: From Source ```bash git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp npm install npm run build ``` ### Option 3: Docker ```bash docker pull kalmars/guardian-mcp:latest # or docker-compose up -d ``` --- ## IDE Setup Instructions Click on your IDE to see setup instructions: <details> <summary><b>Cursor Editor (Recommended)</b></summary> ### Cursor Setup Cursor has native MCP support. Follow these steps: #### 1. Install GuardianMCP ```bash npm install -g guardian-mcp # or use local installation (see Quick Start) ``` #### 2. Configure Cursor Open Cursor settings: - **macOS/Linux**: `~/.cursor/config.json` or `Cursor Settings > Features > MCP Servers` - **Windows**: `%APPDATA%\Cursor\config.json` Add GuardianMCP configuration: ```json { "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` **Or if installed locally:** ```json { "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/absolute/path/to/guardian-mcp/dist/index.js"] } } } ``` #### 3. Enable Auto-Scanning (Optional) Create `.cursor/rules.md` in your project: ```markdown # Security Rules When working in this project: - Check for CRITICAL/HIGH vulnerabilities on project start - Scan after npm install or composer update - Verify no critical issues before git commits Use check_vulnerabilities tool with scan_mode="critical-high-only". ``` #### 4. Restart Cursor Completely restart Cursor to load GuardianMCP. #### 5. Test It Open Cursor's AI chat and type: ``` Check my project for security vulnerabilities ``` GuardianMCP will automatically scan your dependencies! </details> <details> <summary><b>Visual Studio Code</b></summary> ### VS Code Setup VS Code can use MCP servers through extensions or configuration. #### Method 1: Using Continue.dev Extension 1. Install [Continue.dev](https://marketplace.visualstudio.com/items?itemName=Continue.continue) extension 2. Open Continue settings (`.continue/config.json`) 3. Add MCP server configuration: ```json { "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` #### Method 2: Direct Configuration 1. Install GuardianMCP: `npm install -g guardian-mcp` 2. Add to VS Code settings (`.vscode/settings.json`): ```json { "mcp.servers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` #### 3. Enable Auto-Scanning Create `.vscode/rules.md`: ```markdown Automatically check for vulnerabilities when: - Opening the project - After running npm install/composer update - Before creating commits ``` #### 4. Restart VS Code Reload window: `Cmd/Ctrl + Shift + P` → "Reload Window" </details> <details> <summary><b>Claude Desktop</b></summary> ### Claude Desktop Setup Claude Desktop has built-in MCP support. #### 1. Install GuardianMCP ```bash npm install -g guardian-mcp ``` #### 2. Configure Claude Desktop Open configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` Add GuardianMCP: ```json { "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` **Or for local installation:** ```json { "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/Users/you/path/to/guardian-mcp/dist/index.js"] } } } ``` #### 3. Configure Auto-Scanning Add to `~/.claude/rules.md` (global) or project's `.claude/rules.md`: ```markdown # GuardianMCP Rules Automatically scan for vulnerabilities when: 1. User mentions: security, vulnerability, CVE, audit 2. After package installations 3. Before git commits Use scan_mode="critical-high-only" for auto-scans. ``` #### 4. Restart Claude Desktop Completely quit and reopen Claude Desktop. </details> <details> <summary><b>Windsurf Editor</b></summary> ### Windsurf Setup Windsurf supports MCP servers similar to Cursor. #### 1. Install GuardianMCP ```bash npm install -g guardian-mcp ``` #### 2. Configure Windsurf Open Windsurf configuration: - **Location**: `~/.windsurf/config.json` Add MCP server: ```json { "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` #### 3. Create Project Rules Add `.windsurf/rules.md` to your project: ```markdown Auto-scan dependencies for vulnerabilities on: - Project initialization - npm/composer commands - Pre-commit checks ``` #### 4. Restart Windsurf Reload the editor to activate GuardianMCP. </details> <details> <summary><b>Zed Editor</b></summary> ### Zed Setup Zed is adding MCP support. Check current status: #### 1. Install GuardianMCP ```bash npm install -g guardian-mcp ``` #### 2. Configure Zed Open Zed settings: - **macOS**: `~/.config/zed/settings.json` - **Linux**: `~/.config/zed/settings.json` Add configuration: ```json { "assistant": { "mcp_servers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } } ``` #### 3. Restart Zed Reload the editor. **Note**: MCP support in Zed may be experimental. Check [Zed documentation](https://zed.dev/docs) for latest status. </details> <details> <summary><b>Docker Setup (Any IDE)</b></summary> ### Docker Setup Run GuardianMCP in a Docker container and connect from any IDE. #### Method 1: Using Docker Compose (Recommended) 1. **Clone the repository:** ```bash git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp ``` 2. **Build and run:** ```bash docker-compose up -d ``` 3. **Configure your IDE:** In your IDE's MCP configuration, use: ```json { "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } } ``` #### Method 2: Docker Run 1. **Build the image:** ```bash docker build -t kalmars/guardian-mcp:latest . ``` 2. **Run the container:** ```bash docker run -d --name guardian-mcp \ -v /path/to/your/projects:/projects:ro \ kalmars/guardian-mcp:latest ``` 3. **Configure your IDE:** ```json { "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } } ``` #### For Cursor with Docker: Edit `~/.cursor/config.json`: ```json { "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } } ``` #### Volume Mounting To scan projects outside the container: ```bash docker run -d --name guardian-mcp \ -v /Users/you/projects:/projects:ro \ -v /Users/you/work:/work:ro \ guardian-mcp:latest ``` Then scan with: ``` Scan /projects/my-app for vulnerabilities ``` #### Docker Health Check ```bash docker ps --filter name=guardian-mcp # Should show "healthy" status ``` #### Stopping the Container ```bash docker-compose down # or docker stop guardian-mcp && docker rm guardian-mcp ``` </details> <details> <summary><b>Other IDEs / Custom Setup</b></summary> ### Generic MCP Setup For any IDE that supports Model Context Protocol: #### 1. Install GuardianMCP ```bash npm install -g guardian-mcp ``` #### 2. Find Your IDE's MCP Configuration Common locations: - `~/.config/[IDE_NAME]/config.json` - `~/.config/[IDE_NAME]/settings.json` - `~/.[IDE_NAME]/mcp.json` #### 3. Add GuardianMCP ```json { "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } ``` Or with full path: ```json { "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/full/path/to/guardian-mcp/dist/index.js"] } } } ``` #### 4. Verify Setup Test by asking your IDE's AI assistant: ``` Use the check_vulnerabilities tool to scan my project ``` </details> --- ## Usage Once GuardianMCP is installed in your IDE, you can: ### Manual Scanning Simply ask your AI assistant: ``` Check my project for security vulnerabilities ``` ``` Scan package.json for critical issues only ``` ``` Give me a full security audit ``` ### Automatic Scanning Configure rules in your IDE's rules file (`.cursor/rules.md`, `.claude/rules.md`, etc.): ```markdown # Security Automation When I mention: security, vulnerability, CVE, audit, or exploit → Run check_vulnerabilities with scan_mode="critical-high-only" After running: npm install, npm update, composer install, composer update → Automatically scan for new vulnerabilities Before creating git commits: → Check for CRITICAL vulnerabilities and warn if found ``` ## Tool Parameters GuardianMCP provides the `check_vulnerabilities` tool with these parameters: | Parameter | Type | Options | Default | Description | |-----------|------|---------|---------|-------------| | `project_path` | string | any path | current dir | Path to project directory | | `file_type` | string | `package.json`, `composer.json`, `both` | `both` | Which files to scan | | `scan_mode` | string | `full`, `summary`, `critical-high-only` | `full` | Output detail level | ### Examples **Full scan:** ``` Check vulnerabilities with scan_mode="full" ``` **Quick summary:** ``` How many vulnerabilities are in my project? (uses scan_mode="summary") ``` **Auto-scan mode (recommended):** ``` Scan for critical vulnerabilities only (scan_mode="critical-high-only") ``` ## Scan Modes Explained ### `full` Mode **Best for:** Manual security audits, comprehensive reviews Shows ALL vulnerabilities with complete details: - CRITICAL, HIGH, MODERATE, and LOW severity - Detailed descriptions and remediation steps - Reference links and CVE IDs - Update commands for each package **Example output:** ```markdown ## 🔴 express@4.17.1 **Vulnerability ID:** GHSA-rv95-896h-c2vc **Severity:** CRITICAL ### ⚠️ CRITICAL RISK! **Description:** Express.js accepts requests with malformed URL encoding **IMMEDIATE ACTION REQUIRED:** 1. Update package: npm update express 2. Verify no vulnerable functionality is used ... ``` ### `summary` Mode **Best for:** Quick health checks, CI/CD dashboards Shows only vulnerability counts: - Fast overview - No detailed descriptions - Total counts by severity **Example output:** ```markdown ## 📊 Summary - 🔴 Critical: 2 - 🟠 High: 5 - 🟡 Moderate: 12 - 🟢 Low: 3 **Total: 22 vulnerabilities** Run with scan_mode="full" for details. ``` ### `critical-high-only` Mode **Best for:** Auto-scans, automated monitoring (RECOMMENDED for rules) Shows detailed info for CRITICAL/HIGH, counts others: - Reduces noise - Highlights actionable issues - Perfect for automatic scans - Hides moderate/low details **Example output:** ```markdown ## 🔴 lodash@4.17.20 **Severity:** HIGH **Issue:** Prototype pollution vulnerability **Recommendation:** npm update lodash --- ## 📊 Summary - 🔴 Critical: 1 - 🟠 High: 2 _Also found 8 moderate/low issues (hidden)._ _Run with scan_mode="full" to see all._ ``` ## Severity Levels | Level | Icon | Action | Examples | |-------|------|--------|----------| | **CRITICAL** | 🔴 | Update IMMEDIATELY | RCE, Auth bypass, Privilege escalation | | **HIGH** | 🟠 | Update ASAP | SQL injection, XSS, CSRF | | **MODERATE** | 🟡 | Plan update | DoS, Information disclosure | | **LOW** | 🟢 | Consider updating | Deprecated packages, Minor issues | ## Example Rules Files See [`examples/`](examples/) for ready-to-use templates: - **`claude-rules.md`** - Comprehensive template with all scenarios - **`project-rules.md`** - Project-specific configuration example - **`global-rules.md`** - User-wide configuration for all projects Copy these to: - Cursor: `.cursor/rules.md` - Claude Desktop: `.claude/rules.md` - VS Code: `.vscode/rules.md` (with Continue.dev) ## Supported Ecosystems | Ecosystem | File | Status | |-----------|------|--------| | **npm** (Node.js) | `package.json` | ✅ Supported | | **Composer** (PHP) | `composer.json` | ✅ Supported | | PyPI (Python) | `requirements.txt` | 🔄 Planned | | Go Modules | `go.mod` | 🔄 Planned | | Maven (Java) | `pom.xml` | 🔄 Planned | | NuGet (.NET) | `*.csproj` | 🔄 Planned | | RubyGems | `Gemfile` | 🔄 Planned | | Cargo (Rust) | `Cargo.toml` | 🔄 Planned | ## Troubleshooting <details> <summary><b>GuardianMCP not showing up in IDE</b></summary> 1. **Verify installation:** ```bash npx guardian-mcp --version # or which guardian-mcp ``` 2. **Check config file path is absolute:** - ❌ `"args": ["dist/index.js"]` - ✅ `"args": ["/Users/you/guardian-mcp/dist/index.js"]` 3. **Restart IDE completely** (don't just reload window) 4. **Check IDE logs:** - Cursor: Open DevTools (Help > Toggle Developer Tools) - VS Code: Output panel > Extension Host - Claude Desktop: View > Developer > Toggle Developer Tools 5. **Test manually:** ```bash node /path/to/guardian-mcp/dist/index.js # Should not crash ``` </details> <details> <summary><b>Auto-scanning not working</b></summary> 1. **Verify rules file exists:** ```bash cat .cursor/rules.md # or cat .claude/rules.md ``` 2. **Check rules mention tool name:** - Must reference `check_vulnerabilities` - Use `scan_mode="critical-high-only"` for auto-scans 3. **Test with keywords:** - Try saying "security" or "vulnerability" - Should trigger automatic scan 4. **Check IDE supports rules:** - Cursor: ✅ Built-in support - Claude Desktop: ✅ Built-in support - VS Code: Depends on extension </details> <details> <summary><b>Docker container not starting</b></summary> 1. **Check logs:** ```bash docker logs guardian-mcp ``` 2. **Verify build succeeded:** ```bash docker build -t kalmars/guardian-mcp:latest . ``` 3. **Test manually:** ```bash docker run -it kalmars/guardian-mcp:latest ``` 4. **Check health:** ```bash docker ps --filter name=guardian-mcp # Status should be "healthy" ``` </details> <details> <summary><b>OSV.dev API errors</b></summary> 1. **Check internet connection** 2. **Verify API is accessible:** ```bash curl https://api.osv.dev/v1/query ``` 3. **Rate limiting:** OSV.dev has rate limits - Wait a few minutes - Reduce scan frequency 4. **Firewall:** Ensure outbound HTTPS is allowed </details> ## Contributing Contributions are welcome! Areas for improvement: - Additional ecosystem support (Python, Go, Rust, etc.) - Better version range parsing - Caching to reduce API calls - IDE-specific optimizations - Test coverage - Documentation improvements ## License MIT - See [LICENSE](LICENSE) file ## Resources - [OSV.dev Database](https://osv.dev/) - [OSV.dev API Docs](https://osv.dev/docs/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Cursor Documentation](https://cursor.sh/docs) - [VS Code MCP Guide](https://code.visualstudio.com/) ## Security Note GuardianMCP helps identify known vulnerabilities but is **not a substitute for**: - Comprehensive security audits - Penetration testing - Secure coding practices - Regular dependency updates - Security training **Always review and test dependency updates before deploying to production.** --- <p align="center"> Made with 🛡️ by the GuardianMCP team </p> <p align="center"> <a href="https://github.com/Kalvisan/guardian-mcp/issues">Report Bug</a> · <a href="https://github.com/Kalvisan/guardian-mcp/issues">Request Feature</a> · <a href="https://github.com/Kalvisan/guardian-mcp">Star on GitHub</a> </p>