sast-mcp by Sengtocxoen - MCP Server

MCP-SAST-Server

A comprehensive Model Context Protocol (MCP) server that integrates multiple SAST (Static Application Security Testing) tools with Claude Code AI, enabling automated security analysis and vulnerability scanning directly from your AI assistant.

Overview

This project provides a bridge between Claude Code and industry-standard security scanning tools, allowing developers to perform comprehensive security analysis through natural language commands.

Key Features

23+ Security Tools Integration:
- SAST: Semgrep, Bandit, ESLint Security, Gosec, Brakeman, Graudit, Bearer
- Secrets: TruffleHog, Gitleaks
- Dependencies: Safety, npm audit, OWASP Dependency-Check, Snyk
- IaC: Checkov, tfsec, Trivy
- Kali Tools: Nikto, Nmap, SQLMap, WPScan, DIRB, Lynis, ClamAV
Multi-Process Backend ⚡: High-performance parallel execution with true CPU parallelism
- ProcessPoolExecutor for isolated process execution
- 3.3x faster performance with parallel scans
- Configurable parallelism (1-16+ concurrent scans)
- Process isolation for enhanced stability
- Resource monitoring and health checks
Enhanced Accuracy & Reliability 🎯: Advanced validation and error handling
- Automatic result validation with checksum verification
- Retry logic with exponential backoff
- Error categorization with remediation hints
- Process health monitoring (memory, CPU, threads)
TOON Format Integration 🎒: Automatic conversion to Token-Oriented Object Notation for LLM-optimized analysis
- 30-60% token reduction compared to JSON
- Automatic TOON format output for all scans
- AI-ready payloads for future LLM analysis
- Significant cost savings on AI API usage
Background Processing: All scans run asynchronously in the background with job management
Automatic File Output: Results automatically saved to files with configurable output directory (JSON + TOON + AI payload)
Job Management API: Track scan status, retrieve results, cancel jobs, and list all scans
AI Analysis Ready: Prepared for future AI-powered scan summarization and decision support
MCP Protocol: Seamless integration with Claude Code AI
Remote Execution: Run security tools on a dedicated security VM (Kali Linux) while working on Windows
Path Resolution: Automatic Windows ↔ Linux path mapping for cross-platform operation
Flexible Architecture: Choose between full-featured or lightweight server
Comprehensive Coverage: Code analysis, secret scanning, dependency checking, IaC security, web security, network scanning, malware detection

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│  Claude Code    │  MCP    │  MCP Client      │  HTTP   │  SAST Server    │
│  (Windows)      │◄───────►│  client/         │◄───────►│  server/        │
│                 │         │  sast_mcp_client │         │  (Kali Linux)   │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                                                  │
                                                                  ▼
                                                          ┌─────────────────┐
                                                          │  Security Tools │
                                                          │  (installed via │
                                                          │  tools/install) │
                                                          └─────────────────┘

Supported Tools

Code Analysis

Semgrep - Multi-language static analysis (30+ languages)
Bandit - Python security scanner
ESLint Security - JavaScript/TypeScript security linting
Gosec - Go security checker
Brakeman - Ruby on Rails security scanner
Graudit - Grep-based source code auditing
Bearer - Security and privacy risk scanner

Secret Detection

TruffleHog - Secret scanner for git repos and filesystems
Gitleaks - Fast secret detection for git repositories

Dependency Scanning

Safety - Python dependency vulnerability checker
npm audit - Node.js dependency security audit
OWASP Dependency-Check - Multi-language dependency scanner
Snyk - Modern dependency and container scanner

Infrastructure as Code

Checkov - Terraform, CloudFormation, Kubernetes, Dockerfile scanner
tfsec - Terraform security scanner
Trivy - Container and IaC vulnerability scanner

Kali Linux Security Tools

Nikto - Web server vulnerability scanner
Nmap - Network and port scanner
SQLMap - SQL injection detection and exploitation
WPScan - WordPress security scanner
DIRB - Web content discovery scanner
Lynis - System auditing and hardening tool
ClamAV - Antivirus and malware scanner

Installation

Prerequisites

Windows Machine (Client):

Python 3.8+
Claude Code installed

Linux Machine (Server - Kali Linux recommended):

Python 3.8+
Security tools installed (see Tool Installation)

Quick Start

1. Clone the Repository

git clone https://github.com/your-username/MCP-SAST-Server.git
cd MCP-SAST-Server

2. Install Python Dependencies

pip install -r requirements.txt

3. Configure Server (Optional)

Copy the example environment file and customize:

cp .env.example .env
# Edit .env with your settings (port, paths, timeouts)

4. Start SAST Server (on Kali Linux)

Option A: Full-Featured Server (recommended for complete functionality)

python3 server/sast_server.py --port 6000

Option B: Simple Server (no external dependencies, basic functionality)

python3 server/simple_sast_server.py --port 6000

5. Configure Claude Code (on Windows)

Option A: Use the example configuration

Open config.example.json in the repository
Copy the configuration that matches your setup
Add it to your .claude.json file
Update the paths and server URL

Option B: Manual configuration

Add the MCP server configuration to your .claude.json:

{
  "mcpServers": {
    "sast_tools": {
      "type": "stdio",
      "command": "python",
      "args": [
        "/path/to/sast-mcp/client/sast_mcp_client.py",
        "--server",
        "http://YOUR_KALI_IP:6000"
      ]
    }
  }
}

Important: Update these values:

/path/to/sast-mcp/client/sast_mcp_client.py - Full path to the MCP client script
YOUR_KALI_IP - Your Kali Linux machine's IP address (e.g., 192.168.1.100)
Port 6000 - Change if you configured a different port

Windows Path Examples:

C:/Projects/sast-mcp/client/sast_mcp_client.py
F:/work/sast-mcp/client/sast_mcp_client.py

Linux/Mac Path Examples:

/home/user/sast-mcp/client/sast_mcp_client.py
~/projects/sast-mcp/client/sast_mcp_client.py

6. Verify Installation

On Kali Linux:

curl http://localhost:6000/health

In Claude Code:

@sast_tools

Check the SAST server health and show me available tools

Usage Examples

Security Scanning

Scan Python code for vulnerabilities:

@sast_tools

Run a Bandit scan on F:/work/MyProject/backend with high severity filter

Multi-language security audit:

@sast_tools

Use Semgrep with OWASP Top 10 rules to scan F:/work/MyProject

Find secrets in repository:

@sast_tools

Scan F:/work/MyProject for leaked secrets using TruffleHog

Dependency Checking

Check Python dependencies:

@sast_tools

Run Safety check on F:/work/MyProject/requirements.txt

Audit Node.js packages:

@sast_tools

Run npm audit on F:/work/MyProject/frontend with critical severity

Infrastructure Security

Scan Terraform files:

@sast_tools

Use Checkov to scan Terraform configurations in F:/work/MyProject/terraform

Check Docker security:

@sast_tools

Scan F:/work/MyProject/Dockerfile with Trivy

Kali Security Tools

Scan web server with Nikto:

@sast_tools

Run Nikto scan on https://example.com with SSL and save results to /tmp/nikto-scan.txt

Network scanning with Nmap:

@sast_tools

Use Nmap to scan 192.168.1.1 for open ports 1-1000 and save results

SQL injection testing:

@sast_tools

Test https://example.com/login.php for SQL injection using SQLMap

WordPress security scan:

@sast_tools

Scan https://wordpress-site.com with WPScan to enumerate vulnerable plugins

Web content discovery:

@sast_tools

Run DIRB on https://example.com to discover hidden directories and files

System audit:

@sast_tools

Run Lynis system audit to check security hardening

Malware scanning:

@sast_tools

Scan F:/work/MyProject with ClamAV antivirus to detect malware

Tool Installation

Quick Installation (Recommended)

We provide an automated installation script that installs all required tools:

# On your Kali Linux machine
cd /path/to/sast-mcp
sudo bash tools/install_tools.sh

The script will:

✅ Update system packages
✅ Install Python, Node.js, Ruby, and Go
✅ Install all 23+ security tools automatically
✅ Install Python dependencies (Flask, MCP SDK)
✅ Verify all installations
✅ Show you next steps

Installation takes 5-15 minutes depending on your internet speed.

⚠ Having installation issues? Common problems include stuck downloads, version conflicts, or network timeouts. Try running the script again or install tools manually.

Manual Installation

If you prefer to install tools manually:

Installing Security Tools on Kali Linux

Many tools come pre-installed on Kali Linux. For missing tools:

Semgrep:

pip3 install semgrep

Bandit:

pip3 install bandit

TruffleHog:

pip3 install trufflehog

Gitleaks:

wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz
tar -xzf gitleaks_8.18.0_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

Checkov:

pip3 install checkov

Safety:

pip3 install safety

Trivy:

wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
echo "deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt update
sudo apt install trivy

Installing Kali Linux Tools

Most Kali tools come pre-installed on Kali Linux. For missing tools:

Nikto:

sudo apt install nikto

Nmap:

sudo apt install nmap

SQLMap:

sudo apt install sqlmap

WPScan:

sudo gem install wpscan
# Or
sudo apt install wpscan

DIRB:

sudo apt install dirb

Lynis:

sudo apt install lynis

Snyk:

npm install -g snyk
# Or download from https://github.com/snyk/cli

ClamAV:

sudo apt install clamav clamav-daemon
sudo freshclam  # Update virus definitions

For a complete installation guide, refer to each tool's official documentation.

Configuration

Server Configuration (.env file)

The server can be configured using environment variables or a .env file:

Using .env file (recommended):

# Copy the example file
cp .env.example .env

# Edit .env with your settings
nano .env

Available Configuration Options:

# Server Port (default: 6000)
API_PORT=6000

# Debug Mode (default: 0)
DEBUG_MODE=0

# Command Timeout in seconds (default: 3600 / 1 hour)
COMMAND_TIMEOUT=3600

# Max timeout limit (default: 86400 / 24 hours)
# For scans that take days, increase this value
# Examples: 259200 (3 days), 604800 (1 week)
MAX_TIMEOUT=86400

# Tool-Specific Timeouts (in seconds)
# Customize timeout for each security tool based on your needs
NIKTO_TIMEOUT=3600        # Web server scanning
NMAP_TIMEOUT=7200         # Network/port scanning
SQLMAP_TIMEOUT=7200       # SQL injection testing
WPSCAN_TIMEOUT=3600       # WordPress scanning
DIRB_TIMEOUT=7200         # Web content discovery
LYNIS_TIMEOUT=1800        # System auditing
SNYK_TIMEOUT=3600         # Dependency scanning
CLAMAV_TIMEOUT=14400      # Malware scanning (4 hours)
SEMGREP_TIMEOUT=7200      # Code analysis
BANDIT_TIMEOUT=1800       # Python security
TRUFFLEHOG_TIMEOUT=3600   # Secret detection

# Path Mapping (for Windows/Linux cross-platform)
MOUNT_POINT=/mnt/work
WINDOWS_BASE=F:/

# Multi-Process Backend Configuration
USE_MULTIPROCESSING=1           # Enable multi-process backend (default: 1)
MAX_PARALLEL_SCANS=4            # Number of concurrent scans (default: 4)
MAX_PROCESS_WORKERS=8           # Process pool size (default: CPU count - 1)
PROCESS_MEMORY_LIMIT_MB=2048    # Memory limit per process (default: 2048)
SCAN_WAIT_TIMEOUT=1800          # Scan slot wait timeout (default: 1800 / 30 min)

# Retry and Validation Configuration
MAX_RETRY_ATTEMPTS=2            # Retry attempts for failed scans (default: 2)
RETRY_BACKOFF_BASE=2.0          # Exponential backoff multiplier (default: 2.0)
ENABLE_RESULT_VALIDATION=1      # Enable result validation (default: 1)
ENABLE_CHECKSUM_VERIFICATION=1  # Enable checksum verification (default: 1)
MIN_RESULT_SIZE_BYTES=10        # Minimum valid result size (default: 10)

Timeout Configuration Tips:

For large-scale or comprehensive security scans, you may need to increase timeouts:

Large codebases (>100K LOC): Increase SEMGREP_TIMEOUT to 14400 (4 hours)
Full network scans: Set NMAP_TIMEOUT to 28800 (8 hours) or higher
Thorough SQL injection testing: Use SQLMAP_TIMEOUT of 21600 (6 hours)
Complete malware scans: Set CLAMAV_TIMEOUT to 43200 (12 hours)
Multi-day scans: Increase MAX_TIMEOUT to 259200 (3 days) or more

The server saves partial results if a scan times out, so you won't lose all data.

Using environment variables directly:

export API_PORT=6000
export DEBUG_MODE=1
export MOUNT_POINT=/mnt/work
export WINDOWS_BASE=F:/

Client Configuration (config.example.json)

For Claude Code configuration, see config.example.json which includes:

Windows with local Kali VM example
Windows with remote Kali server example
Linux/Mac configuration example

Simply copy the appropriate configuration to your .claude.json and update the paths and IP address.

Path Resolution

The server automatically resolves Windows paths to Linux mount paths:

F:/MyProject/file.txt → /mnt/work/MyProject/file.txt
F:\work\Project\scan.json → /mnt/work/work/Project/scan.json
F:/scan-results.txt → /mnt/work/scan-results.txt

Default mapping: F:/ (Windows) ↔ /mnt/work (Linux)

Configure your mount point using environment variables if different.

API Endpoints

Health Check

GET /health

SAST Tools

POST /api/sast/semgrep
POST /api/sast/bandit
POST /api/sast/bearer
POST /api/sast/graudit
POST /api/sast/gosec
POST /api/sast/brakeman
POST /api/sast/eslint-security

Secret Scanning

POST /api/secrets/trufflehog
POST /api/secrets/gitleaks

Dependency Scanning

POST /api/dependencies/safety
POST /api/dependencies/npm-audit
POST /api/dependencies/dependency-check

Infrastructure as Code

POST /api/iac/checkov
POST /api/iac/tfsec

Container Security

POST /api/container/trivy

Custom Commands

POST /api/command

Background Job Management

GET  /api/jobs                  # List all jobs
GET  /api/jobs/{job_id}         # Get job status
GET  /api/jobs/{job_id}/result  # Get job result
POST /api/jobs/{job_id}/cancel  # Cancel a job
POST /api/jobs/cleanup           # Cleanup old jobs

Background Processing

All security scans now run in the background by default, allowing you to:

Start multiple scans concurrently
Continue working while scans execute
Retrieve results when convenient
Track scan progress and status

How It Works

Submit a Scan: When you request a scan (e.g., Semgrep), the server immediately returns a job ID
Background Execution: The scan runs in the background (up to 10 concurrent jobs by default)
Automatic File Storage: Results are automatically saved to /var/sast-mcp/scan-results/ (or your configured directory)
Retrieve Results: Use the job ID to check status and retrieve results

Example Workflow

1. Start a Semgrep scan:

curl -X POST http://localhost:6000/api/sast/semgrep \
  -H "Content-Type: application/json" \
  -d '{
    "target": "/path/to/code",
    "config": "auto",
    "output_format": "json"
  }'

Response:

{
  "success": true,
  "message": "Scan job submitted successfully",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_status": "pending",
  "output_file": "/var/sast-mcp/scan-results/semgrep_20250104_143022_a1b2c3d4.json",
  "check_status_url": "/api/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "get_result_url": "/api/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result"
}

2. Check scan status:

curl http://localhost:6000/api/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response:

{
  "success": true,
  "job": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tool_name": "semgrep",
    "status": "running",
    "created_at": "2025-01-04T14:30:22",
    "started_at": "2025-01-04T14:30:23",
    "output_file": "/var/sast-mcp/scan-results/semgrep_20250104_143022_a1b2c3d4.json",
    "progress": 0,
    "duration_seconds": 45.2
  }
}

3. Get results when complete:

curl http://localhost:6000/api/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result

Response:

{
  "success": true,
  "status": "completed",
  "job": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "duration_seconds": 127.5
  },
  "result": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tool_name": "semgrep",
    "started_at": "2025-01-04T14:30:23",
    "completed_at": "2025-01-04T14:32:30",
    "scan_result": {
      "stdout": "...",
      "summary": {
        "total_findings": 15,
        "total_errors": 0
      }
    }
  }
}

Configuration

Configure background processing in your .env file:

# Default directory for scan results
DEFAULT_OUTPUT_DIR=/var/sast-mcp/scan-results

# Maximum concurrent scan jobs
MAX_WORKERS=10

# Keep job metadata for 72 hours (3 days)
JOB_RETENTION_HOURS=72

Custom Output Locations

You can specify a custom output file for any scan:

{
  "target": "/path/to/code",
  "output_file": "F:/my-scans/custom-name.json"
}

If not specified, files are automatically named: {tool}_{timestamp}_{job_id}.json

Synchronous Mode (Legacy)

For backward compatibility, you can run scans synchronously:

{
  "target": "/path/to/code",
  "background": false
}

This will block until the scan completes (not recommended for long-running scans).

Project Structure

sast-mcp/
├── client/
│   └── sast_mcp_client.py      # MCP client for Claude Code integration
├── server/
│   ├── sast_server.py          # Full-featured SAST server (recommended)
│   └── simple_sast_server.py   # Lightweight alternative (minimal dependencies)
├── tools/
│   ├── install_tools.sh        # Automated security tools installation script
│   ├── toon_converter.py       # TOON format converter for LLM optimization
│   └── ai_analysis.py          # AI analysis utilities (future feature)
├── requirements.txt            # Python dependencies
├── .env.example                # Server configuration template
├── config.example.json         # Claude Code configuration examples
├── LICENSE                     # MIT License
└── README.md                   # This documentation

Simple & Clean Architecture

client/ - MCP client that connects Claude Code to the SAST server via HTTP

server/ - Two server options:

sast_server.py - Full-featured with TOON conversion and all features
simple_sast_server.py - Minimal dependencies, basic functionality

tools/ - Utilities and installation scripts:

install_tools.sh - Automated installation of all 23+ security tools
toon_converter.py - TOON format converter (30-60% token reduction)
ai_analysis.py - AI-powered scan analysis (coming soon)

Configuration files:

requirements.txt - Python package dependencies
.env.example - Server environment configuration template
config.example.json - Claude Code MCP configuration examples

Troubleshooting

Connection Issues

Problem: Cannot connect to SAST server

Solution:

Verify server is running: curl http://KALI_IP:6000/health
Check firewall settings on Kali Linux
Ensure IP address in .claude.json is correct
Check network connectivity between Windows and Kali

Path Resolution Issues

Problem: Scans fail with "path not found"

Solution:

Verify Windows share is mounted on Linux: ls /mnt/work
Check mount point configuration matches MOUNT_POINT environment variable
Ensure paths use forward slashes in .claude.json

Tool Not Available

Problem: Health check shows tool as unavailable

Solution:

Install missing tools (see Tool Installation)
Verify tool is in PATH: which semgrep
Test tool manually: semgrep --version

Security Considerations

Network Security: Use firewall rules to restrict access to SAST server port
Authentication: Consider adding API authentication for production use
Secrets: Never commit API keys or credentials to the repository
Isolation: Run SAST server in isolated VM or container
Updates: Regularly update security tools to get latest vulnerability signatures

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Acknowledgments

Model Context Protocol - MCP specification
Anthropic - Claude AI and Claude Code
All the amazing open-source security tool maintainers

Support

For issues, questions, or contributions:

Issues: GitHub Issues
Discussions: GitHub Discussions

Roadmap

Add authentication/authorization
Implement scan result caching
Add webhook notifications
Create web dashboard for scan results
Support for additional SAST tools
Docker containerization
CI/CD integration examples

Built with ❤️ for secure code development