Workspace Management
Table of Contents
- What are Workspaces?
- Workspace Commands
- Default Workspace
- Workspace Data Isolation
- Workspace Best Practices
- Workspace and db_nmap Integration
- Workspace and Credential Management
- OSCP Exam Strategy
- 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
- No visual distinction: It is easy to forget you are in
defaultand accidentally mix data. - No naming context:
defaulttells you nothing about what data it contains. - 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
lab1are invisible when you switch tooscp_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
Recommended Workspace Setup for Exam Day
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
- Single source of truth: All scan data, credentials, and notes live in one workspace.
- No data pollution: Your exam workspace is completely isolated from any practice data.
- Easy report generation: Export the workspace data at the end for your write-up.
- 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:
- Always create a dedicated workspace (
oscp_exam) before starting. - Verify the active workspace before every scan and database operation.
- Use the workspace database to track hosts, services, credentials, and notes.
- Export your workspace data at the end of the exam for your write-up.
- 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.