Domain 5Pivoting & MetasploitCORE

Database Integration

Complete guide to Metasploit database integration, PostgreSQL backend, db_nmap scanning, credential storage, host/service tracking, and database querying for organized OSCP exam reconnaissance.

Domain: Domain 5: Pivoting, Tunneling & Metasploit•Updated: 2026-09-01
#metasploit#database#postgresql#db_nmap#credentials

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_nmap scan 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; -T5 is even faster but less reliable)

How Results Are Stored

When db_nmap completes, the database automatically populates:

  1. Hosts table — IP address, MAC address, OS name, state (up/down)
  2. Services table — Each open port with service name, version info, state, and port number
  3. 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 pairs
  • exploit — Credentials discovered via exploit modules
  • auth — 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:

  1. Multiple targets — When scanning a subnet (10.10.10.0/24), db_nmap organizes all results queryably instead of dumping them to terminal output you must manually parse.

  2. 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.

  3. Credential tracking — db_cred centralizes all discovered credentials across all machines, making it easy to try the same password on multiple targets.

  4. Report preparation — db_export generates structured reports that can feed into your final write-up.

  5. 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:

  1. Single target — For a single machine, regular nmap with -oA output is sufficient and equally effective.

  2. Quick recon — If you just need to check a few ports, nmap -p 22,80,443 10.10.10.10 is faster than spinning up the database.

  3. Familiar workflows — If you are already comfortable with manual note-taking and file-based Nmap output, the database adds complexity without proportional benefit.

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.