Database Integration
1. Database Overview
Why Metasploit Uses PostgreSQL
The Metasploit Framework uses PostgreSQL as its default backend database to persistently store all reconnaissance, exploitation, and post-exploitation data. This integration transforms Metasploit from a standalone exploitation tool into a comprehensive penetration testing platform with centralized data management.
For OSCP exam purposes, understanding database integration is valuable because it:
- Automatically stores all
db_nmapscan results (hosts, open ports, services, versions, OS) - Centralizes credentials discovered during brute-force or exploitation
- Tracks notes and loot in a structured, queryable format
- Supports workspaces for isolating different targets or exam machines
- Enables fast querying during long sessions without re-running scans
What Data Does the Database Store?
The PostgreSQL backend stores six core data types:
| Data Type | Description | OSCP Relevance |
|---|---|---|
| Hosts | IP addresses, MAC addresses, OS details, hostnames | Critical for tracking all discovered machines |
| Services | Open ports, service names, version info, banners | Essential for identifying attack vectors |
| Vulnerabilities | Known CVEs and vulnerabilities associated with hosts/services | Useful for correlating findings |
| Credentials | Usernames, passwords, hashes, SSH keys from looting/brute-forcing | Critical for pivoting and lateral movement |
| Notes | Manual or auto-generated notes tied to hosts/services | Great for exam write-ups |
| Loot | Files captured during exploitation (configs, hashes, dumps) | Directly useful for post-exploitation |
Starting the Database
Before using any database commands, you must start the PostgreSQL service:
# Start the Metasploit database service
msfdb init
# Start msfconsole with database already running
msfconsole
On many systems, msfdb init handles installation, configuration, and starting of PostgreSQL automatically. Once msfconsole launches, verify the connection:
msf6 > db_status
[*] postgresql - connected as msf@127.0.0.1:5432/msf3
If disconnected, you’ll see:
msf6 > db_status
[*] postgresql - could not connect
Reconnect with:
msf6 > db_connect
2. Database Commands Reference
The following table provides a complete reference of all core database commands available in msfconsole:
| Command | Description | Example |
|---|---|---|
db_status |
Check database connection status | db_status |
db_connect |
Connect to a PostgreSQL database | db_connect user:pass@host/dbname |
db_disconnect |
Disconnect from the current database | db_disconnect |
db_nmap |
Run Nmap and store results in the database | db_nmap -sV -sC 10.10.10.10 |
db_hosts |
List all hosts in the database | db_hosts -c address,os_name |
db_services |
List all services in the database | db_services -c port,service,info |
db_vulns |
List all vulnerabilities in the database | db_vulns |
db_cred |
List all stored credentials | db_cred -c origin_type,username,password |
db_nmap_options |
List available Nmap options for db_nmap | db_nmap_options |
db_import |
Import scan results (Nmap XML, Nessus, OpenVAS) | db_import scan.xml |
db_export |
Export database contents (XML, HTML, YAML) | db_export -f xml -o report.xml |
db_notes |
List all notes in the database | db_notes |
db_loot |
List all captured loot files | db_loot |
workspace |
Create, switch, or list workspaces | workspace -a lab1 |
workspace -d |
Delete a workspace | workspace -d lab1 |
workspace -D |
Delete all workspaces | workspace -D |
workspace -l |
List all workspaces | workspace -l |
workspace -r |
Rename a workspace | workspace -r old new |
3. Using db_nmap
db_nmap is the most important database command for OSCP. It runs Nmap and automatically stores all results in the PostgreSQL backend — hosts, ports, services, versions, and OS detection data.
Basic Service Version Scan
msf6 > db_nmap -sV 10.10.10.10
This performs a service version detection scan against the target. The -sV flag tells Nmap to probe open ports to determine service/version info. All results are stored in the database automatically.
Full Reconnaissance Scan (OSCP Standard)
msf6 > db_nmap -sV -sC -p- 10.10.10.10
This is the most common OSCP scan pattern:
-sV— Service version detection-sC— Run default Nmap scripts (equivalent to--script=default)-p-— Scan all 65535 ports (not just the top 1000)
This single command gives you everything you need for initial reconnaissance, and all data is queryable afterward.
Subnet Scan for Multiple Targets
msf6 > db_nmap -sV -sC 10.10.10.0/24
When you have a subnet range (common in OSCP exam environments), this scans all 254 possible hosts and stores results for every live machine.
OS Detection
msf6 > db_nmap -O 10.10.10.10
The -O flag enables OS detection. Combined with other flags:
msf6 > db_nmap -sV -sC -O -p- 10.10.10.10
Verbose and Timing Options
msf6 > db_nmap -sV -sC -p- -v -T4 10.10.10.10
-v— Verbose output (shows progress in real time)-T4— Aggressive timing (faster than default-T3;-T5is even faster but less reliable)
How Results Are Stored
When db_nmap completes, the database automatically populates:
- Hosts table — IP address, MAC address, OS name, state (up/down)
- Services table — Each open port with service name, version info, state, and port number
- Notes table — Auto-generated notes from Nmap script output
You can verify the storage immediately after the scan:
msf6 > db_hosts
msf6 > db_services
msf6 > db_notes
Advantages Over Regular Nmap for OSCP
| Feature | Regular Nmap | db_nmap |
|---|---|---|
| Results persistence | Manual save required (-oA) |
Automatic storage in PostgreSQL |
| Querying results | Re-parse output files | Instant SQL-like queries |
| Cross-referencing | Manual correlation | Automatic linking of hosts/services/creds |
| Workspace isolation | Not applicable | Separate workspaces per target |
| Credential tracking | Not supported | Integrated with db_cred |
| Exploit module integration | Not applicable | Modules can query DB for targets |
| Report generation | Separate tools | Built-in db_export |
4. Querying the Database
After running db_nmap or manually adding data, you can query the database to retrieve stored information.
db_hosts — Listing Discovered Hosts
# List all hosts
msf6 > db_hosts
# Filter by specific columns
msf6 > db_hosts -c address,os_name,os_flavor
# Show only specific columns with addresses
msf6 > db_hosts -c address,mac,name,os_name
Common column names: address, mac, name, os_name, os_flavor, os_sp, os_family, os_vendor, state
Example output:
msf6 > db_hosts -c address,os_name
[*] Time: 2026-09-01 10:30:00 UTC
Address OS Name
--------- ---------
10.10.10.10 Ubuntu 20.04
10.10.10.20 Windows Server 2019
db_services — Listing Discovered Services
# List all services
msf6 > db_services
# Filter by specific columns
msf6 > db_services -c host,port,service,info,name
# Filter by port range
msf6 > db_services -R port:80
# Filter by service name
msf6 > db_services -R service:ssh
Common column names: host, port, proto, name, info, state, service
Example output:
msf6 > db_services -c host,port,name,info
[*] Time: 2026-09-01 10:31:00 UTC
Host Port Name Info
---- ---- ---- ----
10.10.10.10 22 ssh OpenSSH 8.2p1 Ubuntu 4ubuntu0.5
10.10.10.10 80 http Apache httpd 2.4.41
10.10.10.10 443 http Apache httpd 2.4.41 (SSL)
10.10.10.10 3306 mysql MySQL 8.0.27
db_cred — Listing Stored Credentials
# List all credentials
msf6 > db_cred
# List only logins (usernames/passwords)
msf6 > db_cred -c origin_type,username,password
# Filter by type
msf6 > db_cred -R origin_type:exploit
Credential types include:
login— Username/password pairsexploit— Credentials discovered via exploit modulesauth— Authentication data
db_vulns — Listing Vulnerabilities
# List all vulnerabilities
msf6 > db_vulns
# Filter by host
msf6 > db_vulns -f 10.10.10.10
Vulnerabilities are added automatically when exploit modules reference known CVEs, or can be added manually.
db_notes — Listing Notes
# List all notes
msf6 > db_notes
# Filter by host
msf6 > db_notes -f 10.10.10.10
# Filter by type
msf6 > db_notes -R type:vuln
Note types: vuln (vulnerability), exploit (exploit attempt), hack (manual note), detect (auto-detected)
db_loot — Listing Captured Files
# List all loot
msf6 > db_loot
# Filter by type
msf6 > db_loot -R type:config_file
Loot types: config_file, hash, screen_capture, keylog, credentials, document
5. Adding Data Manually
Beyond db_nmap, you can manually add data to the database from within msfconsole.
Adding Hosts
msf6 > add_host 10.10.10.30
msf6 > add_host -m 10.10.10.0/24
The -m flag adds all IPs in a subnet range as hosts.
Adding Services
msf6 > add_service -H 10.10.10.10 -p 8080 -s http -n custom_app
Parameters:
-H— Host IP-p— Port number-s— Protocol (tcp/udp)-n— Service name
Adding Credentials
msf6 > add_credential -u admin -p P@ssw0rd! -r http -H 10.10.10.10 -P 80
Parameters:
-u— Username-p— Password-r— Protocol-H— Host IP-P— Port
Adding Notes
msf6 > add_note -H 10.10.10.10 -t vuln -d "Apache 2.4.41 - potential RCE via path traversal"
Parameters:
-H— Host IP-t— Note type (vuln, exploit, hack, detect)-d— Note description
Adding Loot
msf6 > add_loot -H 10.10.10.10 -t config_file -d "Apache config" -f httpd.conf
Parameters:
-H— Host IP-t— Loot type-d— Description-f— File path (local path to the captured file)
6. Importing and Exporting Data
db_import — Importing Scan Results
Metasploit can import results from various scanning tools:
# Import Nmap XML output
msf6 > db_import /path/to/nmap_scan.xml
# Import Nmap grepable output
msf6 > db_import /path/to/nmap_scan.gnmap
# Import Nessus XML report
msf6 > db_import /path/to/nessus_report.nessus
# Import OpenVAS XML report
msf6 > db_import /path/to/openvas_report.xml
# Import multiple files at once
msf6 > db_import scan1.xml scan2.xml scan3.xml
OSCP Tip: If you already ran Nmap outside Metasploit with -oX (XML output), you can import those results instead of re-scanning:
# Outside msfconsole - run Nmap with XML output
nmap -sV -sC -p- -oX scan.xml 10.10.10.10
# Inside msfconsole - import the results
msf6 > db_import scan.xml
db_export — Exporting Database Contents
# Export to XML
msf6 > db_export -f xml -o report.xml
# Export to HTML
msf6 > db_export -f html -o report.html
# Export to YAML
msf6 > db_export -f yaml -o report.yaml
Supported formats: xml, html, yaml
7. Credential Management
Storing Credentials from Brute Force
When you use Metasploit’s auxiliary scanner modules for brute-forcing, successful credentials are automatically stored in the database:
msf6 > use auxiliary/scanner/ssh/ssh_login
msf6 > set RHOSTS 10.10.10.10
msf6 > set USER_FILE /path/to/usernames.txt
msf6 > set PASS_FILE /path/to/passwords.txt
msf6 > run
After successful authentication, check stored credentials:
msf6 > db_cred
Adding Credentials Manually
If you discover credentials through other means (web app, file enumeration, exploitation), store them:
msf6 > add_credential -u jsmith -p Summer2024! -r ssh -H 10.10.10.10 -P 22
Using Stored Credentials for Pivoting
Query credentials to find usable login pairs for lateral movement:
msf6 > db_cred -c username,password,origin_type
Cross-reference with services to find which credentials apply to which hosts:
msf6 > db_services -c host,port,name
msf6 > db_cred
Credential Types in the Database
| Origin Type | Source | Example |
|---|---|---|
login |
Manual entry or scanner modules | add_credential or ssh_login |
exploit |
Discovered during exploitation | Post-exploitation hash dumps |
auth |
Authentication data | NTLM hashes, Kerberos tickets |
8. Workspaces
Workspaces allow you to isolate data for different targets or engagements.
# List all workspaces
msf6 > workspace -l
# Create a new workspace
msf6 > workspace -a oscp_machine1
# Switch to a workspace
msf6 > workspace oscp_machine1
# Delete a workspace
msf6 > workspace -d oscp_machine1
# Rename a workspace
msf6 > workspace -r old_name new_name
# Delete all workspaces (except default)
msf6 > workspace -D
By default, all data is stored in the default workspace. Each workspace maintains its own separate set of hosts, services, credentials, notes, and loot.
9. OSCP Relevance
When Database Integration Helps
Database integration is highly valuable in the following OSCP scenarios:
-
Multiple targets — When scanning a subnet (
10.10.10.0/24),db_nmaporganizes all results queryably instead of dumping them to terminal output you must manually parse. -
Long exam sessions — With 24-48 hours to complete the exam, having all scan results, credentials, and notes stored in a queryable database saves significant time.
-
Credential tracking —
db_credcentralizes all discovered credentials across all machines, making it easy to try the same password on multiple targets. -
Report preparation —
db_exportgenerates structured reports that can feed into your final write-up. -
Cross-referencing — Quickly correlate services with credentials (
db_services+db_cred) to identify attack paths.
When It Is Overkill
Database integration is less critical when:
-
Single target — For a single machine, regular
nmapwith-oAoutput is sufficient and equally effective. -
Quick recon — If you just need to check a few ports,
nmap -p 22,80,443 10.10.10.10is faster than spinning up the database. -
Familiar workflows — If you are already comfortable with manual note-taking and file-based Nmap output, the database adds complexity without proportional benefit.
Recommended OSCP Approach
For the OSCP exam, the recommended approach is:
# Step 1: Start the database
msfdb init
# Step 2: Launch msfconsole
msfconsole
# Step 3: Verify connection
db_status
# Step 4: Create a workspace for the target
workspace -a target1
# Step 5: Run comprehensive scan
db_nmap -sV -sC -p- -v -T4 10.10.10.10
# Step 6: Query results
db_hosts
db_services -c host,port,name,info
# Step 7: As you find credentials, store them
add_credential -u username -p password -r protocol -H 10.10.10.10
# Step 8: Add notes for tracking
add_note -H 10.10.10.10 -t vuln -d "Description of finding"
Quick Reference: Most Used Commands for OSCP
db_status # Verify database connection
db_nmap -sV -sC -p- <IP> # Full scan with storage
db_hosts -c address,os_name # List hosts with OS info
db_services -c host,port,name,info # List services
db_cred # List all credentials
add_credential -u <user> -p <pass> -r <proto> -H <host> # Store credential
add_note -H <host> -t vuln -d "<description>" # Add note
workspace -a <name> # Create workspace
workspace -l # List workspaces
db_export -f html -o report.html # Export report
Summary
Metasploit’s PostgreSQL database integration transforms the framework into a centralized penetration testing platform. For OSCP, the most valuable commands are db_nmap for automated scan storage, db_hosts and db_services for querying results, and db_cred for credential management. While not strictly required for passing the exam, database integration significantly improves organization and efficiency — especially when handling multiple targets or long exam sessions. Master these commands, and you’ll have a powerful reconnaissance and tracking system at your fingertips.