Domain 5Pivoting & MetasploitCORE

Workspace Management

Complete guide to Metasploit workspace management for organizing multiple labs, targets, and scanning data during the OSCP exam with best practices for efficient data separation.

Domain: Domain 5: Pivoting, Tunneling & Metasploit•Updated: 2026-09-01
#metasploit#workspace#organization#database#lab-management

Workspace Management

Table of Contents

  1. What are Workspaces?
  2. Workspace Commands
  3. Default Workspace
  4. Workspace Data Isolation
  5. Workspace Best Practices
  6. Workspace and db_nmap Integration
  7. Workspace and Credential Management
  8. OSCP Exam Strategy
  9. Common Mistakes

What are Workspaces?

Concept

In Metasploit Framework, a workspace is a logical container that isolates all database-stored information — hosts, services, vulnerabilities, credentials, notes, and loot — into separate, named contexts. Think of a workspace as a “project folder” within Metasploit’s database backend.

When you run msfdb init, Metasploit creates a PostgreSQL database (typically named msf_database). Within this single database, workspaces allow you to partition your data so that information from one engagement, lab, or exam does not mix with another.

Why Workspaces Exist

Workspaces solve a fundamental organizational problem:

  • Multiple engagements: You may be working on a training lab, a CTF, and a real penetration test simultaneously. Without workspaces, all hosts, credentials, and notes would collide in a single flat namespace.
  • Data hygiene: When you finish a lab, you can delete its workspace cleanly without affecting other projects.
  • Exam readiness: During the OSCP exam, you need a dedicated, isolated space to track all scan results, discovered credentials, and exploitation progress — completely separate from any practice labs.

How Workspaces Isolate Data

Each workspace maintains its own independent set of records for:

Data Type Description
Hosts IP addresses, hostnames, operating systems
Services Ports, banners, service names, versions
Vulnerabilities Discovered CVEs, exploit references
Credentials Login/password pairs, hashes, SSH keys
Notes Manual or automatic notes attached to hosts/services
Loot Captured files, screenshots, dumps
Clients Meterpreter and other session records

When you switch workspaces, Metasploit queries the database with a workspace filter. Data from workspace lab1 is invisible when you are active in workspace oscp_exam, and vice versa. The underlying PostgreSQL tables store a workspace_id column that enforces this separation at the query level.


Workspace Commands

Complete Command Reference

Command Description Example
workspace Show the currently active workspace workspace
workspace -l List all workspaces (lowercase L) workspace -l
workspace -L List all workspaces with host counts workspace -L
workspace -a <name> Create a new workspace workspace -a oscp_exam
workspace <name> Switch to an existing workspace workspace oscp_exam
workspace -d <name> Delete a workspace workspace -d old_lab
workspace -C Clear all data in the current workspace workspace -C
workspace -D Delete all workspaces (except default) workspace -D

Detailed Command Explanations

1. Show Current Workspace

msf6 > workspace
[*] Workspace: default

Running workspace with no arguments simply prints the name of the currently active workspace. This is your first line of defense against accidentally scanning into the wrong workspace.

2. List All Workspaces (workspace -l)

msf6 > workspace -l
    +------+-------+-------+
    | Name | Users | Hosts |
    +------+-------+-------+
    | *default | 0 | 0 |
    | lab1 | 0 | 5 |
    | oscp_exam | 0 | 10 |
    +------+-------+-------+

The asterisk (*) next to a workspace name indicates which workspace is currently active. This command gives you a quick overview of all available workspaces and their host counts.

3. List Workspaces with Details (workspace -L)

msf6 > workspace -L
    +------+-------+-------+
    | Name | Users | Hosts |
    +------+-------+-------+
    | *default | 0 | 0 |
    | lab1 | 3 | 5 |
    | oscp_exam | 12 | 10 |
    +------+-------+-------+

The uppercase -L flag provides the same listing but may include additional columns depending on your Metasploit version. Both -l and -L are useful for auditing your workspace environment.

4. Create a New Workspace (workspace -a)

msf6 > workspace -a oscp_exam
[*] Workspace: oscp_exam

This creates a new, empty workspace named oscp_exam and automatically switches to it. You can verify the switch:

msf6 > workspace
[*] Workspace: oscp_exam

Key point: Creating a workspace does not copy any data from the previous workspace. It starts completely empty.

5. Switch to an Existing Workspace (workspace <name>)

msf6 > workspace lab1
[*] Workspace: lab1

Switching workspaces is instantaneous — Metasploit simply changes the query filter applied to all subsequent database operations. All your active sessions, loaded modules, and console state remain unchanged; only the database context switches.

6. Delete a Workspace (workspace -d)

msf6 > workspace -d old_lab
[*] Deleted workspace `old_lab`

Warning: This permanently removes all data (hosts, services, credentials, notes, loot) stored in that workspace. There is no recycle bin. Always export your data before deleting.

You cannot delete the workspace you are currently active in:

msf6 > workspace lab1
[*] Workspace: lab1
msf6 > workspace -d lab1
[-] Error while running command workspace: Cannot delete the current workspace

Switch to a different workspace first, then delete.

7. Clear Current Workspace (workspace -C)

msf6 > workspace -C
[*] Cleared workspace `oscp_exam`

This removes all data (hosts, services, vulns, creds, notes, loot) from the currently active workspace but keeps the workspace itself. Useful when you want to restart a lab from scratch without recreating the workspace.

8. Delete All Workspaces (workspace -D)

msf6 > workspace -D
[*] Deleted all workspaces

This deletes every workspace except the default workspace. Use with extreme caution.


Default Workspace

What Is the Default Workspace?

The default workspace is automatically created when you initialize the Metasploit database with msfdb init. It serves as the fallback workspace and is always present — you cannot delete it.

When to Use the Default Workspace

Scenario Recommendation
Quick, one-off testing Fine to use default
Learning and practice Create named workspaces for discipline
OSCP exam Never use default — create a dedicated workspace
Multiple concurrent labs Always use named workspaces

Why You Should Avoid the Default Workspace for Serious Work

  1. No visual distinction: It is easy to forget you are in default and accidentally mix data.
  2. No naming context: default tells you nothing about what data it contains.
  3. Cannot be deleted: If it accumulates garbage data, you can only clear it (workspace -C), not recreate it.

Best practice: Always create a named workspace for any structured engagement, lab, or exam.


Workspace Data Isolation

What Data Is Isolated Per Workspace?

When you switch between workspaces, the following database tables are filtered by workspace_id:

Database Table Data Stored Isolated?
hosts IP addresses, hostnames, OS info, MAC addresses Yes
services Port numbers, protocols, service names, banners, versions Yes
vulns Discovered vulnerabilities, CVE references, exploit paths Yes
creds Credentials (usernames, passwords, hashes, JWTs) Yes
notes Manual and automatic notes (attached to hosts/services) Yes
loot Captured files, screenshots, password dumps Yes
clients Meterpreter sessions, shell sessions Yes
events Event log entries Yes
modules Module execution history Partially

What Is NOT Isolated?

Item Behavior
Loaded modules Modules loaded in the console persist across workspace switches
Active sessions Meterpreter/shell sessions remain connected regardless of workspace
Console options Global console settings (verbosity, output format) are shared
Exploit payloads Payload configuration is not workspace-specific

Practical Demonstration

# Create two workspaces and populate them separately
msf6 > workspace -a lab_alpha
[*] Workspace: lab_alpha

msf6 > db_nmap -sV 10.0.1.0/24
[*] Nmap: Starting Nmap at 2026-08-31 10:00
[*] Nmap: Scan complete at 10:05
[*] Nmap: 10 host(s) scanned in 302.45 seconds

msf6 > hosts
[*] Host: 10 hosts found in workspace 'lab_alpha'

# Switch to a different workspace
msf6 > workspace -a lab_beta
[*] Workspace: lab_beta

msf6 > hosts
[*] There are no currently defined hosts in the current workspace.

# The lab_alpha hosts are invisible here — perfectly isolated

Workspace Best Practices

1. One Workspace Per Lab or Exam

This is the golden rule. Each distinct engagement, lab environment, or exam should get its own workspace:

msf6 > workspace -a tryhackme_pentestlab
msf6 > workspace -a oscp_exam_july2026
msf6 > workspace -a proctored_practice_1

2. Naming Conventions

Use clear, descriptive names that immediately tell you what data they contain:

Convention Example When to Use
lab<number> lab1, lab2 Sequential practice labs
oscp_exam oscp_exam The actual OSCP exam
pentest_<client> pentest_client_x Client engagements
<platform>_<name> thm_room_xyz, htb_machine_abc TryHackMe, HackTheBox
practice_<date> practice_20260831 Dated practice sessions

Avoid: Generic names like test, new, workspace1 — they provide no context.

3. Export Before Deleting

Always export your workspace data before deleting it:

# Export hosts and services to CSV
msf6 > db_export -f csv -o /root/reports/oscp_exam_export.csv

# Or export in XML format
msf6 > db_export -f xml -o /root/reports/oscp_exam_export.xml

4. Clear Old Workspaces Regularly

Keep your workspace list clean to avoid confusion:

msf6 > workspace -l
    +------+-------+-------+
    | Name | Users | Hosts |
    +------+-------+-------+
    | *oscp_exam | 15 | 10 |
    | lab1 | 0 | 5 |
    | lab2 | 0 | 3 |
    | old_ctf | 0 | 20 |
    +------+-------+-------+

# Switch away, then delete old workspaces
msf6 > workspace oscp_exam
msf6 > workspace -d old_ctf
[*] Deleted workspace `old_ctf`

5. Audit Before Starting New Work

Before beginning a new engagement, check your workspace list and clean up:

msf6 > workspace -L
# Review the list
# Delete or clear any stale workspaces
# Create fresh workspace for new engagement
msf6 > workspace -a new_engagement

Workspace and db_nmap Integration

How Scans Are Stored

When you run db_nmap, all results are stored in the currently active workspace. This is critical — if you are in the wrong workspace, your scan results go to the wrong place.

Workflow Example

# Step 1: Ensure you are in the correct workspace
msf6 > workspace
[*] Workspace: oscp_exam

# Step 2: Run reconnaissance scan
msf6 > db_nmap -sV -sC --open 10.10.10.0/24
[*] Nmap: Starting Nmap at 2026-08-31 14:00
[*] Nmap: 255 host(s) scanned in 845.12 seconds
[*] Nmap: 42 open ports on 10 host(s)

# Step 3: Verify results are in the correct workspace
msf6 > hosts
[*] Address         Hostname  Info  OS  Port  Transportation
[*] -------------------------------------------------------
[*] 10.10.10.1      None      None  None 80/tcp   tcp
[*] 10.10.10.5      None      None  None 22/tcp   tcp
...

msf6 > services
[*] Services: 42 service(s) found on 10 host(s)

Critical Warning

If you accidentally run db_nmap while in the wrong workspace, the scan data is stored there. You cannot move it — you must re-scan in the correct workspace. Always verify your active workspace before scanning:

msf6 > workspace
[*] Workspace: oscp_exam    <-- Confirm this before every scan

Advanced: Importing Existing Nmap XML

You can also import pre-existing Nmap XML scan results into the current workspace:

msf6 > workspace oscp_exam
[*] Workspace: oscp_exam

msf6 > db_import /root/scans/nmap_results.xml
[*] Processing `/root/scans/nmap_results.xml` as `Xml`
[*] Importing 10 hosts and 42 services into workspace 'oscp_exam'

Workspace and Credential Management

How Credentials Are Isolated

All credentials discovered or added during your session are stored in the workspace’s creds table. This means:

  • Credentials found in lab1 are invisible when you switch to oscp_exam.
  • You can safely brute-force passwords in a practice workspace without polluting your exam workspace.

Credential Commands Per Workspace

# View all credentials in the current workspace
msf6 > creds
[+] Credentials: 5 credential(s) found in workspace 'oscp_exam'
[+] ---- ---- ---- ---- -------------
[+] 1    admin  admin  10.10.10.5:22   ssh

# Add a credential manually to the current workspace
msf6 > add_cred -u jsmith -p P@ssw0rd! -r 10.10.10.5:443
[+] Added a credential: jsmith:P@ssw0rd! @ 10.10.10.5:443

# Search credentials across all workspaces (auxiliary module)
use auxiliary/scanner/parser/ssh
# Or use db_auth_brute to test creds within current workspace

Practical Scenario: Credential Spraying Across Workspaces

# Workspace 1: Lab environment
msf6 > workspace lab1
[*] Workspace: lab1
msf6 > creds
[+] 3 credentials found (lab-specific)

# Workspace 2: Exam environment
msf6 > workspace oscp_exam
[*] Workspace: oscp_exam
msf6 > creds
[+] 0 credentials found (clean exam workspace)

This isolation ensures that practice credentials never leak into your exam workspace, maintaining a clean, auditable record.


OSCP Exam Strategy

Follow this exact sequence on exam day:

Step 1: Start Metasploit and Verify Database

msfdb run
msfconsole
msf6 > db_status
[*] postgresql connected to db name 'msf_database'

Step 2: Create Your Exam Workspace

msf6 > workspace -a oscp_exam
[*] Workspace: oscp_exam

msf6 > workspace
[*] Workspace: oscp_exam

Step 3: Verify the Workspace Is Empty

msf6 > hosts
[*] There are no currently defined hosts in the current workspace.

msf6 > creds
[+] No credentials to display

Step 4: Run All Scans Into This Workspace

# Always confirm workspace before each major scan
msf6 > workspace
[*] Workspace: oscp_exam

# Initial ping sweep
msf6 > db_nmap -sn 10.10.10.0/24

# Service version scan on live hosts
msf6 > db_nmap -sV -sC --open -p 22,80,443,8080,3389 10.10.10.0/24

Step 5: Use Database Commands to Track Progress

# View all discovered hosts
msf6 > hosts -c address,os_name,comments

# View all discovered services
msf6 > services -c address,port,name,state -R

# View all credentials
msf6 > creds -c origin_name,service,user,pass

# View all notes
msf6 > notes -c host,service,type,note

Step 6: Add Notes During the Exam

# Add a note about a compromised host
msf6 > add_note -a 10.10.10.5 -t msg -d "Root shell obtained via EternalBlue (MS17-010)"

# Add a note about a service
msf6 > add_note -a 10.10.10.10 -t msg -d "SMB signing disabled, attempt psexec"

Step 7: Export at the End of the Exam

# Export everything for your write-up
msf6 > db_export -f csv -o /root/oscp_exam_data.csv

# Or export in XML for structured data
msf6 > db_export -f xml -o /root/oscp_exam_data.xml

Why This Strategy Works

  1. Single source of truth: All scan data, credentials, and notes live in one workspace.
  2. No data pollution: Your exam workspace is completely isolated from any practice data.
  3. Easy report generation: Export the workspace data at the end for your write-up.
  4. Audit trail: The workspace provides a timestamped record of all your discoveries.

Common Mistakes

Mistake 1: Forgetting Which Workspace Is Active

Scenario: You finish a practice lab in lab1, switch to oscp_exam, but forget to verify. You run db_nmap and the results go into lab1.

Prevention:

# Make this a habit — check before every scan
msf6 > workspace
[*] Workspace: oscp_exam    <-- Confirm!

Mistake 2: Mixing Data Between Workspaces

Scenario: You leave the default workspace populated with practice data, then start your exam without creating a new workspace. All exam data mixes with practice data.

Prevention: Always create a dedicated workspace before starting any structured work:

msf6 > workspace -a oscp_exam

Mistake 3: Deleting a Workspace Without Exporting

Scenario: You delete lab1 after finishing, only to realize you needed the credential list for your notes.

Prevention: Always export before deleting:

msf6 > db_export -f csv -o /root/backups/lab1_export.csv
msf6 > workspace default
msf6 > workspace -d lab1

Mistake 4: Assuming Sessions Follow Workspace Switches

Scenario: You have a Meterpreter session from lab1, switch to oscp_exam, and expect the session data to appear in the new workspace.

Reality: Active sessions persist, but their database records (clients table) remain in the workspace where they were created. New sessions opened while in oscp_exam will be recorded there.

Mistake 5: Not Clearing the Default Workspace

Scenario: You leave scan results, credentials, and notes in the default workspace from months of practice. It becomes a cluttered junk drawer.

Prevention: Periodically clean the default workspace:

msf6 > workspace default
msf6 > workspace -C
[*] Cleared workspace `default`

Quick Reference Card

+-------------------------------+------------------------------------------+
| Action                        | Command                                  |
+-------------------------------+------------------------------------------+
| Show current workspace        | workspace                                |
| List all workspaces           | workspace -l                             |
| List with details             | workspace -L                             |
| Create workspace              | workspace -a <name>                      |
| Switch workspace              | workspace <name>                         |
| Delete workspace              | workspace -d <name>                      |
| Clear current workspace       | workspace -C                             |
| Delete all (except default)   | workspace -D                             |
| Export workspace data         | db_export -f csv -o <file>               |
| Check database status         | db_status                                |
+-------------------------------+------------------------------------------+

Summary

Metasploit workspaces are essential for maintaining organized, isolated data during penetration testing engagements. For the OSCP exam specifically:

  1. Always create a dedicated workspace (oscp_exam) before starting.
  2. Verify the active workspace before every scan and database operation.
  3. Use the workspace database to track hosts, services, credentials, and notes.
  4. Export your workspace data at the end of the exam for your write-up.
  5. Never mix practice data with exam data — workspaces exist to prevent exactly this.

Mastering workspace management ensures your Metasploit database remains a reliable, organized tool throughout your OSCP journey and beyond.