# MCP Vulnerability Reporting

Professional vulnerability report generator for security assessments. This MCP server creates standardized, well-formatted security reports following industry best practices.

## ⚠️ IMPORTANT: AI-Generated Content

This MCP **does not use pre-written templates**. Instead, **the AI (Claude) generates all report content** based on the specific vulnerability instance. The report structure follows the template format from `/Users/orhanyildirim/Desktop/mcp-browser-injection-extented/report.md`, but the content is dynamically created for each unique finding.

### What the AI Generates:
- ✅ Vulnerability Overview (educational description of the vulnerability type)
- ✅ Specific Findings (detailed analysis of this instance)
- ✅ Steps to Reproduce (customized for the target application)
- ✅ Recommendations (actionable remediation guidance)
- ✅ Impacts (business and technical impact analysis)
- ✅ References (OWASP, CWE, security resources)

## Features

- **AI-Powered Content Generation**: Claude generates comprehensive, contextual report content for each vulnerability
- **Template Structure Compliance**: Maintains the exact format from your report template
- **Flexible Content**: Adapts to different vulnerability types, severities, and application contexts
- **CVSS Scoring**: Automated CVSS v3.1 score and vector calculation
- **Evidence Management**: Support for screenshots, HTTP requests/responses, PoC code
- **Markdown Export**: Professional markdown reports ready for bug bounty submissions or pentest deliverables
- **Reference Database**: Fallback to default OWASP/CWE references if AI doesn't provide custom ones

## Installation

```bash
npm install
npm run build
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "browser-automation": {
      "command": "node",
      "args": ["/Users/your-username/Desktop/mcp-browser-injection-extented/dist/index.js"]
    },
    "vulnerability-reporting": {
      "command": "node",
      "args": ["/Users/your-username/Desktop/mcp-vulnerability-reporting/dist/index.js"]
    }
  }
}
```

## Tools Available

### 1. `create_vulnerability_report`

Creates a new vulnerability report with AI-generated content following the template structure.

**IMPORTANT**: The AI must generate all content sections. This tool does NOT use pre-written templates.

**Parameters:**
- `vulnerability`: Object containing vulnerability details
  - `type`: Vulnerability type (e.g., SQL_INJECTION, XSS, SSTI)
  - `severity`: Severity level (Critical, High, Medium, Low, Informational)
  - `url`: Target URL
  - `parameter`: Vulnerable parameter name
  - `payload`: Successful payload
  - `affectedEndpoint` (optional): Specific endpoint
  - `method` (optional): HTTP method

- `overview`: **AI-GENERATED** - General description of the vulnerability type (what is it, how does it work, why is it dangerous)

- `findings`: Object with specific findings
  - `specificDescription`: **AI-GENERATED** - Detailed description of this specific instance
  - `detectedBehaviors`: Array of observed behaviors (from testing)
  - `confidence`: Detection confidence level

- `stepsToReproduce`: **AI-GENERATED** - Array of step-by-step reproduction instructions

- `recommendations`: **AI-GENERATED** - Array of remediation recommendations with format:
  - `"- **Bold Header**: Detailed explanation"`

- `impacts`: **AI-GENERATED** - Array of potential impacts with format:
  - `"- **Bold Header**: What could happen"`

- `references` (optional): Array of security references
  - If not provided, template defaults are used

**Returns:** Report ID for future operations

### 2. `add_evidence_to_report`

Adds evidence to an existing report.

**Parameters:**
- `reportId`: Target report ID
- `evidenceType`: Type of evidence (screenshot, request, response, poc, code)
- `content`: Evidence content or file path
- `description`: Evidence description

### 3. `calculate_cvss_score`

Calculates CVSS score and vector for a report.

**Parameters:**
- `reportId`: Target report ID

### 4. `export_report`

Exports report as markdown file.

**Parameters:**
- `reportId`: Report ID to export
- `outputPath`: Output file path

### 5. `list_reports`

Lists all generated reports.

### 6. `get_report_preview`

Previews report in markdown format.

**Parameters:**
- `reportId`: Report ID to preview

### 7. `get_report_template`

Gets the exact report template format that AI should follow. **Use this before creating reports** to understand the required structure.

**Parameters:** None

**Returns:** The template with detailed formatting instructions for AI content generation

## Example Workflow with Browser MCP

Here's how to use both MCPs together. **Claude generates all report content:**

```
User: "Test https://vulnerable-site.com/login for SQL injection and create a professional report"

Claude uses Browser MCP:
1. browser_navigate({ url: "https://vulnerable-site.com/login" })
2. browser_test_payload({
     targetSelector: "#username",
     payload: "' OR 1=1--",
     submitSelector: "#login"
   })
   // Returns: { isVulnerable: true, confidence: "high", detectedBehaviors: [...] }

3. browser_screenshot({ path: "./evidence/sqli-bypass.png" })

Claude uses Reporting MCP (AI GENERATES ALL CONTENT):
4. get_report_template()
   // Returns: Template with exact structure and formatting requirements

5. create_vulnerability_report({
     vulnerability: {
       type: "SQL_INJECTION",
       severity: "Critical",
       url: "https://vulnerable-site.com/login",
       parameter: "username",
       payload: "' OR 1=1--",
       method: "POST"
     },

     // AI WRITES THIS OVERVIEW:
     overview: "SQL Injection is a code injection technique that exploits security vulnerabilities in an application's database layer. This vulnerability occurs when user-supplied input is incorporated into SQL queries without proper sanitization...",

     findings: {
       // AI WRITES THIS SPECIFIC DESCRIPTION:
       specificDescription: "The login form at /login endpoint is vulnerable to SQL injection via the username parameter. The application directly concatenates user input into SQL queries without using parameterized statements...",
       detectedBehaviors: ["SQL_ERROR_MESSAGE", "AUTHENTICATION_BYPASS"],
       confidence: "high"
     },

     // AI GENERATES THESE STEPS:
     stepsToReproduce: [
       "Navigate to https://vulnerable-site.com/login",
       "In the username field, enter: ' OR 1=1--",
       "In the password field, enter any value",
       "Click the login button",
       "Observe successful authentication bypass",
       "Verify by checking session cookie"
     ],

     // AI WRITES THESE RECOMMENDATIONS:
     recommendations: [
       "- **Use Parameterized Queries**: Implement prepared statements with parameterized queries for all database interactions...",
       "- **Input Validation**: Implement strict server-side input validation...",
       "- **Principle of Least Privilege**: Configure database accounts with minimal permissions..."
     ],

     // AI WRITES THESE IMPACTS:
     impacts: [
       "- **Complete Authentication Bypass**: An attacker can bypass the login mechanism entirely...",
       "- **Sensitive Data Exfiltration**: Using UNION-based attacks, attackers can extract database contents...",
       "- **Database Manipulation**: Attackers could modify or delete records..."
     ]
   })

6. add_evidence_to_report({
     reportId: "vuln_report_xxx",
     evidenceType: "screenshot",
     content: "./evidence/sqli-bypass.png",
     description: "Authentication Bypass - Successfully logged in as admin"
   })

7. calculate_cvss_score({ reportId: "vuln_report_xxx" })

8. export_report({
     reportId: "vuln_report_xxx",
     outputPath: "./reports/sql-injection-login-bypass.md"
   })
```

**See `USAGE_EXAMPLE.md` for a complete detailed example.**

## Report Format

Reports follow the exact template structure from `/Users/orhanyildirim/Desktop/mcp-browser-injection-extented/report.md`:

```markdown
## Vulnerability Overview
[AI-generated general description of vulnerability type]

### Finding Details
[AI-generated specific findings for this instance]

### Steps To Reproduce
1. [AI-generated step]
2. [AI-generated step]
...

## Recommendations
To address this finding, implement the following:
[AI-generated recommendations with bold headers]

## References
See the following for more information:
[AI-generated or template default references]

## Impacts
If not addressed, this finding could lead to the following:
[AI-generated impacts with bold headers]
```

## How It Works

1. **Template Loading**: MCP reads `report.md` template from its directory
2. **AI Reads Template**: Use `get_report_template()` to see the exact structure required
3. **Template Structure**: The markdown format is fixed and matches your report template exactly
4. **AI Content**: Claude generates all descriptive content based on:
   - The specific vulnerability found during testing
   - Security best practices and industry standards
   - Context from the target application
   - Severity and confidence levels
   - Template format guidelines
5. **Flexibility**: Content adapts to different vulnerability types, applications, and contexts
6. **Fallback References**: If AI doesn't provide custom references, the vulnerability database provides defaults for common types (SQL Injection, XSS, SSTI, Command Injection, NoSQL, LDAP, XXE)

## Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start
```

## Architecture

- `index.ts`: Main MCP server implementation
- `vulnerability-db.ts`: Vulnerability knowledge base with templates
- `dist/`: Compiled JavaScript output

## Integration with Browser Automation MCP

This MCP is designed to work seamlessly with the [mcp-browser-injection-extended](../mcp-browser-injection-extented) MCP server. The browser MCP handles:
- Automated vulnerability testing
- Payload generation and testing
- Evidence collection (screenshots, HTTP responses)

The reporting MCP then transforms those findings into professional security reports.

## License

MIT

## Contributing

Contributions welcome! Please submit issues and pull requests.