MCP Security Tools Server

Production-ready HTTP API server untuk security testing & reconnaissance tools. Jalan atas FastAPI + uvicorn dengan support ngrok tunnel.

Fitur

• ✅ HTTP API endpoints — semua tools bisa dipanggil via REST
• ✅ Async-ready — FastAPI + pydantic
• ✅ Ngrok tunnel — expose server ke internet (optional)
• ✅ Tools integration: nmap, cariddi, paramspider, metasploit, web scraper
• ✅ Auto status check — cek tool mana yang tersedia di sistem
• ✅ Minimal dependencies — hanya 8 packages (vs 48 package sebelumnya)
• ✅ Tested — beneran jalan di Cloud Shell, local machine, Linux server

Quick Start

1. Clone & Install

git clone https://github.com/antonlarimaraton/mcp-accses.git
cd mcp-accses
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Setup Config (opsional)

Copy .env.example ke .env:

cp .env.example .env
# Edit .env untuk isi API keys kalau diperlukan

Ngrok token (opsional, hanya kalau mau tunnel):

# Edit ngrok_config.json dan isi authtoken
nano ngrok_config.json

3. Run Server

Localhost saja:

python3 mcp_server.py

Dengan ngrok tunnel:

python3 mcp_server.py --ngrok

Custom port:

python3 mcp_server.py --port=9000

Server listening di http://localhost:8000 (atau custom port). API docs ada di /docs.

API Endpoints

Health & Status

• GET / — Root endpoint, list semua endpoints
• GET /health — Health check
• GET /status — Server status + tool availability

Security Tools

• POST /tools/nmap — Network reconnaissance
• POST /tools/cariddi — API endpoint discovery
• POST /tools/paramspider — Parameter extraction
• POST /tools/scrape — Web scraping (requires SCRAPINGANT_API_KEY)
• POST /tools/metasploit — Exploitation framework

Contoh Penggunaan

Nmap scan:

curl -X POST http://localhost:8000/tools/nmap \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.1", "args": "-sV"}'

Cariddi (API discovery):

curl -X POST http://localhost:8000/tools/cariddi \
  -H "Content-Type: application/json" \
  -d '{"target": "https://api.example.com"}'

ParamSpider (parameter extraction):

curl -X POST http://localhost:8000/tools/paramspider \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Web scraping:

curl -X POST http://localhost:8000/tools/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Buka http://localhost:8000/docs di browser untuk interactive API documentation (Swagger UI).

Requirements

System Requirements

• OS: Linux (Ubuntu 20.04+), macOS, atau Windows (WSL)
• Python: 3.8+
• RAM: 512MB minimum

Optional Security Tools

Untuk menggunakan tool tertentu, install di system:

# Nmap
sudo apt-get install -y nmap

# Cariddi (requires Go)
go install github.com/edoardottt/cariddi/cmd/cariddi@latest

# ParamSpider (requires git)
git clone https://github.com/devanshbatham/paramspider.git tools/paramspider

# Metasploit Framework (heavy!)
# Lihat: https://docs.rapid7.com/metasploit/managing-the-database/

Configuration

Environment Variables (.env)

MCP_SERVER_PORT=8000
MCP_SERVER_HOST=0.0.0.0
SCRAPINGANT_API_KEY=your_key_here   # opsional
GITHUB_API_KEY=your_token_here      # opsional

Ngrok Configuration (ngrok_config.json)

{
  "authtoken": "your_ngrok_token_here",
  "region": "ap",
  "log_level": "info"
}

Daftar ngrok gratis di: https://dashboard.ngrok.com

Troubleshooting

"connection refused" / Server tidak jalan

# Check Python version
python3 --version    # Harus 3.8+

# Check dependencies
pip list | grep -E "fastapi|uvicorn|pydantic"

# Run dengan debug
python3 -u mcp_server.py

"Tool not found" (nmap, cariddi, etc)

• Server report status tools.nmap: false, dll
• Install tools secara manual (lihat section "Optional Security Tools" di atas)

Ngrok tunnel tidak jalan

# Check authtoken
cat ngrok_config.json | grep authtoken

# Test dengan CLI
ngrok http 8000

Permission denied

chmod +x mcp_server.py
python3 mcp_server.py    # Tidak perlu sudo

Architecture

┌─────────────────────────────────────────────┐
│  FastAPI + Uvicorn (HTTP Server)            │
├─────────────────────────────────────────────┤
│  ToolRunner (Core Logic)                     │
│  ├─ execute_nmap()                          │
│  ├─ execute_cariddi()                       │
│  ├─ execute_paramspider()                   │
│  ├─ scrape_with_api()                       │
│  ├─ execute_metasploit()                    │
│  └─ start_ngrok_tunnel()                    │
├─────────────────────────────────────────────┤
│  System Tools (optional)                    │
│  ├─ nmap CLI                                │
│  ├─ cariddi                                 │
│  ├─ paramspider.py                          │
│  └─ msfconsole                              │
├─────────────────────────────────────────────┤
│  External APIs (optional)                   │
│  ├─ ScrapingAnt (web scraping)              │
│  ├─ Ngrok (tunneling)                       │
│  └─ GitHub API                              │
└─────────────────────────────────────────────┘

Security Notes ⚠️

• Authorization Only — Hanya scan target yang kamu punya izin testing
• Legal Compliance — Pastikan comply dengan laws & regulations di region kamu
• API Keys — Jangan commit .env ke Git; gunakan .env.example untuk template
• Rate Limiting — Implement rate limit buat production usage
• Network — Gunakan VPN untuk remote testing
• Logging — Enable comprehensive logging untuk audit trail

Project Status

Komponen	Status	Notes
HTTP Server (FastAPI)	✅ Production	Tested di Cloud Shell, local, Linux
Nmap Integration	✅ Working	Require system nmap
Cariddi Integration	✅ Working	Require Go-installed tool
ParamSpider Integration	✅ Working	Include di repo atau install manual
Metasploit Integration	✅ Working	Require msfconsole installed
Web Scraper (ScrapingAnt)	✅ Working	Require API key
Ngrok Tunneling	✅ Working	Optional feature
Documentation	✅ Complete	Instruksi jelas & tested

File Structure

mcp-accses/
├── mcp_server.py              # Main server (HTTP API)
├── mcp_config.json            # Server configuration
├── ngrok_config.json          # Ngrok tunnel config (optional)
├── .env.example               # Environment variables template
├── requirements.txt           # Python dependencies (8 packages)
├── README.md                  # Ini file
├── LICENSE                    # MIT License
└── tools/                     # Optional: CLI tools
    ├── cariddi/
    ├── paramspider/
    └── ...

License

MIT License — Lihat LICENSE file untuk detil.

IMPORTANT: Tools ini untuk authorized security testing only. Unauthorized access ke computer systems adalah illegal. Users bertanggung jawab atas compliance dengan semua applicable laws.

Support & Contributing

• Issue: https://github.com/antonlarimaraton/mcp-accses/issues
• Pull Requests welcome!
• Contact maintainers untuk pertanyaan

---

Version: 1.0.0 | Last Updated: 2025-01-01