🛡️ Methodology Checklist
- Start PostgreSQL + MSF DB:
msfdb run - Create workspace per engagement:
workspace -a [CLIENT_NAME] - Import Nmap results:
db_import [SCAN].xml - Review discovered hosts:
hosts - Review discovered services:
services - Review stored credentials:
creds - Export engagement data:
db_export -f xml [FILE].xml - Switch workspace when changing engagement:
workspace [NAME]
🎯 Operational Context
Use when: Multi-target engagement or long-running assessment — use MSF database to track discovered hosts, services, credentials, and loot across sessions.
Think Dumber First: workspace -a [CLIENT_NAME] before any scan. Keeps your current engagement data separate from other clients. db_nmap instead of nmap — automatically imports results into the database.
Skip when: Single-target lab — database overhead not worth it for simple CTF-style single machine.
⚡ Tactical Cheatsheet
| Command | Tactical Outcome |
|---|---|
sudo systemctl start postgresql | Start PostgreSQL backend |
sudo msfdb init | Initialize MSF database schema |
sudo msfdb run | Launch msfconsole with DB auto-connected |
db_status | Verify database connection (inside msfconsole) |
msfdb reinit | Reinitialize DB if connectivity fails |
cp /usr/share/metasploit-framework/config/database.yml ~/.msf4/ | Fix DB config manually |
workspace | List all workspaces |
workspace -a [NAME] | Create new workspace |
workspace [NAME] | Switch to workspace |
workspace -d [NAME] | Delete workspace |
db_import [FILENAME].xml | Import external Nmap XML scan |
db_nmap -sV -sS [TARGET_IP] | Run Nmap + auto-save results to DB |
hosts | List all discovered hosts |
hosts -a [TARGET_IP] | Add host manually |
hosts -u | Show only live hosts |
services | List all discovered services |
services -p [PORT] | Filter services by port |
services -s smb | Filter services by name |
creds | List all stored credentials |
creds add user:[USER] password:[PASS] realm:workgroup | Add plaintext credential |
creds add ntlm:[HASH] | Add NTLM hash credential |
creds -t NTLM | Filter credentials by type |
loot | List all loot (hash dumps, captured files) |
loot -S shadow | Search loot by keyword |
db_export -f xml backup.xml | Export entire database to XML |
🔬 Deep Dive & Workflow
Why Use the Database?
On complex assessments with many hosts and services, manually tracking findings in notes loses context. The MSF database gives you:
- Persistent host/service inventory across sessions
- Automatic credential tracking when modules find them
RHOSTSpopulation fromhostsresults (no copy-pasting IPs)- Backup/migration via XML export
Workspaces — Project Isolation
Workspaces segregate data by engagement scope. Always create a workspace before starting:
workspace -a ClientA_External
workspace ClientA_ExternalSwitching between engagements: workspace ClientB_Internal — all hosts, services, creds commands show only that workspace’s data.
db_nmap vs Regular Nmap
# Standard — must manually parse XML and import
nmap -sV -oX target.xml [TARGET_IP]
db_import target.xml
# DB-integrated — parses and stores automatically
db_nmap -sV -sS [TARGET_IP]db_nmap accepts all standard nmap flags. Prefer this during engagements — results land directly in hosts and services.
Credential Types
| Type | Command | Use |
|---|---|---|
| Plaintext | creds add user:admin password:pass123 | After finding creds in cleartext |
| NTLM hash | creds add ntlm:[HASH] | After credential dump |
| NetNTLMv2 | Captured automatically by modules | Relay/crack later |
Filter: creds -t NTLM / creds -t password — useful before Pass-the-Hash attacks.
Troubleshooting DB Connection
If db_status shows not connected:
# Reinitialize
msfdb reinit
cp /usr/share/metasploit-framework/config/database.yml ~/.msf4/
sudo service postgresql restart
sudo msfdb run🛠️ Troubleshooting & Edge Cases
| Problem | Cause | Fix |
|---|---|---|
| db_connect fails | PostgreSQL not running | Start: systemctl start postgresql && msfdb init |
| db_nmap returns ‘no database’ | MSF not connected to DB | Run db_status — if disconnected, db_connect msf:msf@localhost/msf_db |
| Workspace data missing after restart | MSF session disconnected | DB persists — reconnect with db_connect and workspace [NAME] to reload |
| hosts command shows no results | Scans not using db_nmap | Import manually: db_import /path/to/nmap.xml for existing nmap XML output |
| creds command empty after credential harvesting | Module didn’t store creds | Manually add: creds add host:[IP] user:[USER] password:[PASS] type:plaintext |
📝 Reporting Trigger
Finding Title: MSF Database Tracks Compromised Infrastructure Across Engagement Impact: MSF database maintains persistent record of all discovered hosts, services, credentials, and session history enabling coordinated multi-target exploitation and preventing data loss during engagement. Root Cause: N/A — operational capability documentation. Recommendation: Operators must use workspace isolation per client engagement. Database should be encrypted at rest. All engagement data must be securely deleted post-engagement per data handling procedures.