🗄️ Databases¶

Metasploit integrates with a PostgreSQL database to persistently store all data collected during an engagement — discovered hosts, open ports, service versions, credentials, vulnerabilities, and loot. This is essential for organized, professional penetration testing.

1️⃣ Setting Up the Database¶

Initialize the Database (First Time)¶

# Initialize PostgreSQL and create the msf database
sudo msfdb init

This command: 1. Starts the PostgreSQL service. 2. Creates a database user (msf). 3. Creates the database (msf). 4. Writes the connection config to ~/.msf4/database.yml.

Check Database Status¶

# From the command line
sudo msfdb status

# From inside MSFconsole
msf6 > db_status

Expected output:

[*] Connected to msf. Connection type: postgresql.

Start/Stop the Database¶

sudo msfdb start
sudo msfdb stop
sudo msfdb restart

Note

If db_status shows "no connection", ensure PostgreSQL is running (sudo systemctl start postgresql) and that ~/.msf4/database.yml exists with correct credentials.

2️⃣ Workspaces¶

Workspaces allow you to organize data by engagement, client, or project. Each workspace has its own isolated set of hosts, services, credentials, and loot.

# List workspaces (default is "default")
msf6 > workspace

# Create a new workspace
msf6 > workspace -a client_engagement_2024

# Switch to a workspace
msf6 > workspace client_engagement_2024

# Delete a workspace
msf6 > workspace -d old_workspace

# Rename a workspace
msf6 > workspace -r old_name new_name

Tip

Always create a dedicated workspace for each engagement. This keeps data isolated and makes reporting much easier.

3️⃣ Importing Scan Data¶

You can import results from external tools directly into the Metasploit database:

Import Nmap Results¶

# Run Nmap from within MSFconsole (results are auto-imported)
msf6 > db_nmap -sV -sC -p- 10.10.10.0/24

# Or import an existing Nmap XML file
msf6 > db_import /path/to/nmap_scan.xml

Supported Import Formats¶

# Import from various tools
msf6 > db_import /path/to/nessus_scan.nessus
msf6 > db_import /path/to/burp_results.xml
msf6 > db_import /path/to/openvas_scan.xml

Concept

db_nmap is simply a wrapper that runs Nmap and automatically imports the results into the current workspace. It supports all standard Nmap flags. This is the recommended way to run Nmap scans when using Metasploit.

4️⃣ Querying the Database¶

Hosts¶

# List all discovered hosts
msf6 > hosts

# Filter by OS
msf6 > hosts -o windows

# Search by IP
msf6 > hosts -S 10.10.10

# Add a host manually
msf6 > hosts -a 10.10.10.5

# Delete a host
msf6 > hosts -d 10.10.10.5

Services¶

# List all discovered services
msf6 > services

# Filter by port
msf6 > services -p 445

# Filter by service name
msf6 > services -s http

# Show only open ports
msf6 > services -u

Credentials¶

# List all captured credentials
msf6 > creds

# Add credentials manually
msf6 > creds -a 10.10.10.5 -p 445 -u administrator -P 'Password123!'

Vulnerabilities¶

# List all discovered vulnerabilities
msf6 > vulns

# Search for a specific CVE
msf6 > vulns -S CVE-2017-0144

Loot¶

# List all captured loot (files, hashes, tokens)
msf6 > loot

5️⃣ Using Database Data with Modules¶

The real power of the database is using stored data to automatically populate module options:

# Use the hosts in the database as RHOSTS
msf6 > use auxiliary/scanner/smb/smb_version
msf6 > hosts -R    # This sets RHOSTS to all hosts in the current workspace
msf6 > run

# Or filter by service
msf6 > services -p 445 -R    # Set RHOSTS to only hosts with port 445 open
msf6 > run

Tip

The -R flag on hosts and services commands automatically populates RHOSTS with the matching results. This is extremely efficient when scanning or exploiting multiple hosts.

6️⃣ Exporting Data¶

# Export the workspace data
msf6 > db_export -f xml /path/to/export.xml

# Supported formats: xml, pwdump
msf6 > db_export -f pwdump /path/to/creds.txt

7️⃣ Database Rebuild and Troubleshooting¶

# Reinitialize the database (warning: deletes all data)
sudo msfdb reinit

# Check and rebuild the database
sudo msfdb delete
sudo msfdb init

Common Issues¶

Problem	Solution
`db_status` shows "no connection"	Run `sudo msfdb start` and restart MSFconsole.
"could not connect to server"	Ensure PostgreSQL is running: `sudo systemctl start postgresql`.
Stale data from old engagements	Create a new workspace: `workspace -a new_engagement`.
Database is slow	Run `db_rebuild_cache` to rebuild the module cache.

Note

The database connection is configured in ~/.msf4/database.yml. If this file is missing or corrupted, run sudo msfdb init to regenerate it.

Warning

The Metasploit database may contain sensitive engagement data including credentials, network maps, and vulnerability information. Secure access to your Metasploit installation and encrypt database backups.