Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Architecture and Modules

Anatomy of a Metasploit Module: Reading the Ruby Safely

Learn how a Metasploit module is structured in Ruby: metadata, references, options, the run or check method, and how to read a module's code to understand what it does.

Metasploit modules are small Ruby classes. Reading one is the best way to understand what a module will really do before you run it, and it is a core skill for any tester or defender. You do not need to be a Ruby expert: modules follow the same template, and most of the interesting information sits in a block of metadata at the top.

This lesson shows a harmless, invented auxiliary module as read-only Ruby (it is shaped like real modules but only prints a message). The Python stand-ins parse and validate the same kind of structure.

The skeleton

Ruby
# Example only: a harmless module that reports a banner it would check.
class MetasploitModule < Msf::Auxiliary
  include Msf::Auxiliary::Scanner

  def initialize(info = {})
    super(
      update_info(
        info,
        'Name'        => 'Example Service Version Check',
        'Description' => 'Reports the version string of an example service.',
        'Author'      => ['Course Author'],
        'License'     => MSF_LICENSE,
        'References'  => [['URL', 'https://example.com/advisory']]
      )
    )
    register_options([
      Opt::RPORT(8080)
    ])
  end

  def run_host(ip)
    print_status("#{ip}: would query port #{rport} for a version string")
  end
end

The pieces, from top to bottom:

  1. Class declaration. Every module is class MetasploitModule inheriting from a base class that matches its type (Msf::Auxiliary, Msf::Exploit::Remote, Msf::Post, ...).
  2. Mixins. include lines add behaviour: Scanner runs run_host once per address in RHOSTS and handles threads.
  3. initialize with update_info. This is the metadata block: name, description, authors, license, references, platform, targets, disclosure date, rank and notes.
  4. register_options. Declares options; OptString, OptInt, OptBool, OptAddress, OptPath and others validate types.
  5. Action methods. run or run_host for auxiliary modules, exploit and check for exploits, run for post modules.
flowchart TD
    A["class MetasploitModule < Msf::Auxiliary"] --> B["include mixins"]
    B --> C["initialize: update_info (metadata)"]
    C --> D["register_options"]
    D --> E["run_host / run / exploit / check"]

Metadata first, behaviour last. Read in that order.

What to read before running any module

When you are about to run a module you have not used before:

  • Description and references. What flaw or service is it about? The references list CVE numbers, vendor advisories and write-ups.
  • Rank and Notes. The Notes field can list stability (CRASH_SAFE, CRASH_SERVICE_DOWN), side effects (IOC_IN_LOGS, ARTIFACTS_ON_DISK) and reliability. These tell you what footprint the module leaves, which you should mention in the report and warn the owner about.
  • Options with defaults. Default ports, paths and credentials in the code tell you what a defender could detect.
  • The action method. What network traffic does it send? Does it write files, change settings or only read?

info prints most of this in the console; the source file has all the detail. The source path for a loaded module is shown by edit (which opens it in your editor) or by info -d.

Reading the code of a third-party module before running it on a client network is standard practice. A module is just code, and a downloaded module could do something you did not expect.

Parsing metadata

The stand-in below treats a module's metadata as a Python dictionary and checks the same things a reviewer does: is there a description, at least one reference and a rank, and does Notes declare side effects?

Python Review a module's metadata

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Options and validation

Option definitions give each option a name, a required flag, a default and a description. Typed option classes reject bad values early: a port must be an integer in range, an address must parse. The next stand-in reproduces that behaviour with plain Python functions.

Python Typed options reject bad values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Writing your own modules

You can write modules yourself and drop them in ~/.msf4/modules/<type>/... (see the architecture lesson). Reload with reload_all. Good practice for authors: give a complete description, cite references, declare Notes, implement check for exploits, avoid destructive defaults and never hard-code targets. Building small auxiliary modules (a banner reader for your own service, for example) is a good way to learn the API.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which base class does an auxiliary module inherit from?

    Each module type has a matching base class; auxiliary modules use Msf::Auxiliary.
  2. 2. What does the Scanner mixin do?

    The scanner mixin iterates over the targets, handling threading for you.
  3. 3. Why read a module's Notes field?

    Notes describe crash risk, logs and files left behind, which you must know and report.
  4. 4. Where should custom modules go so that updates do not overwrite them?

    The user module directory is scanned too and is not touched by updates.

Summary

  • A module is a Ruby class: metadata in update_info, options in register_options, behaviour in an action method.
  • Read the description, references, Notes, defaults and action method before running a module.
  • Typed options validate input early.
  • Put your own modules in ~/.msf4/modules and reload with reload_all.

Next: Options, the Datastore and Resource Scripts