# 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

```bash
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`:
```bash
cp .env.example .env
# Edit .env untuk isi API keys kalau diperlukan
```

Ngrok token (opsional, hanya kalau mau tunnel):
```bash
# Edit ngrok_config.json dan isi authtoken
nano ngrok_config.json
```

### 3. Run Server

**Localhost saja:**
```bash
python3 mcp_server.py
```

**Dengan ngrok tunnel:**
```bash
python3 mcp_server.py --ngrok
```

**Custom port:**
```bash
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:**
```bash
curl -X POST http://localhost:8000/tools/nmap \
  -H "Content-Type: application/json" \
  -d '{"target": "192.168.1.1", "args": "-sV"}'
```

**Cariddi (API discovery):**
```bash
curl -X POST http://localhost:8000/tools/cariddi \
  -H "Content-Type: application/json" \
  -d '{"target": "https://api.example.com"}'
```

**ParamSpider (parameter extraction):**
```bash
curl -X POST http://localhost:8000/tools/paramspider \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

**Web scraping:**
```bash
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:

```bash
# 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)

```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)

```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
```bash
# 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
```bash
# Check authtoken
cat ngrok_config.json | grep authtoken

# Test dengan CLI
ngrok http 8000
```

### Permission denied
```bash
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