Skip to content

deruke/asi-mcp

BranchesTags

Repository files navigation

Attack Surface Intelligence (ASI-MCP)

AI-Powered Attack Surface Intelligence via Model Context Protocol

⚠️ DISCLAIMER: This is a proof of concept intended for testing and educational purposes only. Do not use in production environments. Use only against systems you have explicit authorization to test.

Overview

ASI-MCP is an intelligent security assessment platform that provides AI-driven orchestration of industry-standard penetration testing and vulnerability assessment tools through the Model Context Protocol (MCP). By exposing security tools as MCP-compatible services, ASI-MCP enables AI agents to conduct comprehensive security assessments with human-like reasoning and automation.

Key Features

Comprehensive Tool Coverage

  • Network reconnaissance and port scanning (nmap, masscan, rustscan)
  • Web application vulnerability scanning (nuclei, nikto, sqlmap)
  • Directory and file enumeration (gobuster, feroxbuster, ffuf, dirsearch)
  • Web application firewall detection (wafw00f)
  • Content discovery and crawling (gospider, katana, httpx)
  • Authentication testing and credential brute-forcing (hydra)
  • Domain reconnaissance (subfinder, theHarvester)
  • Binary analysis (strings, radare2, binwalk)

AI-Native Architecture

  • Model Context Protocol (MCP) integration for seamless AI agent interaction
  • Asynchronous job execution for long-running scans
  • Real-time status monitoring and progress tracking
  • Structured JSON output optimized for AI analysis

Enterprise Security

  • Target validation and safety controls
  • Comprehensive audit logging
  • Rate limiting and resource management
  • Non-root container execution
  • Health monitoring and metrics

Production-Ready

  • Docker containerization with Kali Linux base
  • FastAPI-based REST API
  • Persistent job storage
  • Built-in validation for all security tools

Architecture

ASI-MCP is built on a multi-layered architecture:

┌─────────────────────────────────────┐
│   AI Agent (Claude, n8n, etc.)     │
└─────────────┬───────────────────────┘
              │ MCP Protocol
┌─────────────▼───────────────────────┐
│      ASI-MCP Server (FastAPI)       │
│  ┌───────────────────────────────┐  │
│  │   Job Management & Queueing   │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  Security Tool Orchestration  │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  Validation & Safety Layer    │  │
│  └───────────────────────────────┘  │
└─────────────┬───────────────────────┘
              │
┌─────────────▼───────────────────────┐
│    Security Tools (Kali Linux)      │
│  nmap | nuclei | gobuster | nikto   │
│  sqlmap | hydra | gospider | ...    │
└─────────────────────────────────────┘

Quick Start

Prerequisites

  • Docker
  • Docker Compose
  • 4GB RAM minimum
  • 20GB disk space

Installation

  1. Clone the repository:
git clone https://github.com/deruke/asi-mcp.git
cd asi-mcp
  1. Build and start the container:
docker-compose up -d --build
  1. Verify the server is running:
curl http://localhost:3000/health

Expected response:

{"status":"healthy","service":"mcp-security-server","version":"1.0.0"}

Usage

Direct API Access

ASI-MCP exposes a JSON-RPC 2.0 API over HTTP for MCP tool invocation:

Example: Port Scan

curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "nmap_scan",
      "arguments": {
        "target": "scanme.nmap.org",
        "ports": "80,443",
        "scan_type": "fast"
      }
    }
  }'

Example: Web Vulnerability Scan

curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "nuclei_scan",
      "arguments": {
        "target": "https://example.com",
        "profile": "pentest"
      }
    }
  }'

Asynchronous Scanning

For long-running scans, use the asynchronous job API:

1. Start a scan job:

curl -X POST http://localhost:3000/scan/start \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "nmap_scan",
    "target": "scanme.nmap.org",
    "scan_type": "comprehensive"
  }'

Response:

{
  "job_id": "abc123",
  "status": "running",
  "tool": "nmap_scan",
  "target": "scanme.nmap.org"
}

2. Check job status:

curl http://localhost:3000/scan/status/abc123

3. Get results:

curl http://localhost:3000/scan/results/abc123

AI Agent Integration

ASI-MCP is designed for use with AI agents via MCP:

Example with n8n:

// Add MCP tool node
{
  "name": "ASI-MCP",
  "type": "mcp",
  "server": "http://localhost:3000",
  "tool": "nmap_scan",
  "arguments": {
    "target": "{{ $json.target }}",
    "ports": "1-1000"
  }
}

Example with Claude Desktop (config.json):

{
  "mcpServers": {
    "asi-mcp": {
      "url": "http://localhost:3000"
    }
  }
}

Available Tools

Network Reconnaissance

  • nmap_scan - Network port scanning and service detection
  • masscan_scan - High-speed port scanning
  • rustscan_scan - Fast port scanner with automatic nmap integration

Web Application Security

  • nuclei_scan - Vulnerability scanning with 8000+ templates (pentest profile default)
  • nikto_scan - Web server vulnerability scanner
  • sqlmap_scan - SQL injection detection and exploitation
  • gobuster_scan - Directory and file brute-forcing (raft wordlists)
  • feroxbuster_scan - Fast content discovery
  • ffuf_scan - Web fuzzing tool
  • dirsearch_scan - Web path scanner
  • httpx_scan - HTTP toolkit for probing
  • wafw00f_scan - Web application firewall detection
  • gospider_scan - Web crawler for URL and resource discovery
  • katana_scan - Next-generation web crawler
  • wpscan_scan - WordPress security scanner
  • http_request - HTTP client for content fetching and endpoint testing

Authentication & Credentials

  • hydra_bruteforce - Network authentication brute-forcing

Domain Intelligence

  • subfinder_scan - Subdomain discovery
  • theharvester_scan - OSINT and information gathering

Binary Analysis

  • strings_analyze - Extract readable strings from binaries
  • radare2_analyze - Binary analysis and reverse engineering
  • binwalk_analyze - Firmware analysis and extraction

Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
HOST=0.0.0.0
PORT=3000
LOG_LEVEL=INFO

# Security Settings
ALLOWED_TARGETS=*  # Comma-separated list or * for all
RATE_LIMIT_PER_MINUTE=60

# Job Management
MAX_CONCURRENT_JOBS=5
JOB_TIMEOUT_SECONDS=3600

Docker Configuration

Modify docker-compose.yml to customize:

services:
  mcp-security-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - LOG_LEVEL=INFO
    volumes:
      - ./logs:/app/logs
      - ./scans:/tmp/scans
    restart: unless-stopped

Tool-Specific Configuration

Nuclei

  • Default Profile: pentest (excludes DoS, fuzzing, and OSINT templates)
  • Templates Location: /home/mcpuser/nuclei-templates
  • Auto-update: Templates update on container build

Gobuster

  • Default Wordlist: raft-medium-directories.txt (30,000 entries)
  • Available Wordlists:
    • raft-small: 20,115 entries
    • raft-medium: 29,999 entries
    • raft-large: 62,281 entries
  • Location: /usr/share/seclists/Discovery/Web-Content/

Nikto

  • Timeout: 1800 seconds (30 minutes)
  • Max Scan Time: 1500 seconds (25 minutes with -maxtime)
  • Output Format: JSON with stdout fallback

Development

Local Development Setup

  1. Install Python dependencies:
pip install -r requirements.txt
  1. Run the server locally:
python -m uvicorn src.server:app --host 0.0.0.0 --port 3000 --reload
  1. Run tests:
pytest tests/

Project Structure

asi-mcp/
├── src/
│   ├── server.py           # FastAPI application and MCP server
│   ├── logging_config.py   # Logging configuration
│   ├── safety.py           # Target validation and safety controls
│   └── tools/
│       ├── network.py      # Network scanning tools
│       ├── web.py          # Web application security tools
│       └── binary.py       # Binary analysis tools
├── config/
│   └── logging.yaml        # Logging configuration
├── docs/
│   ├── fixes-2026-01-14.md
│   └── build-verification.md
├── tests/
│   └── test_*.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

Adding New Tools

  1. Create tool function in appropriate module (src/tools/)
  2. Add MCP tool definition to list_tools()
  3. Register handler in get_tools()
  4. Add target parameter mapping in src/server.py
  5. Update documentation

Example:

# src/tools/web.py
async def new_tool_scan(target: str) -> Dict[str, Any]:
    """New security tool implementation."""
    validator = get_validator()
    validator.validate_target(target)

    cmd = ["tool-command", target]
    result = await execute_command(cmd, timeout=300, tool_name="new_tool")

    return {
        "tool": "new_tool",
        "target": target,
        "success": result["success"],
        "output": result["stdout"]
    }

Security Considerations

Warning: ASI-MCP contains powerful security testing tools. Use responsibly and only against systems you have explicit authorization to test.

Best Practices

  1. Authorization: Always obtain written permission before scanning
  2. Scope: Define and respect engagement boundaries
  3. Rate Limiting: Configure appropriate limits to avoid service disruption
  4. Logging: Enable comprehensive audit logs for compliance
  5. Network Isolation: Run in isolated networks when possible
  6. Target Validation: Use allowlists for authorized targets

Legal Notice

Unauthorized security testing may be illegal in your jurisdiction. Users are solely responsible for ensuring compliance with applicable laws and regulations. The authors and contributors of ASI-MCP assume no liability for misuse of this software.

Performance

Resource Requirements

Minimum:

  • 2 CPU cores
  • 4GB RAM
  • 20GB disk space

Recommended:

  • 4+ CPU cores
  • 8GB+ RAM
  • 50GB+ disk space (for scan results)

Benchmarks

Typical scan times on recommended hardware:

  • nmap comprehensive scan (1000 ports): 5-15 minutes
  • nuclei pentest profile: 5-10 minutes
  • gobuster raft-medium: 2-5 minutes
  • nikto scan: 15-25 minutes
  • gospider crawl (depth 2): 1-3 minutes

Troubleshooting

Common Issues

Container won't start

# Check logs
docker logs mcp-security-server

# Rebuild without cache
docker-compose down
docker-compose up -d --build --no-cache

Tools not found

# Verify tool installation
docker exec mcp-security-server which nmap
docker exec mcp-security-server nuclei -version

Job timeout

# Increase timeout in .env
JOB_TIMEOUT_SECONDS=7200

# Restart container
docker-compose restart

Permission denied errors

# Check container user
docker exec mcp-security-server whoami

# Verify file permissions
docker exec mcp-security-server ls -la /tmp/scans

Roadmap

  • Integration with vulnerability management platforms
  • Scheduled scanning capabilities
  • Enhanced reporting and visualization
  • Support for distributed scanning
  • Integration with CI/CD pipelines
  • Additional OSINT and reconnaissance tools
  • Cloud security assessment capabilities

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/new-tool)
  3. Commit your changes (git commit -m 'Add new security tool')
  4. Push to the branch (git push origin feature/new-tool)
  5. Open a Pull Request

Development Guidelines

  • Follow PEP 8 style guidelines
  • Add tests for new functionality
  • Update documentation
  • Ensure all tests pass before submitting PR

License

MIT License

Copyright (c) 2026 ASI-MCP Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support

Acknowledgments

Built with:

  • Model Context Protocol (MCP) by Anthropic
  • Kali Linux security tools
  • FastAPI web framework
  • Docker containerization

Special thanks to the security research community and open-source tool maintainers.

ASI-MCP - AI-Powered Attack Surface Intelligence

About

MCP server that should work with n8n

Resources

Readme

License

View license
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages