# MSF Integration - Quick Start & Warning

## ⚠️ Read This First

The MSF integration accesses Metasploit's PostgreSQL database directly for fast data import. This has **important trade-offs**:

### ✅ Benefits
- Fast bulk import of hosts, services, vulns, creds, sessions
- Works without MSF console running
- Import historical engagement data
- Automatic exploit result tracking

### ⚠️ Risks
- **May break with MSF updates** - Direct database access means schema changes can break functionality
- **Tested with MSF 6.2-6.4** - Newer versions may require code updates
- **Not officially supported by MSF** - Uses internal database structure, not public API

### 🛡️ Protections Built-In
- ✅ Automatic version checking on connect
- ✅ Schema validation before operations
- ✅ Graceful error handling with helpful messages
- ✅ Suggests XML export as fallback when errors occur
- ✅ Optional dependencies (won't affect base installation)

---

## Quick Decision Guide

**Use MSF Database Integration if:**
- You run MSF locally
- You're okay with occasional maintenance
- You want fast bulk imports
- You're comfortable troubleshooting

**Use XML Export Instead if:**
- You need guaranteed stability
- Working with production MSF
- Prefer officially supported methods
- Want zero maintenance burden

---

## Installation

MSF integration dependencies are included in the base installation:

```bash
pip install -e .
```

All required dependencies (psycopg2-binary, msgpack, requests) are automatically installed.

## Usage

Access from main menu:
```
Main Menu → Metasploit Integration
  19. Import MSF Data
     • Requires: MSF database with data (hosts/services/vulns/creds/sessions)
     • Requires: PostgreSQL connection to MSF DB
     • Dependencies: Included in base installation (psycopg2-binary, msgpack)

     How to use:
     1. Configure MSF database connection:
        • Host: localhost (default) or remote MSF instance
        • Port: 5432 (PostgreSQL default)
        • Database: msf (default) or custom
        • Username: msf user
        • Password: msf password (see password setup below)
     2. Select data types to import:
        • Hosts: IP addresses, hostnames, OS info
        • Services: Ports, protocols, versions
        • Vulnerabilities: CVEs, findings
        • Credentials: Usernames, passwords, hashes
        • Sessions: Active/closed meterpreter sessions
     3. Data merges with existing SoulEyez data
     4. Duplicates are detected and updated

     Setting MSF Database Password (if needed):
     1. sudo -u postgres psql
     2. ALTER USER msf WITH PASSWORD 'your_password';
     3. \q
     4. Update ~/.msf4/database.yml with new password
     5. Restart msfconsole and verify: db_status

  20. Sync Exploit Results
  21. View Active MSF Sessions
```

## If You Get Schema Errors

```bash
# Fallback to XML export
msf> db_export -f xml /tmp/msf_export.xml

# Then report the issue with your MSF version
# This helps us maintain compatibility
```

---

## Full Documentation

See [MSF_INTEGRATION.md](./MSF_INTEGRATION.md) for complete documentation.
