VSGuard MCP - Vulnerability Scanner & Guard

A production-ready Model Context Protocol (MCP) server that provides real-time OWASP ASVS security guidance and vulnerability scanning for AI coding agents.

VSGuard = Vulnerability Scanner + Guard - Powered by FastMCP 2.0

🎯 Overview

This MCP server integrates with Claude Desktop, Cursor, and other MCP-compatible tools to enable proactive security during code generation. It helps AI agents write secure code from the start by providing:

• 📋 OWASP ASVS Requirements - Real-time security guidance based on ASVS v4.0
• 🔍 Vulnerability Scanning - Static analysis using Semgrep with custom ASVS rules
• 🛠️ Secure Code Fixes - Actionable remediation with code examples
• 🤖 LLM-Optimized Output - Formatted for maximum comprehension by AI agents

✨ Features

Three Core Tools

1. check_security_requirements - Get relevant ASVS requirements before writing code
2. scan_code - Analyze code for vulnerabilities with ASVS mappings
3. suggest_fix - Generate secure code alternatives with explanations

Security Coverage

• ✅ Authentication (ASVS Chapter 2)
• ✅ Session Management (ASVS Chapter 3)
• ✅ Access Control (ASVS Chapter 4)
• ✅ Input Validation & Injection Prevention (ASVS Chapter 5)
• ✅ Cryptography (ASVS Chapters 6-9)
• ✅ Data Protection

Supported Languages

• Python (primary)
• JavaScript/TypeScript
• Java, Go, Ruby, PHP, C/C++, C#, Rust (via Semgrep)

🚀 Quick Start

Prerequisites

• Python 3.11+
• pip or Poetry
• Semgrep (for scanning)

Installation

# Clone repository
git clone https://github.com/yourname/vsguard-mcp
cd vsguard-mcp

# Install dependencies
pip install -e .

# Or with Poetry
poetry install

# Install Semgrep
pip install semgrep

Running the Server

# Run directly with FastMCP
python src/server.py

# Or use FastMCP CLI
fastmcp run src/server.py

# Or with Poetry
poetry run python src/server.py

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vsguard": {
      "command": "python",
      "args": ["/absolute/path/to/vsguard-mcp/src/server.py"]
    }
  }
}

Or with Poetry:

{
  "mcpServers": {
    "vsguard": {
      "command": "poetry",
      "args": ["run", "python", "/absolute/path/to/vsguard-mcp/src/server.py"]
    }
  }
}

Or use FastMCP CLI (simplest):

{
  "mcpServers": {
    "vsguard": {
      "command": "fastmcp",
      "args": ["run", "/absolute/path/to/vsguard-mcp/src/server.py"]
    }
  }
}

Restart Claude Desktop to load the server.

📖 Usage Examples

Example 1: Get Security Requirements

In Claude Desktop:

I need to create a user login endpoint. What security requirements should I follow?

Claude will call:

check_security_requirements(
    code_type="authentication",
    language="python"
)

Response:

# OWASP ASVS Security Requirements

## Level 1 Requirements (8)

### 2.1.1: Password Security
**Requirement:** Verify that user set passwords are at least 12 characters in length.

**Implementation Guide:**
- Add validation during user registration and password change
- Reject passwords shorter than 12 characters
- Consider allowing longer passwords (64+ chars)

**Code Example:**
```python
def validate_password_length(password: str) -> bool:
    if len(password) < 12:
        raise ValueError("Password must be at least 12 characters")
    return True

[... more requirements ...]

### Example 2: Scan Code for Vulnerabilities

**In Claude Desktop:**

Can you check this code for security issues?

def login(username, password): query = f"SELECT * FROM users WHERE username = '{username}'" cursor.execute(query)

**Claude will call:**
```python
scan_code(
    code="""def login(username, password):
    query = f"SELECT * FROM users WHERE username = '{username}'"
    cursor.execute(query)""",
    language="python"
)

Response:

❌ **SCAN FAILED**

**Total Findings:** 1
- 🟠 **HIGH:** 1

**ASVS Requirements Violated:** 5.3.4, 5.3.5

## Detailed Findings

### 1. 🟠 SQL Injection
**Severity:** HIGH
**ASVS Requirements:** 5.3.4, 5.3.5

**Issue:**
SQL injection vulnerability detected. User input is concatenated directly into SQL query.

**Location:** input.py:line 2

**Vulnerable Code:**
```python
query = f"SELECT * FROM users WHERE username = '{username}'"

Remediation: Use parameterized queries with placeholders instead of string concatenation.

Example:

cursor.execute("SELECT * FROM users WHERE username = ?", (username,))

### Example 3: Get Secure Code Fix

**In Claude Desktop:**

How do I fix this SQL injection vulnerability?

**Claude will call:**
```python
suggest_fix(
    vulnerable_code="cursor.execute(f'SELECT * FROM users WHERE id = {user_id}')",
    vulnerability_type="sql_injection",
    language="python"
)

Response:

# Security Fix Suggestion

**ASVS Requirements Addressed:** 5.3.4, 5.3.5

## ❌ Vulnerable Code
```python
cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")

✅ Secure Code

cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

# Or with SQLAlchemy ORM:
from sqlalchemy import select
stmt = select(User).where(User.username == username)
user = session.execute(stmt).scalar_one_or_none()

📝 Explanation

Use parameterized queries (prepared statements) instead of string concatenation.

🛡️ Security Benefits

• Prevents SQL injection attacks
• Separates code from data

## 🏗️ Project Structure

vsguard-mcp/ ├── src/ │ ├── server.py # MCP server entry point │ ├── config.py # Configuration │ ├── models.py # Pydantic data models │ │ │ ├── asvs/ │ │ ├── loader.py # Load ASVS from YAML │ │ ├── mapper.py # Map findings to ASVS │ │ └── requirements.py # Requirement models │ │ │ ├── scanners/ │ │ ├── base.py # Abstract scanner │ │ └── semgrep_scanner.py # Semgrep integration │ │ │ ├── fixes/ │ │ ├── generator.py # Fix generator │ │ └── templates.py # Fix templates │ │ │ └── utils/ │ └── formatters.py # LLM-optimized formatting │ ├── data/ │ ├── asvs/ # ASVS requirements (YAML) │ │ ├── authentication.yaml │ │ ├── session_management.yaml │ │ ├── validation.yaml │ │ └── cryptography.yaml │ │ │ └── rules/ # Custom Semgrep rules │ ├── authentication.yaml │ ├── injection.yaml │ ├── cryptography.yaml │ └── session.yaml │ └── tests/ # Test suite

## ⚙️ Configuration

Create a `.env` file (optional):

```env
# ASVS settings
MIN_ASVS_LEVEL=1

# Scanner settings
ENABLE_SEMGREP=true
SCAN_TIMEOUT=30
MAX_CODE_SIZE=50000

# Logging
LOG_LEVEL=INFO

🧪 Testing

# Run tests
pytest tests/

# Run specific test
pytest tests/test_asvs_loader.py

# With coverage
pytest --cov=src tests/

📊 Coverage

Current implementation includes:

• 40+ ASVS Requirements across authentication, session management, input validation, and cryptography
• 25+ Custom Semgrep Rules detecting common vulnerabilities
• 10+ Fix Templates with secure code examples
• Multiple Languages supported (Python, JavaScript, TypeScript, etc.)

Vulnerability Detection

• SQL Injection (ASVS 5.3.4, 5.3.5)
• Cross-Site Scripting (ASVS 5.3.3, 5.3.10)
• Weak Password Validation (ASVS 2.1.1, 2.1.7)
• Weak Cryptography (ASVS 6.2.2, 6.2.5)
• Hardcoded Secrets (ASVS 2.3.1, 14.3.3)
• Session Management Issues (ASVS 3.x)
• XML External Entity (XXE) (ASVS 5.5.2)
• Command Injection (ASVS 5.3.4)
• And more...

🎓 How It Works

1. ASVS Requirements Database

The server loads OWASP ASVS v4.0 requirements from structured YAML files:

requirements:
  - id: "2.1.1"
    level: 1
    category: "Password Security"
    requirement: "Verify that user set passwords are at least 12 characters in length."
    cwe: "CWE-521"
    description: "Passwords should be sufficiently long..."
    implementation_guide: "Add validation during registration..."
    code_examples:
      - |
        if len(password) < 12:
            raise ValueError("Too short")

2. Static Analysis with Semgrep

Custom Semgrep rules detect ASVS violations:

rules:
  - id: asvs-5-3-4-sql-injection
    pattern: cursor.execute(f"... {$VAR} ...")
    message: "ASVS 5.3.4: SQL injection vulnerability"
    severity: ERROR
    metadata:
      asvs_id: "5.3.4"
      cwe: "CWE-89"

3. Intelligent Mapping

Findings are automatically mapped to ASVS requirements by:

• Vulnerability type (sql_injection → ASVS 5.3.4)
• CWE ID (CWE-89 → ASVS 5.3.4, 5.3.5)
• Code patterns (login endpoints → authentication requirements)

4. LLM-Optimized Output

All responses are formatted for maximum LLM comprehension:

• Clear structure with headers and sections
• Code examples with syntax highlighting
• Severity indicators (🔴 🟠 🟡)
• Actionable remediation steps
• ASVS requirement references

🔧 Extending the Server

Add New ASVS Requirements

Create/edit YAML files in data/asvs/:

requirements:
  - id: "X.Y.Z"
    level: 1
    category: "Your Category"
    requirement: "Requirement text"
    cwe: "CWE-XXX"
    description: "Detailed explanation"
    implementation_guide: "How to implement"
    code_examples:
      - "Example code"

Add Custom Semgrep Rules

Create YAML files in data/rules/:

rules:
  - id: custom-rule-id
    patterns:
      - pattern: vulnerable_pattern()
    message: "Vulnerability description"
    severity: ERROR
    metadata:
      asvs_id: "X.Y.Z"
      cwe: "CWE-XXX"
      remediation: "How to fix"

Add Fix Templates

Edit src/fixes/templates.py:

FIX_TEMPLATES = {
    "vulnerability_type": {
        "python": {
            "vulnerable": "# Bad code",
            "secure": "# Good code",
            "explanation": "Why it's better",
            "asvs_requirements": ["X.Y.Z"],
        }
    }
}

🤝 Contributing

Contributions welcome! Areas for improvement:

1. More ASVS Requirements - Cover additional chapters
2. More Languages - Expand language support
3. More Scanners - Integrate Bandit, detect-secrets
4. Better AI Integration - Improve LLM output formatting
5. Performance - Optimize scanning speed

⚡ Powered By

• FastMCP 2.0 - Modern Python framework for MCP servers
• Semgrep - Static analysis engine
• OWASP ASVS - Security verification standard

📝 License

MIT License - see LICENSE file for details.

🔗 Resources

• OWASP ASVS
• Model Context Protocol
• Semgrep
• Claude Desktop

🙏 Acknowledgments

• OWASP for the ASVS standard
• Anthropic for the MCP protocol
• Semgrep for the scanning engine

📧 Support

For issues, questions, or contributions, please open an issue on GitHub.

---

Built with ❤️ for secure AI-assisted development