API.md•11.3 kB
# MCP Kali Pentest - API Documentation
Complete reference for all available tools and resources.
## Table of Contents
- [Reconnaissance Tools](#reconnaissance-tools)
- [Vulnerability Scanning Tools](#vulnerability-scanning-tools)
- [Exploitation Tools](#exploitation-tools)
- [Brute Force Tools](#brute-force-tools)
- [Password Cracking Tools](#password-cracking-tools)
- [Network Analysis Tools](#network-analysis-tools)
- [Autonomous Tools](#autonomous-tools)
- [Resources](#resources)
---
## Reconnaissance Tools
### nmap_scan
Advanced port scanning and service detection using Nmap.
**Parameters:**
- `target` (string, required): Target IP address or hostname
- `scan_type` (string): Type of scan - `quick`, `full`, `stealth`, `aggressive`, `udp` (default: `quick`)
- `ports` (string): Port range (e.g., '1-1000', '80,443,8080')
- `scripts` (array): NSE scripts to run
**Example:**
```json
{
"target": "192.168.1.100",
"scan_type": "full",
"scripts": ["vuln", "default"]
}
```
**Returns:**
```json
{
"tool": "nmap",
"target": "192.168.1.100",
"success": true,
"findings": {
"hosts": [...],
"open_ports": ["22/tcp", "80/tcp", "443/tcp"],
"services": [...]
}
}
```
---
### nikto_scan
Web server vulnerability scanner.
**Parameters:**
- `target` (string, required): Target URL
- `ssl` (boolean): Use SSL/TLS (default: false)
- `port` (integer): Port number (default: 80)
**Example:**
```json
{
"target": "http://example.com",
"port": 80
}
```
---
### gobuster_scan
Directory and file brute-forcing.
**Parameters:**
- `target` (string, required): Target URL
- `wordlist` (string): Path to wordlist file
- `extensions` (array): File extensions to search
**Example:**
```json
{
"target": "http://example.com",
"wordlist": "/usr/share/wordlists/dirb/common.txt",
"extensions": ["php", "html", "txt"]
}
```
---
### dns_enum
DNS enumeration and subdomain discovery.
**Parameters:**
- `domain` (string, required): Target domain
- `record_types` (array): DNS record types (default: ["A", "AAAA", "MX", "NS", "TXT"])
**Example:**
```json
{
"domain": "example.com",
"record_types": ["A", "MX", "TXT"]
}
```
---
### enum4linux
SMB/Samba enumeration.
**Parameters:**
- `target` (string, required): Target IP address
- `username` (string): Username for authentication
- `password` (string): Password for authentication
**Example:**
```json
{
"target": "192.168.1.100",
"username": "guest"
}
```
---
## Vulnerability Scanning Tools
### sqlmap_scan
Automated SQL injection testing.
**Parameters:**
- `target` (string, required): Target URL
- `data` (string): POST data
- `cookie` (string): HTTP Cookie header
- `level` (integer): Test level 1-5 (default: 1)
- `risk` (integer): Risk level 1-3 (default: 1)
**Example:**
```json
{
"target": "http://example.com/page.php?id=1",
"level": 2,
"risk": 2
}
```
---
### nuclei_scan
Fast vulnerability scanner using templates.
**Parameters:**
- `target` (string, required): Target URL or IP
- `templates` (array): Specific templates to use
- `severity` (array): Severity levels - `critical`, `high`, `medium`, `low`, `info`
**Example:**
```json
{
"target": "http://example.com",
"severity": ["critical", "high", "medium"]
}
```
---
### wpscan
WordPress vulnerability scanner.
**Parameters:**
- `target` (string, required): WordPress site URL
- `enumerate` (string): What to enumerate - `vp` (vulnerable plugins), `ap` (all plugins), `tt` (themes), `cb` (config backups), `dbe` (database exports), `u` (users)
- `api_token` (string): WPScan API token
**Example:**
```json
{
"target": "http://wordpress.example.com",
"enumerate": "vp",
"api_token": "your-api-token"
}
```
---
### owasp_zap_scan
OWASP ZAP automated security scanner.
**Parameters:**
- `target` (string, required): Target URL
- `scan_type` (string): Scan type - `quick`, `full`, `api` (default: `quick`)
**Example:**
```json
{
"target": "http://example.com",
"scan_type": "full"
}
```
---
### ssl_scan
SSL/TLS configuration analyzer.
**Parameters:**
- `target` (string, required): Target hostname
- `port` (integer): Port number (default: 443)
**Example:**
```json
{
"target": "example.com",
"port": 443
}
```
---
## Exploitation Tools
### metasploit_search
Search Metasploit database for exploits.
**Parameters:**
- `query` (string, required): Search query
- `type` (string): Module type - `exploit`, `auxiliary`, `post`, `payload`
**Example:**
```json
{
"query": "apache",
"type": "exploit"
}
```
---
### searchsploit
Search Exploit-DB for known exploits.
**Parameters:**
- `query` (string, required): Search query (software name, CVE, etc.)
**Example:**
```json
{
"query": "wordpress 5.0"
}
```
---
## Brute Force Tools
### hydra_bruteforce
Network login brute-force tool.
**Parameters:**
- `target` (string, required): Target IP or hostname
- `service` (string, required): Service type - `ssh`, `ftp`, `http`, `rdp`, `smb`, `mysql`, `postgres`
- `username` (string): Single username or path to username list
- `password_list` (string, required): Path to password list
- `port` (integer): Custom port
**Example:**
```json
{
"target": "192.168.1.100",
"service": "ssh",
"username": "admin",
"password_list": "/usr/share/wordlists/rockyou.txt"
}
```
---
### ffuf_fuzz
Fast web fuzzer.
**Parameters:**
- `target` (string, required): Target URL with FUZZ keyword
- `wordlist` (string, required): Path to wordlist
- `method` (string): HTTP method - `GET`, `POST`, `PUT`, `DELETE` (default: `GET`)
**Example:**
```json
{
"target": "http://example.com/FUZZ",
"wordlist": "/usr/share/wordlists/dirb/common.txt",
"method": "GET"
}
```
---
## Password Cracking Tools
### john_crack
John the Ripper password cracker.
**Parameters:**
- `hash_file` (string, required): Path to file containing hashes
- `wordlist` (string): Path to wordlist
- `format` (string): Hash format (e.g., md5, sha256, ntlm)
**Example:**
```json
{
"hash_file": "/tmp/hashes.txt",
"wordlist": "/usr/share/wordlists/rockyou.txt",
"format": "md5"
}
```
---
### hashcat_crack
Advanced GPU-accelerated password recovery.
**Parameters:**
- `hash` (string, required): Hash to crack
- `hash_type` (integer, required): Hashcat hash type number
- `wordlist` (string): Path to wordlist
- `attack_mode` (integer): Attack mode - 0 (straight), 1 (combination), 3 (brute-force), 6 (hybrid wordlist+mask), 7 (hybrid mask+wordlist)
**Example:**
```json
{
"hash": "5f4dcc3b5aa765d61d8327deb882cf99",
"hash_type": 0,
"wordlist": "/usr/share/wordlists/rockyou.txt",
"attack_mode": 0
}
```
---
## Network Analysis Tools
### tcpdump_capture
Capture network packets.
**Parameters:**
- `interface` (string, required): Network interface
- `filter` (string): BPF filter
- `duration` (integer): Capture duration in seconds
- `output_file` (string): PCAP output file
**Example:**
```json
{
"interface": "eth0",
"filter": "tcp port 80",
"duration": 60,
"output_file": "/tmp/capture.pcap"
}
```
---
### snmp_check
SNMP enumeration tool.
**Parameters:**
- `target` (string, required): Target IP address
- `community` (string): SNMP community string (default: "public")
**Example:**
```json
{
"target": "192.168.1.1",
"community": "public"
}
```
---
## Autonomous Tools
### start_autonomous_pentest
Start a fully autonomous penetration test with AI decision-making.
**Parameters:**
- `target` (string, required): Target IP, hostname, or URL
- `scope` (array): Additional IPs/subnets in scope
- `rules_of_engagement` (object): Constraints and permissions
- `depth` (string): Test depth - `reconnaissance`, `vulnerability_scan`, `exploitation`, `post_exploitation` (default: `vulnerability_scan`)
**Example:**
```json
{
"target": "192.168.1.100",
"scope": ["192.168.1.100", "192.168.1.0/24"],
"depth": "vulnerability_scan",
"rules_of_engagement": {
"allow_exploitation": false,
"allow_post_exploitation": false,
"rate_limit": true,
"max_brute_force_attempts": 100
}
}
```
**Returns:**
```json
{
"session_id": "pentest_20241105_120000",
"status": "started",
"message": "Autonomous pentest initiated",
"initial_plan": {
"phases": [...],
"estimated_duration": "30-60 minutes"
}
}
```
---
### get_ai_suggestion
Get AI-powered suggestions for next steps.
**Parameters:**
- `session_id` (string, required): Pentest session ID
- `context` (string): Additional context for the AI
**Example:**
```json
{
"session_id": "pentest_20241105_120000",
"context": "Found open ports 22, 80, 443. What next?"
}
```
**Returns:**
```json
{
"session_id": "pentest_20241105_120000",
"suggestions": {
"recommended_action": "nuclei_scan",
"reasoning": "Web ports detected, scan for CVEs",
"parameters": {...},
"risk_level": "low",
"alternatives": [...]
}
}
```
---
### vulnerability_assessment
Comprehensive vulnerability assessment.
**Parameters:**
- `target` (string, required): Target to assess
- `assessment_type` (string): Assessment type - `web`, `network`, `wireless`, `comprehensive` (default: `comprehensive`)
**Example:**
```json
{
"target": "http://example.com",
"assessment_type": "web"
}
```
---
### generate_report
Generate comprehensive penetration test report.
**Parameters:**
- `session_id` (string, required): Pentest session ID
- `format` (string): Report format - `json`, `html`, `pdf`, `markdown` (default: `json`)
**Example:**
```json
{
"session_id": "pentest_20241105_120000",
"format": "html"
}
```
---
## Resources
### Session Resource
Access active pentest session data.
**URI:** `pentest://session/{session_id}`
**Example:**
```
pentest://session/pentest_20241105_120000
```
**Returns:**
```json
{
"id": "pentest_20241105_120000",
"target": "192.168.1.100",
"status": "running",
"findings": [...],
"timeline": [...]
}
```
---
### Report Resource
Access generated reports.
**URI:** `pentest://report/{report_id}`
**Example:**
```
pentest://report/report_pentest_20241105_120000
```
**Returns:**
```json
{
"id": "report_pentest_20241105_120000",
"name": "Penetration Test Report",
"executive_summary": {...},
"findings": {...},
"recommendations": [...]
}
```
---
## Error Handling
All tools return a consistent error format:
```json
{
"success": false,
"error": "Error description",
"tool": "tool_name"
}
```
Common error codes:
- Tool not found
- Invalid parameters
- Permission denied
- Timeout
- Network error
- Tool execution failed
---
## Rate Limiting
When `rate_limit` is enabled in rules of engagement:
- Maximum 10 requests per minute per tool
- Exponential backoff on failures
- Automatic retry with delay
---
## Best Practices
1. **Start with reconnaissance** before vulnerability scanning
2. **Use appropriate scan types** - don't use aggressive scans unnecessarily
3. **Check rules of engagement** before exploitation
4. **Monitor resource usage** - some scans are resource-intensive
5. **Review AI suggestions** before execution
6. **Generate reports** after each session
7. **Clean up artifacts** (PCAP files, temporary files)
---
## Support
For questions or issues:
- GitHub Issues: [Link]
- Documentation: [Link]
- Email: security@example.com