> For the complete documentation index, see [llms.txt](https://capcap-1.gitbook.io/capcap/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://capcap-1.gitbook.io/capcap/readme/ctf-modules/vulnerability-assessment/msf/writing-and-importing-modules.md).

# Writing & Importing Modules

[**https://nostarch.com/metasploit-2nd-edition**](https://nostarch.com/metasploit-2nd-edition)

[**https://www.rapid7.com/blog/post/2012/07/05/part-1-metasploit-module-development-the-series/**](https://www.rapid7.com/blog/post/2012/07/05/part-1-metasploit-module-development-the-series/)

**Three Ways to Get New Modules**

**1. Full update** — gets everything at once

```bash
apt update && apt upgrade metasploit-framework
```

**2. Manual import from ExploitDB** — when you need one specific module

```bash
# Search from terminal without browser
searchsploit nagios3

# Filter only Ruby files (MSF-compatible)
searchsploit -t Nagios3 --exclude=".py"
```

Look for `.rb` files — these are Ruby scripts potentially compatible with MSF. Note: not all `.rb` files work in MSF, only ones written as proper Metasploit modules.

**3. Write your own** — covered below

***

**Installing a Module Manually**

**Step 1 — Download the `.rb` file from ExploitDB**

**Step 2 — Copy to correct directory**

```bash
cp ~/Downloads/9861.rb /usr/share/metasploit-framework/modules/exploits/unix/webapp/nagios3_command_injection.rb
```

**Naming rules — important:**

* Use `snake_case` only
* Only alphanumeric characters and underscores
* No dashes
* Wrong naming = MSF won't recognize the module

**Step 3 — Load it into MSF**

Two ways:

```bash
# Option 1 — launch with module path
msfconsole -m /usr/share/metasploit-framework/modules/

# Option 2 — reload inside running msfconsole
msf6 > reload_all
msf6 > use exploit/unix/webapp/nagios3_command_injection
```

***

**Directory Structure**

Two important locations:

| Path                               | Purpose                                   |
| ---------------------------------- | ----------------------------------------- |
| `/usr/share/metasploit-framework/` | Main install, all modules/plugins/scripts |
| `~/.msf4/`                         | User-level, symlinked to above            |

If `~/.msf4/` is missing subdirectories, create them manually with `mkdir` to match the main structure before copying modules there.

***

**Porting Scripts to MSF (Overview)**

When you find a Python/PHP exploit that doesn't have an MSF module, you can port it to Ruby.

**Every MSF module has:**

```ruby
class MetasploitModule < Msf::Exploit::Remote
  Rank = ExcellentRanking

  include Msf::Exploit::Remote::HttpClient   # acts as HTTP client
  include Msf::Exploit::PhpEXE              # generates PHP payload
  include Msf::Exploit::FileDropper         # handles file cleanup
  include Msf::Auxiliary::Report            # logs to MSF DB
```

These `include` statements are the **mixins** mentioned earlier — they pull in functionality the module needs.

**The `initialize` block fills in:**

* Module name, description, author
* CVE references
* Target platform/architecture
* Options (RHOSTS, credentials, wordlists etc.)

**Practical example — changing a password option to a wordlist:**

```ruby
# Single password
OptString.new('BLUDITPASS', [true, 'The password for Bludit'])

# Changed to wordlist for bruteforce
OptPath.new('PASSWORDS', [true, 'The list of passwords',
    File.join(Msf::Config.data_directory, "wordlists", "passwords.txt")])
```

***

**You will need:**

* `searchsploit` to find modules not in MSF
* How to copy `.rb` files to the right directory
* `reload_all` to load new modules without restarting
* Naming conventions (snake\_case, no dashes)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://capcap-1.gitbook.io/capcap/readme/ctf-modules/vulnerability-assessment/msf/writing-and-importing-modules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.