rsvasanth/security-mcp-server

Security Tools MCP Server

A Model Context Protocol (MCP) server that provides controlled access to security testing tools through a Docker container running Kali Linux. This server is designed for educational purposes and authorized penetration testing only.

⚠️ Legal and Ethical Warning

IMPORTANT: This tool is designed for:

• Testing systems you own
• Authorized penetration testing with explicit written permission
• Educational and research purposes in controlled environments

Never use these tools on:

• Systems you don't own or lack permission to test
• Production systems without proper authorization
• Public networks or third-party services

Unauthorized security testing is illegal and can result in serious legal consequences.

Features

Integrated Security Tools

1. Nmap - Network discovery and security auditing
2. Nikto - Web server vulnerability scanner
3. SQLMap - SQL injection detection and exploitation
4. WPScan - WordPress vulnerability scanner
5. Dirb - Web content discovery tool
6. Searchsploit - Exploit database search

Security Features

• Network restrictions: Only scan allowed network ranges
• Input sanitization: Prevents command injection
• Non-root execution: Runs with minimal privileges
• Resource limits: CPU and memory constraints
• Timeout controls: Prevents runaway processes
• Audit logging: Tracks all tool usage

Installation

Prerequisites

• Docker and Docker Compose installed
• Python 3.8+ (for local development)
• Basic understanding of network security concepts

Quick Start

1. Clone or create the project files:

mkdir security-mcp
cd security-mcp
# Copy all the provided files to this directory

2. Configure environment variables:

cp .env.example .env
# Edit .env to set your allowed networks and other configurations

3. Build and run with Docker Compose:

docker-compose up --build

Manual Docker Build

# Build the image
docker build -t security-mcp-server .

# Run the container
docker run -d \
  --name security-mcp \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -e ALLOWED_NETWORKS="192.168.1.0/24" \
  -p 5000:5000 \
  security-mcp-server

Configuration

Environment Variables

Allowed Networks

Configure ALLOWED_NETWORKS to restrict scanning to your own infrastructure:

# Example: Only allow scanning of your local network
ALLOWED_NETWORKS=192.168.1.0/24

# Example: Multiple networks
ALLOWED_NETWORKS=10.10.0.0/16,192.168.0.0/24,172.16.5.0/24

Usage Examples

Using with an MCP Client

from mcp import Client

# Connect to the MCP server
client = Client("http://localhost:5000")

# Get server information
info = client.call("get_server_info")
print(info)

# Perform a basic nmap scan
result = client.call("nmap_scan", {
    "target": "192.168.1.1",
    "scan_type": "basic",
    "ports": "80,443,22"
})

# Scan a website with Nikto
nikto_result = client.call("nikto_scan", {
    "target": "192.168.1.100",
    "port": 80,
    "ssl": False
})

# Search for WordPress vulnerabilities
wp_result = client.call("wpscan_scan", {
    "target_url": "http://192.168.1.50",
    "enumerate": "vp"  # Enumerate vulnerable plugins
})

# Directory enumeration
dirb_result = client.call("dirb_scan", {
    "target_url": "http://192.168.1.100",
    "wordlist": "common",
    "extensions": ".php,.html,.txt"
})

# Search for exploits
exploits = client.call("searchsploit_search", {
    "search_terms": "apache 2.4",
    "json_output": True
})

Tool-Specific Usage

Nmap Scanning

# Stealth SYN scan
client.call("nmap_scan", {
    "target": "192.168.1.0/24",
    "scan_type": "stealth",
    "ports": "1-1000"
})

# Version detection scan
client.call("nmap_scan", {
    "target": "192.168.1.1",
    "scan_type": "version",
    "additional_flags": "--open -Pn"
})

SQL Injection Testing

# Test for SQL injection
client.call("sqlmap_scan", {
    "target_url": "http://192.168.1.100/page.php?id=1",
    "level": 2,
    "risk": 1
})

WordPress Scanning

# Enumerate users and plugins
client.call("wpscan_scan", {
    "target_url": "http://192.168.1.50",
    "enumerate": "up",  # users and plugins
    "api_token": "your_wpscan_api_token"  # Optional
})

Security Best Practices

1. Network Isolation

• Run the container in an isolated network segment
• Use VLANs or separate subnets for testing
• Implement proper firewall rules

2. Access Control

• Restrict access to the MCP server
• Use authentication if exposing beyond localhost
• Monitor and log all access attempts

3. Target Validation

• Always verify ownership or permission
• Document authorization for all tests
• Use written agreements for third-party testing

4. Rate Limiting

• Implement delays between scans
• Avoid overwhelming target systems
• Respect target system resources

Troubleshooting

Common Issues

1. Permission Denied Errors:

# Ensure proper capabilities are set
docker exec security-mcp getcap /usr/bin/nmap

2. Network Unreachable:

• Check Docker network configuration
• Verify ALLOWED_NETWORKS settings
• Ensure target is accessible from container

3. Tool Timeout:

• Increase MAX_TIMEOUT for longer operations
• Check network connectivity
• Verify target system is responsive

Debugging

Enable debug logging:

docker-compose down
export LOG_LEVEL=DEBUG
docker-compose up

View container logs:

docker logs security-mcp-server -f

Development

Adding New Tools

1. Update the Dockerfile to install the tool
2. Add a wrapper function in security_mcp_server.py
3. Implement input sanitization and validation
4. Test thoroughly in isolated environment

Example wrapper function:

@mcp.tool()
def custom_tool(target: str, options: str) -> Dict[str, Any]:
    """Custom tool wrapper"""
    if not validate_target(target):
        return {"error": "Invalid target"}
    
    target = sanitize_input(target)
    cmd = ["tool_name", target]
    
    result = run_command(cmd)
    return {"result": result}

Monitoring and Logging

Log Files

Logs are stored in the ./logs directory:

• access.log - All tool invocations
• error.log - Errors and exceptions
• security.log - Security-related events

Metrics

Monitor these metrics for security:

• Number of scans per target
• Frequency of aggressive scans
• Failed authentication attempts
• Unusual scan patterns

Compliance and Reporting

Generating Reports

The server can output results in various formats:

• JSON for programmatic processing
• Text for human reading
• XML for integration with other tools

Audit Trail

All operations are logged with:

• Timestamp
• User/client identifier
• Target system
• Tool and parameters used
• Results summary

Contributing

Contributions are welcome! Please:

1. Follow security best practices
2. Add appropriate input validation
3. Document new features
4. Test in isolated environments

License

This project is for educational purposes. Users are responsible for ensuring their use complies with all applicable laws and regulations.

Disclaimer

The authors and contributors of this tool are not responsible for any misuse or damage caused by this software. Use at your own risk and only on systems you have explicit permission to test.

Support

For questions and issues:

• Review the security tool's official documentation
• Check Docker and MCP framework documentation
• Ensure proper network configuration

Additional Resources

• OWASP Testing Guide
• Nmap Documentation
• Kali Linux Tools
• FastMCP Documentation

Remember: With great power comes great responsibility. Always use these tools ethically and legally.