# Exploit Suggestions Engine - User Guide

**Last Updated:** 2025-11-18

---

## What is the Exploit Suggestions Engine?

The Exploit Suggestions Engine **automatically finds exploits for discovered services**. It analyzes your scan results, extracts service versions, and suggests matching CVEs and Metasploit modules from both a curated Metasploit knowledge base and the complete Exploit-DB database via searchsploit integration.

**Think of it as:**
"Hey, I found vsftpd 2.3.4 on port 21"
→ Exploit Engine: "Here's the backdoor exploit for that! Use `exploit/unix/ftp/vsftpd_234_backdoor`"

---

## Why Use Exploit Suggestions?

### Problems It Solves

❌ **Before:**
- Manual CVE searching for each service
- Time-consuming exploit research
- Easy to miss known vulnerabilities
- Tedious correlation between version → CVE → exploit

✅ **With Exploit Suggestions:**
- Automatic CVE matching for all services
- Metasploit modules ready to use
- Generic attack techniques for common services
- Ranked by severity (critical first)
- Saves hours of research time

---

## How It Works

### Step 1: Service Version Extraction

**Sources:**
- Nmap service scans (`-sV` flag)
- Banner grabbing
- Nikto server headers
- Application fingerprinting

**Example:**
```
Nmap discovers:
Port 21: vsftpd 2.3.4
Port 22: OpenSSH 7.2p2
Port 80: Apache 2.4.7
Port 3306: MySQL 5.7.12
```

---

### Step 2: Exploit Matching

**Dual-Source Database:**

**Static MSF Knowledge Base (~200 modules):**
- Curated Metasploit modules with metadata
- Pre-configured severity ratings
- Ready-to-use MSF commands
- Fast, offline matching

**Exploit-DB via SearchSploit (~30,000+ exploits):**
- Automatically queries searchsploit for each service
- 1-hour caching for performance
- Includes shellcode and proof-of-concept exploits
- Direct links to exploit-db.com
- **Enabled by default** (gracefully disabled if searchsploit not installed)

**Match Types:**
1. **Exact version match** - vsftpd 2.3.4 → CVE-2011-2523
2. **Version range match** - MySQL 5.5-5.7 → CVE-XXXX-YYYY
3. **Fuzzy product match** - "Apache httpd" → generic exploits
4. **Service-based techniques** - "Any MySQL" → mysql_login, mysql_hashdump

**Deduplication:**
- Removes duplicates by CVE (same vulnerability from both sources)
- Fuzzy title matching (>80% similarity)
- Prioritizes MSF modules when duplicates exist (more actionable)

---

### Step 3: Ranking

**Exploits ranked by:**
1. **Severity** (Critical > High > Medium > Low)
2. **Match quality** (Exact > Range > Generic)
3. **Source** (MSF modules prioritized - more actionable than raw exploits)
4. **CVE availability** (Exploits with CVE IDs ranked higher)

**Output:**
```
vsftpd 2.3.4 Exploit Suggestions:
1. [CRITICAL] vsftpd 2.3.4 Backdoor (CVE-2011-2523)
   MSF: exploit/unix/ftp/vsftpd_234_backdoor
   Match: Exact version

2. [MEDIUM] Anonymous FTP Access
   Technique: Test anonymous login
   Command: ftp 10.0.0.82
```

---

## Accessing Exploit Suggestions

### Option 1: Interactive Menu

```bash
# Start interactive dashboard
souleyez interactive

# Navigate to:
Intelligence → Exploit Suggestions
```

---

### Option 2: Command Line (Coming Soon)

```bash
# View all exploit suggestions
souleyez exploits suggest

# For specific host
souleyez exploits suggest --host 10.0.0.82

# For specific service
souleyez exploits suggest --service mysql
```

---

## SearchSploit Integration

### Installation

SearchSploit integration is **enabled by default** and will automatically activate if searchsploit is installed.

**Install searchsploit (Exploit-DB):**

```bash
# Debian/Ubuntu/Kali
sudo apt install exploitdb

# Update database
searchsploit --update
```

**Verify installation:**

```bash
searchsploit --version
# Should show: SearchSploit - Exploit-DB
```

### How It Works

1. **Automatic Querying**: When you view exploit suggestions, the engine automatically queries searchsploit for each discovered service
2. **Smart Queries**: Uses `product + version` (e.g., "vsftpd 2.3.4") for precise results
3. **Caching**: Results cached for 1 hour to avoid redundant queries
4. **Deduplication**: Removes duplicates between MSF KB and Exploit-DB
5. **Graceful Degradation**: If searchsploit not installed, falls back to static MSF knowledge base

### Performance

- **First query**: 0.5-2 seconds (queries Exploit-DB)
- **Cached queries**: <0.1 seconds (instant)
- **Cache duration**: 1 hour per service+version
- **Database size**: ~30,000+ exploits

### Configuration

SearchSploit integration is controlled via code:

```python
from souleyez.intelligence.exploit_suggestions import ExploitSuggestionEngine

# Default: searchsploit enabled (if installed)
engine = ExploitSuggestionEngine()

# Explicitly disable searchsploit (use only MSF KB)
engine = ExploitSuggestionEngine(use_searchsploit=False)
```

**Note:** The interactive menu always uses default settings (searchsploit enabled if available).

### Understanding Results

**SOURCE Column:**
- **MSF** = Curated Metasploit module (ready to use, actionable)
- **EDB** = Exploit-DB entry (proof-of-concept, may need adaptation)

**MODULE/EDB Column:**
- MSF modules: Short name (e.g., `vsftpd_234_backdoor`)
- EDB entries: ID number (e.g., `EDB-17491`)

**When to prefer MSF vs EDB:**
- **MSF modules**: Production-ready, well-tested, integrated with Metasploit
- **EDB exploits**: Research value, may require modification, PoC code

---

## Reading the Suggestions View

### Overview

```
┌─ Exploit Suggestions ──────────────────────────────┐
│ Engagement: acme-corp-pentest                      │
│ Hosts Analyzed: 8                                  │
│ Services with Exploits: 12                         │
│ Total Suggestions: 34                              │
└────────────────────────────────────────────────────┘
```

---

### Per-Host Breakdown

```
HOST: 10.0.0.82 (web-server.acme.local)
Attack Surface Score: 115
────────────────────────────────────────────────────────

Port 21 - FTP (vsftpd 2.3.4)
─────────────────────────────
  EXPLOITS (3 found):

  SEV   | EXPLOIT                         | CVE            | SOURCE | MODULE/EDB
  ──────┼─────────────────────────────────┼────────────────┼────────┼────────────────
  CRIT  | vsftpd 2.3.4 Backdoor Command   | CVE-2011-2523  | MSF    | vsftpd_234_backdoor
  CRIT  | vsftpd 2.3.4 Malicious Backdoor | CVE-2011-2523  | EDB    | EDB-17491
  MED   | FTP Login Brute Force           | -              | MSF    | ftp_login

  **Details:**
  [1] vsftpd 2.3.4 Backdoor (MSF)
      Match: Exact version
      Description: Malicious backdoor allows remote command execution
      Command: use exploit/unix/ftp/vsftpd_234_backdoor
               set RHOST 10.0.0.82
               exploit

  [2] vsftpd 2.3.4 Malicious Backdoor (Exploit-DB)
      Match: Exact version
      EDB Link: https://www.exploit-db.com/exploits/17491
      Description: Proof-of-concept for vsftpd backdoor

  TECHNIQUES (3 available):
  - Anonymous FTP Access
  - FTP Bounce Attack
  - Directory Traversal Testing

────────────────────────────────────────────────────────

Port 22 - SSH (OpenSSH 7.2p2)
─────────────────────────────
  EXPLOITS (1 found):

  [1] OpenSSH Username Enumeration
      Severity: LOW
      CVE: CVE-2018-15473
      MSF Module: auxiliary/scanner/ssh/ssh_enumusers
      Match: Version range (7.0-7.7 affected)
      Description: OpenSSH 7.0-7.7 leaks valid usernames via
                   timing attack.
      Command: use auxiliary/scanner/ssh/ssh_enumusers
               set RHOSTS 10.0.0.82
               run

  TECHNIQUES (2 available):
  - SSH Brute Force
  - SSH Key Enumeration

────────────────────────────────────────────────────────

Port 80 - HTTP (Apache 2.4.7)
─────────────────────────────
  EXPLOITS (3 found):

  [1] Apache Struts Remote Code Execution
      Severity: CRITICAL
      CVE: CVE-2017-5638
      MSF Module: exploit/multi/http/struts2_content_type_ognl
      Match: Fuzzy (if Struts detected)
      Description: Apache Struts 2.3.5-2.3.31 / 2.5-2.5.10 RCE
      Command: [Requires Struts verification first]

  [2] Shellshock (Bash CGI)
      Severity: HIGH
      CVE: CVE-2014-6271
      MSF Module: exploit/multi/http/apache_mod_cgi_bash_env_exec
      Match: Generic (if CGI detected)
      Description: Bash environment variable injection
      Command: [Test for CGI scripts first]

  TECHNIQUES (6 available):
  - Directory Brute Force (Gobuster)
  - SQL Injection Testing (SQLMap)
  - XSS Testing
  - File Upload Testing
  - Authentication Bypass
  - Nikto Vulnerability Scan

────────────────────────────────────────────────────────

Port 3306 - MySQL (5.7.12)
─────────────────────────────
  EXPLOITS (2 found):

  [1] MySQL Remote Root Authentication Bypass
      Severity: HIGH
      CVE: CVE-2012-2122
      MSF Module: auxiliary/scanner/mysql/mysql_authbypass_hashdump
      Match: Version range (5.1.x-5.5.23 affected)
      Description: Authentication bypass via repeated login attempts
      Note: Your version may not be vulnerable (5.7.12 > 5.5.23)

  TECHNIQUES (4 available):
  - MySQL Default Credentials (root/admin)
  - MySQL Brute Force
  - MySQL Hash Dump (if authenticated)
  - MySQL UDF Exploitation (if FILE privilege)

```

---

## Severity Levels

### CRITICAL (Red)

**Criteria:**
- Remote code execution (RCE)
- Known backdoors
- Authentication bypass
- Exact version match

**Examples:**
- vsftpd 2.3.4 backdoor
- Struts RCE
- EternalBlue (MS17-010)

**Priority:** Exploit immediately!

---

### HIGH (Orange)

**Criteria:**
- Privilege escalation
- Information disclosure (sensitive)
- DoS attacks
- Version range match

**Examples:**
- OpenSSH username enumeration
- MySQL authentication bypass
- Sudo vulnerabilities

**Priority:** Test soon, likely exploitable

---

### MEDIUM (Yellow)

**Criteria:**
- Brute-force opportunities
- Generic attack techniques
- Configuration issues

**Examples:**
- FTP brute force
- Weak credentials
- Directory listing enabled

**Priority:** Test when time permits

---

### LOW (Blue)

**Criteria:**
- Information gathering
- Minor configuration issues
- Fuzzy matches (may not apply)

**Examples:**
- Banner disclosure
- Server version exposed
- Generic service techniques

**Priority:** Document for report

---

## Match Types

### Exact Version Match (100% confidence)

**What it means:** The exact service version is known to be vulnerable

**Example:**
```
Service: vsftpd 2.3.4
CVE: CVE-2011-2523
Match: Exact (vsftpd 2.3.4)
Confidence: 100%
```

**Action:** Exploit with confidence!

---

### Version Range Match (75-95% confidence)

**What it means:** Service version falls within known vulnerable range

**Example:**
```
Service: OpenSSH 7.2p2
CVE: CVE-2018-15473
Match: Range (7.0 - 7.7 affected)
Confidence: 90%
```

**Action:** Test the exploit, may work

---

### Fuzzy Product Match (30-60% confidence)

**What it means:** Product matches, but version unclear or range uncertain

**Example:**
```
Service: Apache httpd
CVE: CVE-2017-5638 (Struts RCE)
Match: Fuzzy (Struts may be installed)
Confidence: 40%
```

**Action:** Verify product first, then exploit

---

### Generic Technique (N/A confidence)

**What it means:** Common attack technique for this service type

**Example:**
```
Service: MySQL (any version)
Technique: mysql_login brute force
Match: Generic (all MySQL)
```

**Action:** Always worth trying

---

## Using Exploit Suggestions

### Method 1: Copy MSF Command

**From Suggestions:**
```
MSF Module: exploit/unix/ftp/vsftpd_234_backdoor
Command: use exploit/unix/ftp/vsftpd_234_backdoor
         set RHOST 10.0.0.82
         exploit
```

**Execute:**
```bash
# Start Metasploit
msfconsole

# Paste suggested commands
use exploit/unix/ftp/vsftpd_234_backdoor
set RHOST 10.0.0.82
exploit
```

---

### Method 2: Queue via SoulEyez

**For MSF exploits:**
```bash
# Enqueue Metasploit exploit
souleyez jobs enqueue msf_exploit exploit/unix/ftp/vsftpd_234_backdoor \
  --args "RHOST=10.0.0.82"
```

**For auxiliary modules:**
```bash
# Enqueue MSF auxiliary
souleyez jobs enqueue msf_auxiliary auxiliary/scanner/ssh/ssh_enumusers \
  --args "RHOSTS=10.0.0.82"
```

---

### Method 3: One-Click Exploit (Future)

**Coming soon:**
- Press 'e' on suggested exploit
- Automatically queues job with correct parameters
- Tracks results in Attack Surface Dashboard

---

## Generic Attack Techniques

**For services without specific CVEs, use generic techniques:**

### FTP Techniques
- Anonymous login test
- Brute-force authentication
- FTP bounce attack
- Directory traversal

### SSH Techniques
- Brute-force credentials
- Public key enumeration
- User enumeration

### HTTP/HTTPS Techniques
- Directory brute-force (Gobuster)
- SQL injection testing (SQLMap)
- XSS testing
- Authentication bypass
- File upload vulnerabilities

### MySQL/PostgreSQL Techniques
- Default credentials testing
- Brute-force authentication
- Hash dumping (if authenticated)
- UDF exploitation

### SMB Techniques
- Null session enumeration
- Share enumeration
- Brute-force credentials
- EternalBlue (specific versions)

---

## Best Practices

### ✅ Do

1. **Verify Version First**
   - Re-scan if version unclear
   - Check service banners manually
   - Confirm before exploiting

2. **Start with Exact Matches**
   - Critical + Exact = Highest success rate
   - Test these first
   - Document results

3. **Test Generic Techniques Too**
   - Even without CVEs, brute-force may work
   - Default credentials are common
   - Configuration issues are real

4. **Document What You Try**
   - Track which exploits attempted
   - Note which failed and why
   - Update findings with results

### ❌ Don't

1. **Don't Blindly Trust Fuzzy Matches**
   - Verify product/version first
   - May be false positive
   - Research before exploiting

2. **Don't Skip Version Verification**
   - "Apache 2.4" is vague
   - Get exact version (2.4.7, 2.4.29, etc.)
   - Re-scan with `-sV` if needed

3. **Don't Ignore Older CVEs**
   - Systems may be unpatched
   - Old exploits still work
   - Test even if CVE is from 2012

---

## Exploit Suggestions + Other Features

### Works Great With:

**Attack Surface Dashboard**
- Suggestions: "Here's how to exploit it"
- Attack Surface: "Here's what needs exploiting"

**Evidence Vault**
- Suggestions: Provides exploit commands
- Evidence: Captures exploitation attempts

**Correlation Engine**
- Suggestions: Recommends next attack
- Correlation: Tracks if you already tried it

---

## Common Questions

### Q: Why no exploits for some services?

**A:** Several reasons:
1. **Service is up-to-date** - No known vulnerabilities
2. **Version not extracted** - Re-scan with `-sV`
3. **Obscure service** - Not in CVE database
4. **Generic service** - Use techniques instead

**Solution:** Always try generic attack techniques!

---

### Q: Exploit suggestion says CVE-XXXX but it doesn't work?

**A:** Possible reasons:
1. **Patch applied** - System patched without version update
2. **Wrong product** - Version matched but different product
3. **Configuration prevents** - Firewall/IPS blocking
4. **Exploit unreliable** - Some exploits have low success rate

**Solution:** Try alternative exploits, check MSF exploit info

---

### Q: Can I add custom exploits to the knowledge base?

**A:** Not yet, but coming soon!

**Workaround:**
1. Use suggestions as inspiration
2. Manually test custom exploits
3. Document in findings
4. Share with team via GitHub issues

---

### Q: How often is the CVE database updated?

**A:** Currently uses a static knowledge base (200+ exploits).

**Future:** Automatic CVE database updates via API integration.

---

## Troubleshooting

### No Exploits Showing Up

**Possible causes:**
1. **No services scanned** - Run Nmap first
2. **Version not detected** - Use `nmap -sV`
3. **Services are patched** - No known vulns

**Solution:**
```bash
# Re-scan with version detection
souleyez jobs enqueue nmap 10.0.0.82 --args "-sV -sC"

# Check if services detected
souleyez services list
```

---

### Wrong Service Versions

**Possible causes:**
1. **Nmap fingerprint incorrect**
2. **Banner modified** - Admin changed version string
3. **Service behind proxy** - Seeing proxy version

**Solution:**
- Manual verification (connect to service)
- Check HTTP headers directly
- Try banner grabbing: `nc 10.0.0.82 21`

---

## Next Steps

**Learn More:**
- [Attack Surface Dashboard](attack-surface.md) - Track what to exploit
- [Metasploit Integration](../tools-reference.md#metasploit) - Using MSF with SoulEyez
- [Workflows Guide](workflows.md) - Complete exploitation workflows

**Related Commands:**
```bash
souleyez interactive                       # Access Exploit Suggestions
souleyez services list                     # See discovered services
souleyez jobs enqueue msf_exploit [module] # Queue MSF exploit
```

---

**Need Help?** Check `docs/user-guide/troubleshooting.md` or open an issue on GitHub.
