Field Manual

MSF Custom Modules

4 min read

🛡️ Methodology Checklist

  • Identify the gap: existing modules don’t cover your target/version
  • Find closest existing module as template
  • Copy to ~/.msf4/modules/[type]/[category]/name.rb
  • Update Mixin, Target, and Payload sections
  • Set def check method to verify before exploit
  • Test against lab target before use in engagement
  • Run reload_all in MSF console to load new module

🎯 Operational Context

Use when: No public MSF module exists for a target vulnerability — write custom exploit or auxiliary module in Ruby. Think Dumber First: Copy the closest existing module as a template. Change the metadata and the exploit method. The MSF framework handles all the boilerplate (options, payload generation, session handling). Focus only on the unique exploit logic. Skip when: A working PoC in Python exists — it may be faster to exploit without MSF rather than port to Ruby.

⚡ Tactical Cheatsheet

CommandTactical Outcome
searchsploit [NAME]Search local exploit-db for modules
searchsploit -t Nagios3 --exclude=".py"Filter for Ruby MSF-compatible modules
mkdir -p ~/.msf4/modules/exploits/linux/http/Create user module directory
cp [MODULE].rb ~/.msf4/modules/exploits/linux/http/[name].rbInstall module to user path
loadpath ~/.msf4/modules/Load custom module directory in msfconsole
reload_allReload all modules (picks up newly added)
use exploit/linux/http/nagios3_command_injectionUse the newly installed module
show optionsVerify module loaded correctly

🔬 Deep Dive & Workflow

When to Import External Modules

Official MSF modules are maintained and updated via apt update && apt install metasploit-framework, but some exploits (especially new CVEs or niche applications) only exist as community .rb files on ExploitDB or GitHub.

Finding Metasploit-Compatible Modules on ExploitDB

# Search for all Nagios3 exploits, exclude Python files
searchsploit -t Nagios3 --exclude=".py"
 
# Look for .rb extension in the results — these are MSF modules
# Also filter on ExploitDB web: tag "Metasploit Framework (MSF)"

Installation Workflow

# 1. Download the .rb file
# (from searchsploit results or GitHub)
 
# 2. Mirror directory structure — must match the module's category
mkdir -p ~/.msf4/modules/exploits/linux/http/
 
# 3. Copy with snake_case filename (no dashes!)
cp ~/Downloads/9861.rb ~/.msf4/modules/exploits/linux/http/nagios3_command_injection.rb
 
# 4. Load inside msfconsole
msf6 > loadpath ~/.msf4/modules/
# OR
msf6 > reload_all
 
# 5. Verify
msf6 > use exploit/linux/http/nagios3_command_injection
msf6 > show options

Writing/Porting Modules — Boilerplate Strategy

Don’t start from scratch. Copy an existing module from a similar category as the template:

cp /usr/share/metasploit-framework/modules/exploits/linux/http/bludit_upload_images_exec.rb ./my_exploit.rb

Key Ruby Mixins

MixinProvides
Msf::Exploit::Remote::HttpClientGET/POST request methods
Msf::Exploit::PhpEXEPHP payload generation
Msf::Exploit::FileDropperFile transfer + cleanup after exploit
Msf::Auxiliary::ReportReports creds/loot to MSF database

Module Structure Skeleton

class MetasploitModule < Msf::Exploit::Remote
  Rank = ExcellentRanking
  include Msf::Exploit::Remote::HttpClient
 
  def initialize(info={})
    super(update_info(info,
      'Name'        => 'App - Auth Bypass RCE',
      'Description' => %q{ ... },
      'Author'      => [ 'YourName' ],
      'References'  => [ ['CVE', '2019-XXXX'] ],
      'Platform'    => 'php',
      'Arch'        => ARCH_PHP,
      'Targets'     => [ [ 'App v1.0', {} ] ],
      'DefaultTarget' => 0
    ))
    register_options([
      OptString.new('TARGETURI', [true, 'Base path', '/']),
      OptString.new('USERNAME', [true, 'Login user']),
    ])
  end
 
  def exploit
    # HTTP requests + payload delivery logic here
  end
end

Naming Rules

  • Use snake_case: my_exploit.rb (not my-exploit.rb)
  • Use hard tabs for indentation (MSF enforces this)

🛠️ Troubleshooting & Edge Cases

ProblemCauseFix
Custom module not found after reload_allWrong file locationPlace in ~/.msf4/modules/exploits/ — not in MSF install dir; run reload_all
Module fails with Ruby errorSyntax issueTest: ruby -c ~/.msf4/modules/exploits/custom/module.rb; common error: missing end or wrong include
Payload not working in custom modulePayload mixin not includedAdd: include Msf::Exploit::Remote::Tcp and call connect before payload
Module options not appearingMissing def initialize register_optionsVerify OptString.new('TARGETURI', [true, 'Path', '/']) syntax in initialize block
Session not created after successful exploitPayload not stagedEnsure handler is called with start_handler or exploit uses handler mixin

📝 Reporting Trigger

Finding Title: Custom Metasploit Module Developed for Proprietary Vulnerability Impact: Custom MSF module operationalizes a novel or proprietary vulnerability for reliable exploitation with integrated session management and post-exploitation capability. Root Cause: Target running vulnerable proprietary software with no vendor patch or existing public exploit. Recommendation: Notify vendor via coordinated disclosure. Apply vendor patch when available. Implement WAF/IPS rule for the specific vulnerability until patched. Consider removing or isolating the vulnerable service.

🔗 Related Nodes

Graph View

Backlinks