🔒 Vulnerability Assessment Framework MCP

A comprehensive Model Context Protocol (MCP) server for automated vulnerability assessment and security testing.

⚠️ IMPORTANT ETHICAL NOTICE

THIS TOOL IS FOR AUTHORIZED SECURITY TESTING ONLY

✅ Only use on systems you own or have explicit written permission to test
✅ Obtain proper authorization before conducting any security assessments
✅ Follow responsible disclosure practices for any vulnerabilities found.
❌ NEVER use this tool for unauthorized scanning or malicious purposes.
❌ Unauthorized security testing is illegal and unethical.

By using this tool, you agree to use it responsibly and in accordance with applicable laws and regulations.

📋 Features

🌐 Network Security Assessment

Host Discovery: Discover live hosts in network ranges
Port Scanning: Comprehensive port scanning with service detection
Service Enumeration: Identify services and versions on open ports
Banner Grabbing: Extract service banners and version information

🕸️ Web Application Security Testing

Vulnerability Scanning: Test for XSS, SQL Injection, LFI, RFI, CSRF
Security Headers Analysis: Check for missing security headers
SSL/TLS Configuration Testing: Analyze SSL/TLS security
Clickjacking Detection: Test for frame protection vulnerabilities

📊 Compliance Assessment

OWASP Top 10: Test against OWASP Top 10 (2017 & 2021)
CIS Benchmarks: Compliance checking for Linux, Windows, Apache, Nginx
Custom Security Frameworks: Extensible compliance checking

🔍 Vulnerability Management

CVE Database Integration: Look up CVE information from NVD
Known Vulnerability Matching: Check services against vulnerability databases
Risk Assessment: CVSS scoring and severity classification

📈 Reporting & Documentation

Multiple Report Formats: JSON, HTML, CSV, PDF support
Executive Summaries: High-level security assessment summaries
Detailed Findings: Comprehensive vulnerability documentation
Remediation Guidance: Actionable security recommendations

🔐 Security & Scope Management

Authorized Target Management: Strict scope verification
Authorization Tracking: Document testing permissions
Audit Logging: Comprehensive activity logging

🚀 Quick Start

Prerequisites

Node.js 18.0.0 or higher
TypeScript 5.0.0 or higher
Windows/Linux/macOS support

Installation

Clone and Setup:

cd vulnerability-assessment-mcp
npm install

Build the Project:

npm run build

Initialize Database:

npm run start
# Database will be automatically initialized on first run

MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "vulnerability-assessment": {
      "command": "node",
      "args": ["C:/Users/PrassanthVG/vulnerability-assessment-mcp/dist/index.js"],
      "env": {
        "NVD_API_KEY": "your-nvd-api-key-optional"
      }
    }
  }
}

📖 Usage Guide

1. Scope Management (CRITICAL FIRST STEP)

Before conducting any scans, you MUST add authorized targets:

// Add an authorized target
await mcp.call("scope_management", {
  action: "add",
  target: "example.com",
  authorization_ref: "PENTEST-2024-001"
});

// List authorized targets
await mcp.call("scope_management", {
  action: "list"
});

// Verify target authorization
await mcp.call("scope_management", {
  action: "verify",
  target: "192.168.1.100"
});

2. Network Discovery & Scanning

// Discover hosts in a network range
await mcp.call("network_discovery", {
  target: "192.168.1.0/24"
});

// Scan ports on a specific target
await mcp.call("port_scan", {
  target: "192.168.1.100",
  port_range: "top1000",
  scan_type: "tcp"
});

// Enumerate services on open ports
await mcp.call("service_enumeration", {
  target: "192.168.1.100",
  aggressive: false
});

3. Web Application Security Testing

// Comprehensive web vulnerability scan
await mcp.call("web_vulnerability_scan", {
  url: "https://example.com",
  scan_depth: 3,
  include_checks: ["xss", "sqli", "csrf", "headers"]
});

// SSL/TLS security analysis
await mcp.call("ssl_tls_analysis", {
  hostname: "example.com",
  port: 443
});

4. Vulnerability Research

// Look up specific CVE
await mcp.call("vulnerability_lookup", {
  cve_id: "CVE-2021-44228"
});

// Check service for known vulnerabilities
await mcp.call("check_known_vulnerabilities", {
  service: "apache",
  version: "2.4.49"
});

5. Compliance Assessment

// OWASP Top 10 assessment
await mcp.call("owasp_top10_check", {
  url: "https://example.com",
  year: "2021"
});

// CIS benchmark check
await mcp.call("cis_benchmark_check", {
  target: "192.168.1.100",
  benchmark_type: "linux"
});

6. Report Generation

// Generate comprehensive HTML report
await mcp.call("generate_report", {
  scan_id: "scan-2024-001",
  format: "html",
  include_remediation: true
});

🛠️ Available Tools

Network Tools

network_discovery - Discover live hosts
port_scan - Scan network ports
service_enumeration - Identify services
whois_lookup - Domain/IP WHOIS information
dns_enumeration - DNS record enumeration

Web Security Tools

web_vulnerability_scan - Web application security testing
ssl_tls_analysis - SSL/TLS configuration analysis

Vulnerability Management

vulnerability_lookup - CVE information lookup
check_known_vulnerabilities - Service vulnerability checking

Compliance Tools

owasp_top10_check - OWASP Top 10 assessment
cis_benchmark_check - CIS compliance checking

Reporting & Management

generate_report - Generate assessment reports
scope_management - Manage authorized targets

⚙️ Configuration

Environment Variables

# Optional NVD API key for better rate limits
export NVD_API_KEY="your-nvd-api-key"

# Custom database path (optional)
export DB_PATH="/custom/path/vulnerabilities.db"

File Structure

vulnerability-assessment-mcp/
├── src/                    # Source code
│   ├── index.ts           # Main MCP server
│   ├── scanners/          # Security scanners
│   ├── database/          # Vulnerability database
│   ├── reports/           # Report generation
│   ├── config/            # Configuration management
│   ├── compliance/        # Compliance checkers
│   └── utils/             # Utility functions
├── config/                # Configuration files
│   └── authorized_scope.json  # Authorized targets
├── data/                  # Database files
├── logs/                  # Application logs
├── reports/               # Generated reports
└── README.md             # This file

🔍 Example Scan Workflow

Here's a complete example of conducting a security assessment:

// 1. Add target to authorized scope
await mcp.call("scope_management", {
  action: "add",
  target: "testapp.local",
  authorization_ref: "ASSESSMENT-2024-001"
});

// 2. Discover hosts
const hosts = await mcp.call("network_discovery", {
  target: "192.168.1.0/24"
});

// 3. Scan ports on discovered hosts
const portScan = await mcp.call("port_scan", {
  target: "192.168.1.100",
  port_range: "top1000"
});

// 4. Enumerate services
const services = await mcp.call("service_enumeration", {
  target: "192.168.1.100",
  aggressive: true
});

// 5. Web application testing
const webScan = await mcp.call("web_vulnerability_scan", {
  url: "http://192.168.1.100",
  scan_depth: 3
});

// 6. Compliance assessment
const owasp = await mcp.call("owasp_top10_check", {
  url: "http://192.168.1.100",
  year: "2021"
});

// 7. Generate comprehensive report
const report = await mcp.call("generate_report", {
  scan_id: "assessment-2024-001",
  format: "html",
  include_remediation: true
});

📊 Sample Reports

The framework generates detailed reports including:

Executive Summary: High-level risk assessment
Vulnerability Details: Technical findings with CVSS scores
Compliance Results: Framework compliance status
Remediation Guidance: Actionable security recommendations
Risk Prioritization: Severity-based finding prioritization

🛡️ Security Best Practices

For Assessments

Always obtain written authorization before testing
Limit scope to authorized targets only
Use rate limiting to avoid impacting production systems
Document findings responsibly and securely
Follow responsible disclosure for vulnerability reporting

For Tool Usage

Keep dependencies updated regularly
Use secure configurations for all components
Protect assessment data with appropriate access controls
Log all activities for audit purposes
Regular backup of vulnerability database and configurations

🤝 Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Follow TypeScript/ESLint standards
Submit a pull request with detailed description

Development Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚖️ Legal Disclaimer

This tool is provided for educational and legitimate security testing purposes only. The authors and contributors are not responsible for any misuse or damage caused by this tool. Users are solely responsible for complying with applicable laws and obtaining proper authorization before conducting security assessments.

🆘 Support & Documentation

Issues: Report bugs and request features on GitHub
Documentation: Additional documentation available in /docs
Security: For security issues, please email security@example.com

🔄 Version History

v1.0.0 (Current)

Initial release
Full MCP integration
Comprehensive vulnerability assessment capabilities
OWASP Top 10 and CIS benchmark support
Multi-format reporting

Planned Features

Integration with additional vulnerability databases
Advanced exploitation frameworks
Cloud security assessment capabilities
API security testing enhancements
Real-time vulnerability monitoring

Remember: Use this tool responsibly and only on authorized systems! 🔐

Name		Name	Last commit message	Last commit date
config		config
dist		dist
logs		logs
node_modules		node_modules
src		src
ANALYSIS.md		ANALYSIS.md
DEMO_GUIDE.md		DEMO_GUIDE.md
README.md		README.md
USAGE_GUIDE.md		USAGE_GUIDE.md
WORKING_GUIDE.md		WORKING_GUIDE.md
axios		axios
install.ps1		install.ps1
mcp-config-example.json		mcp-config-example.json
package-lock.json		package-lock.json
package.json		package.json
simple_server.js		simple_server.js
test_mcp.js		test_mcp.js
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation