The user configuration directory can be overridden via environment
variables or configuration files.
In the current implementation `Msf::Config.config_directory` should be
utilized for consistent location reporting. `Msf::Config.get_config_root`
is reserved to generation of a default location and should be considered
`private` as it ignores some injected configuration options. Currently
autoloading does not allow application of the `private` keyword to this method,
requiring guidance during development that module writers should access the
full configured `user` value of `Msf::Config.config_directory`.
Adds additional offsets for various Windows 2000 targets.
Replaces raw socket TCP with HttpClient. This works fine in testing.
Fixes default payload, adds docs and notes.
This change fixes a bug in the confluence_widget_connector
exploit module to prevent it from crashing when the HTTP
response body received in the get_java_property method is
empty or does not match expected regex.
The check method will not work regardless of whether or not there is a
cloned repository. The response can be analyzed using a random,
non-existant repo.
- Fixed exception handling variable attribution
- Tried to change JavaDeserialization Util to JavaDeserialization mixin
instead
- Changed the fail reason when the connection is unsuccessful
This change sets the MeterpreterTryToFork advanced
payload option to true by default for the Linux target
in the aerohive_netconfig_lfi_log_poison_rce module.
Adds a spec targeting a single method in the `lotus_domino_hashes` module. This is a start on
offering example on how a spec can be written to test part of the code in a module using example
responses from a unit testing perspective.
If the listener that handles the incoming connection request replies
with STATUS_ACCESS_DENIED, the API will return ERROR_ACCESS_DENIED to
the caller. This is the behavior of Metasploit's capture module as well
as Responder.
The spec result has a precondition in the expectations.
The RACK_ENV must be `development` and causes the test to
fail based on test execution order in scenarios where a
previous test set a different expectation in the env.
Added an aux module that can perform offline decryption of NetScaler
config files. The module is able to decrypt secrets using well-known
static keys as well as the new Key Encryption Key (KEK) scheme.
This is the initial commit, and some functionality is lacking: there is
currently no loot storage of secrets, and the module cannot decrypt
-passcrypt entries from legacy configuration files.
The `crawler_process_page` method in HttpCrawler assumes that the
`page` object passed into the method is not nil when formatting the
`msg` string for printing to console.
Address the assumption with a ternary check leaving the `|| "ERR"`
handling for `page.code` itself being nil inside the assignment
when page is not nil.
Testing:
`Error accessing page undefined method '[]' for nil:NilClass` is
no longer being thrown when scanning an odd HTTP service.
Net-NTLM (v1 and v2) hashes were being duplicated when
stored in the database due to the unique data in the challenge
dispite being the same. This fixes that issue
This exploit module leverages an improper input validation
vulnerability in MyBB prior to 1.8.30 to execute arbitrary
code in the context of the user running the application.
Despite being called ntlm_session, these hashes are capable of being
cracked as the John 'netntlm' format. Additionally the format is
reported as NTLMv1-SSP in similar tools.
Added verbose output to the RSA and x509 extraction functions for
troubleshooting.
Changed error handling to just print an error message instead of
throwing an exception temporariliy.
- Now, it exposes 4 methods to manage scheduled tasks: `#task_create`,
`#task_start`, `#task_delete` and `#task_query`
- Adds `#check_compatibility` to check the OS version and make sure
`schtasks.exe` and `reg.exe` options are compatible
- Adds `#log_and_print`to print log messages on the console (using
`vprint_*` methods) and in the MSF logs at the same time
- `#get_system_privs` now takes care of checking if the session is a
Meterpreter session and if it has loaded the appropriate extension
- Adds `#run_one_off_task` to run a command on a remote host by using
another scheduled task
- Adds `#add_reg_key_value` to restores the Security Descriptor registry
key value to unhide the task
This adds a temporary Gemfile entry to a branch with all the necessary
dependencies merged together. It should be removed before the PR is
landed once an updated RubySMB gem can be released.
Space = 0 is a special case implying that the smallest payload possible
should be used. It's used by msfvenom when the --smallest flag is set.
It should not cause Metasploit to raise an exception.
Fixes#16471
Add new aux module vcenter_offline_mdb_extract for extracting IdP
credentials, certificates and keys from a vCenter backup file.
Added module documentation.
Changed the line that parses the input for the nessus_connect password. It will now split the user input by the last occurrence of the at sign (@) instead of the first occurrence. This will prevent improperly parsed passwords due to an at sign (@) in the password.
Extra modifications:
- Promote advanced options HttpUsername and HttpPassword
- password is not really necessary, but if one have credential, can
use this module as an exec
- Fixed print statement on check
- Splitted execute_command in two, because we also send a command on the check
methods, however we don't need the checks that are in the execute_command
- Change module name and description
- Added author from the PoC
- Added reference
- Added payloads, targets and notes
- Removed headers used during the tests
- use keep_cookies instead of grabbing and set manually
- separate login code to its own method
- check response is not nil before calling get_html_document method
- clear cookie jar in exploit method and authenticate if user disable AutoCheck option
When using `head` to filter the PR list user or head organization
and branch name in the format of `user:ref-name` or `organization:ref-name`
are required.
* The closing quotes after the `VALUE` attribute were not escaped. This
commit adds them
* The regex assumed that the short name does not contain whitespace.
I am looking at a Domino instance where the short name DOES contain
whitespace. This commit changes the regex such that the value is
assumed to not contain a quote before the closing quote. Of course,
there could be an escaped quote inside quotes in the HTML source, but
if we want to do it properly, we'd need an HTML parser which exceeds
my modest ruby skills.
* The fields `$dspHTTPPassword` and `dspHTTPPassword` (without the
dollar sign) can both contain the hash. The code assumed that only up
to one of those fields contain a hash. This leads to the hash being
printed twice in the output in my case.
Extensive refactoring to move away from directly manipulating datastore
options and use local variables instead.
The initial template generation method has been redesigned to use an
external file via Erubi::Engine which is much cleaner vs. jamming a
multiline string into the module.
Response HTML from vCenter is now parsed with Nokogiri HTML vs. pulling
it out with regex.
Registered options have been reworked, following suggestions and
feedback. The use of VHOST in particular eliminates the need to pass
RHOSTS to the template and makes the module behave more closely to "real"
vCenter (i.e., always uses FQDN for the destination).
Added advanced datastore options to control the token lifetime
NOT_BEFORE and NOT_AFTER skew, in seconds. This also uncovered a bug with
the way I was deriving Zulu time which skewed based on the local system
time zone offset from Zulu; this has been fixed.
Corrected a stupid typo in the validate_fqdn method (don't need to check
for capital letters if the test string is always downcase...)
validate_idp_options now uses File.binread and can process certs in keys
in DER or PEM instead of just PEM.
Code optimization, particularly around error handling; other minor
tweaks based on improved understanding of the Framework's capabilities.
Many style changes and modifications based on suggestions and feedback.
Documentation was updated to reflect reality.
Currently this module doesn't account for Server builds 2016 and above, nor Windows 10 builds. This PR fixes the `sysinfo` comparison to allow later builds.
Note: Many other modules have this problem, and it's probably worth Rapid7 staff time to standardize the usage of build comparisons inside modules.
Some smtp servers only give out creds when promted.
Now there exists a mondule option 'AUTHPROMPT' to indicate
whether or not the auth prompt is required by the server.
This commit fix the issue #16138 by adding
support to old key exchange algorithms in
the net/ssh lib by defining the
append_all_supported_algorithms to true.
In an effort to offer an opportunity for security review and approval
of gem updates after a version is tagged and pushed a new `bundle update`
be preformed and a branch pushed containing the isolate `Gemfile.lock` changes.
This new action will open a PR for committers to review and an land after
completing security review of updates in the gems.
We locate the dyld_shared_cache in memory to find and resolve the
functions we need in libdyld.dylib. We retain the original dyld location
method on osx versions before Sierra.
Explicitly set length for osx x64 initial stage
The rdx register, used for passing the payload length, is being
clobbered by a system call in the new MacOS version. Instead of relying
on the register being untouched, we set it equal to the payload length.
The formatted string containing the JNDI URL can contain further
formatted strings within it sourcing data from the formatting Java
context. This is the mechanism by which this module already gathers
target information.
Expand this capability by permitting the user to supply their own
query string variables separated by '^' and comparing the output
to these inputs for extraction of relevant exposed values.
To help with targeting for the pending-in-PR exploit module, add OS
detection capabilities as well.
Remove duplicated print_status messages. Use respond_to? instead of
methods.include?. Simplify payload generation. Fix naming for the rst
capture thread.
In about 16% of all cases the random value of "tablename" will be set to
a value starting with a number, which needs to be quoted before the
query is sent to the postgres server. Otherwise the query fails with the
message "Exploit failed". This is what happened to me, you can see an
example with a table name set manually here:
msf6 > use exploit/multi/postgres/postgres_copy_from_program_cmd_exec
[*] Using configured payload cmd/unix/reverse_perl
msf6 exploit(multi/postgres/postgres_copy_from_program_cmd_exec) > set RHOSTS 192.168.2.2
RHOSTS => 192.168.2.2
msf6 exploit(multi/postgres/postgres_copy_from_program_cmd_exec) > set tablename 123test
tablename => 123test
[...]
msf6 exploit(multi/postgres/postgres_copy_from_program_cmd_exec) > run
[*] Started reverse TCP handler on 192.168.2.1:4444·
[*] 192.168.2.2:5432 - 192.168.2.2:5432 - PostgreSQL [...]
[*] 192.168.2.2:5432 - Exploiting...
[!] 192.168.2.2:5432 - 192.168.2.2:5432 - Unable to execute query: DROP TABLE IF EXISTS 123test;
[-] 192.168.2.2:5432 - Exploit Failed
This can be verified manually as follows, quoting the table name works:
$ psql --user postgres -W -h 192.168.2.2 template1
[...]
template1=# DROP TABLE IF EXISTS 123test;
ERROR: syntax error at or near "123"
LINE 1: DROP TABLE IF EXISTS 123test;
^
template1=# DROP TABLE IF EXISTS "123test";
NOTICE: table "123test" does not exist, skipping
DROP TABLE
With the patch, the script also works with table names which start with
numbers:
msf6 exploit(multi/postgres/postgres_copy_from_program_cmd_exec) > run
[*] Started reverse TCP handler on 192.168.2.1:4444
[*] 192.168.2.2:5432 - 192.168.2.2:5432 - PostgreSQL [...]
[*] 192.168.2.2:5432 - Exploiting...
[+] 192.168.2.2:5432 - 192.168.2.2:5432 - 123test dropped successfully
[+] 192.168.2.2:5432 - 192.168.2.2:5432 - 123test created successfully
[+] 192.168.2.2:5432 - 192.168.2.2:5432 - 123test copied successfully(valid syntax/command)
[+] 192.168.2.2:5432 - 192.168.2.2:5432 - 123test dropped successfully(Cleaned)
[*] 192.168.2.2:5432 - Exploit Succeeded
[*] Command shell session 1 opened (192.168.2.1:4444 -> 192.168.2.2:51734 ) at 2022-03-24 10:15:33 +0100
Does what it says:
```
[*] Checking if the target is a Virtual Machine ...
[+] This is a Qemu/KVM Virtual Machine
[*] Post module execution completed
```
The smb_shadow module can confirm the server smb version supported with
the ConfirmServerDialect option. The shadow_mitm_dispatcher closes each
stream before opening a new one to prevent leaking file descriptors.
A number of recent payload adds do not conform the patterns
used for suggesting spec configurations. Manually added these
tests to remove warning in rspec run.
Factory is provided by mixin;
Removed the options that were the same as the defaults;
Adjusted the exception to proper feedback the user. There was a return
as incorrect when it was indeed unable to negotiate the key exchange.
When utilizing `Anemone` to crawl pages using `Rex` sockets
Framework common `SSL` settings can pull from standardized options.
This change enables more fine grained user control and avoids issues
with missing or deprecated SSL versions in newer Ruby versions.
See #16262 for context. This will select reverse_bash if no required
commands are specified, which should be suitable for most environments.
The RequiredCmd payload compatibility key can be specified to override
this behavior by marking the commands that are available.
Since Android 11, APK contents must be signed with signature scheme
v2 or higher (v2/v3/v4). In order to maintain compatibility with
older versions of Android, APKs can also be signed with v1 (after
first signing with v2/v3/v4), but this is not mandatory.
When using a template apk file, the APK library now attempts to
extract signing scheme v1 certificate details (using keytool)
and falls back to extracting v2/v3/v4 certificate details (using
apksigner) if the APK is not signed with signing scheme v1.
Fixes#16295.
This commit fix the issue #16138 by adding support to old key
exchange algorithms in the net/ssh lib by defining the
`append_all_supported_algorithms` to `true`.
If we have the API token we can execute command using the parameter
`filter_func` or `script`, and if there is an IP restriction
enabled by the plugin ip-restriction we can bypass this restiction if
the plugin batch-request is also enabled.
As the Shodan is checking the UserAgent to decide which content-type it
will deliver, the default user-agent is causing it to reply a html page.
This commit overwrite the default user-agent the the module shodan_search
to 'Wget' that works in on the shodan API.
Added module that laverage the default admin API token for Apache APISIX
to add malicious route which leads to the remote LUA code execution
through the script parameter added in the 2.x version.
The ShadowMitmDispatcher now supports arbitrary size packets. The
ShadowMitmDispatcher now supports SMB3. The ShadowMitmDispatcher no
longer interferes with existing sessions.
fix URLs not resolving
add csv export to references
fix URLs not resolving
pdf not pd
missed a url change
remove extra recirectedfrom fields
remove extra file
fix ovftool url accidental replacement
When dealing with SMTP servers the communication needs to flow
a known protocol. To ensure the socket is in the correct state
after a send and receive it needs to be read until a line return
a response code followed by a `space` and additional data and `\r\n`
or the response code immediately followed by `\r\n` is returned.
The ShadowMitmDispatcher must be initialized with an interface, mac, and
ip address as keyword arguments. This prevents dispatchers from
retrieving the same network configuration multiple times.
Cases
[x] User defined wrong log file
[-] Exploit aborted due to failure: unexpected-reply: Log file
/var/www/log.log seems doesn't exit
[x] module doesnt detect the log file
[-] Log file does not exist /var/www/storage/logs/laravel.log
[-] Exploit aborted due to failure: bad-config: Log file is
required, however it was defined nor it was not automatically detecte
[x] site doesnt respond with error, module unable to find the log
directoy
[-] Unable to automatically find the log file. To continue set
LOGPATH manually
[-] Exploit aborted due to failure: bad-config: Log file is
required, however it was defined nor it was not automatically detected
[x] site with debug mode false
[-] Exploit aborted due to failure: not-vulnerable: The target is
not exploitable. "set ForceExploit true" to override check result
When connecting to an SMTP server after `HELO` and auth
complete there can be additional data sent from the client
that sits in the socket queue. Adding a `get_once` after connection
has settled ensure any pending for extension responses are cleared.
As we can't determine with certainly whether the target is vulnerable the check method should return appear instead of vulnerable.
Co-authored-by: Simon Janusz <85949464+sjanusz-r7@users.noreply.github.com>
Use PacketFu::Utils.whoami? instead of PacketFu::Utils.default_int to
retrieve the ip address for a network interface. The Exploit class for
the Shadow Dispatcher is now a module.
The MitmDispatcher is now the ShadowMitmDispatcher to help prevent name
confusion. Updated the ShadowMitmDispatcher to use native rex lib calls
to decode binary fields.
The MitmDispatcher reduces code repetition and enables the use of
standard RubySMB syntax. I have noticed increased power draw when using
the new dispatcher compared to the previous (less stateful) approach.
Please fill out each section below, otherwise, your issue will be closed. This info allows Metasploit maintainers to diagnose (and fix!) your issue as quickly as possible.
We will also accept demonstrations of successful module execution even if your module doesn't meet the above conditions. It's not a necessity, but it may help us land your module faster!
Demonstration of successful module execution can take the form of a packet capture (pcap) or a screen recording. You can send pcaps and recordings to [msfdev@metasploit.com](mailto:msfdev@metasploit.com). Please include a CVE number in the subject header (if applicable), and a link to your PR in the email body.
If you wish to sanitize your pcap, please see the [wiki](https://github.com/rapid7/metasploit-framework/wiki/Sanitizing-PCAPs).
If you wish to sanitize your pcap, please see the [wiki](https://docs.metasploit.com/docs/development/get-started/sanitizing-pcaps.html).
This folder maintains the docs for https://docs.metasploit.com/ and https://github.com/rapid7/metasploit-framework/wiki
## Architecture
How it works:
-`build.rb` - The main entry point for generating the docs site from the old Github Wiki format files within `metasploit-framework.wiki/`
-`navigation.rb` - Stores the mapping of `metasploit-framework.wiki` files to the website's navigational structure
-`metasploit-framework.wiki/` - The raw markdown documentation files. Modify these files when updating the site. These files originally came from https://github.com/rapid7/metasploit-framework/wiki
-`metasploit-framework.wiki.old/` - A separate clone of https://github.com/rapid7/metasploit-framework/wiki
Behind the scenes these docs are built and deployed to https://docs.metasploit.com/
maintainer_message="#{MAINTAINER_MESSAGE_PREFIX} Please do not modify this file directly, create a pull request instead -->\n\n"
user_message="#{USER_MESSAGE_PREFIX} This Wiki page should be viewable at [#{new_url}](#{new_url}). Or if it is no longer available, see this page's [previous history](#{history_link})**\n\n"
run_command("git remote add -f wiki #{File.join(Dir.pwd,OLD_WIKI_PATH)}",exception:false)
# run_command("git remote update wiki")
run_command("git merge -m 'Migrate docs from https://github.com/rapid7/metasploit-framework/wiki to main repository' wiki/#{new_wiki_branch_name} --allow-unrelated-histories")
In 2017, we published our first open roadmap for Metasploit development. How did we do? For achievements:
* The Metasploit data model backend: we did a lot of design work on this, and got a couple of initial Proof-of-Concept project built. You can see a video of it here: <https://www.youtube.com/watch?v=hvuy6A-ie1g>. In the mean time, we started merging parts of the main development branch
* The first pass of external session handling landed with the metasploit-proxy project.
* Independent modules that run in isolation _did_ land, along with a hand full of new modules demonstrating the advantages of the design, including multi-language support.
* The ruby_smb project made a lot of progress, with support incorporated into several existing modules. Full client-side support is also available for testing now.
* Native iOS and macOS support landed, along with many new IoT and router exploits.
* Meterpreter shrank almost 4x thanks to the new cryptTLV packet obfuscation support, and the removal of OpenSSL.
Things we didn't quite finish:
* Metasploit's RESTful interface was not complete in 2017, so we will continue it into 2018.
* Session handling as a separate process was implemented with the <https://github.com/rapid7/metasploit-aggregator> project, but more work needs to be done to improve scalability and usability.
* Asynchronous session support remains on the drawing board.
* SOCKS5 support did not land, but Metasploit did gain a lot more support for running modules externally as separate processes, and gained initial support for running modules in Python.
* Modernized payload generation with new tools continues to be researched.
Starting in 2017, we will provide an open roadmap for setting our goals for the year. The goals are based on many discussions we have had over the past year with users, developers, and customers. The intent is to provide focus for core developers and contributors alike, so that we can together work toward a common vision for how we want Metasploit to evolve.
This year, the themes for Metasploit are modularity, reusability, and reliability.
Metasploit has grown organically over the years into a very large project, combining thousands of modules, payloads, a database, session handling, user interaction and more into a single monolithic application. While the design has served us well, it has reached some limits for maintainability and agility. While we continue to refactor, improve, and reorganize Metasploit, large-scale improvements become increasingly difficult and highlight fragility in the overall system, due to its highly interdependent design.
We want to allow users to effortlessly contribute to the portions of Metasploit they are interested in, and be able to reuse code, both from inside and and outside of the project. Language and licensing constraints have presented barriers to users, both real and imagined. Python, Go, C# and other languages are dominating influences on the infosec community. We would like to be able to welcome more developers, researchers, and tooling into the Metasploit ecosystem, taking advantage of the best-in-breed and avoiding not-invented-here syndrome wherever possible.
In short, we want to develop reusable, modular, and reliable services to enable researchers, pen-testers, students, and red-teamers to work efficiently, have access to the latest technologies and techniques, and to continue to grow the Metasploit community.
## The roadmap
* The Metasploit data model backend should be separated into its own project. Plans include a data service that provides a RESTful interface, both an event-oriented and classic workspace-oriented view of incoming data, improved performance, and easy direct interoperability with other tools.
* Session handling should be able to operate independently of framework, allowing users to share sessions and allowing servers to be as performant, reliable, and light-weight as possible. We have already begun a project called 'metasploit-aggregator' which is a first generation of this design. Once this is complete, direct integration into other frameworks should also be possible.
* Metasploit should support asynchronous sessions. Many testers today use asynchronous frameworks like Empire to maintain light-weight persistence or a footholds into a network, then have to pivot to Meterpreter for interactive sessions. We would like to be able seamlessly support both modes of operation, including the ability to run post exploitation modules and modules over pivots asynchronously as well.
* Metasploit should support running exploit and auxiliary modules in an isolated mode. Plans are underway to support supporting an RPC-style module API to Metasploit framework, providing core services like payload and session handling, network routing, reporting and logging. Modules are run as child processes to Metasploit, and are only loaded into memory as-needed. Networking from a module point-of-view will be handled via SOCKS5 proxy support, hooking the child environment, or remote API calls, largely removing the need for specially-crafted socket objects or changes to 3rd-party protocol libraries. Modules, when written for the Metasploit API, could even be tested and used independently from the full Metasploit framework.
In addition to these primary goals, we'd also like to explore:
* *SMB 2.0* SMB 1.0 increasingly being disabled in many networks, making Metasploit modules using this protocol ineffective. We would like to implement at least server-side support for SMB 2.0, both for sharing files and for named pipe communications.
* *iOS and macOS support* The mettle and python meterpreter payloads will continue evolving to further support OS X and iOS, along with more post exploitation support.
* *Native Android support in Mettle* We began the work last year with mettle now supporting all of the basic operations for a Meterpreter implementation. We would like to continue adding Android post-exploitation capabilities to mettle as well.
* *Streamlining Windows Meterpreter* mettle soon will replace the original POSIX meterpreter, which will reduce the size of the Windows meterpreter. Switching from OpenSSL to native SChannel support will simplify and shrink Windows meterpreter, allowing to focus on what it supports best.
* *Router and IoT research* We would like to continue research and support for embedded device exploitation and first-class support for resource-constrained environments.
* *Modernizing payload generation* We are investigating being able to integrate with third-party toolchains for building assembly, C, .NET, Java, on the fly, making it easy for a user to acquire the and use the tools, while providing first-class support for many architectures and platforms.
Release notes inform our users about the stuff we're shipping in each release. By looking at our release notes, our users should be able to easily understand what's new, what's fixed, and what's changed in the release. Therefore, **all PRs, except for minor fixes and tweaks, must have release notes.**
To add a release note to a pull request, you'll need to add it as a comment, like so:
You'll need to tag the comment for inclusion in the release notes by using the `# Release Notes` heading. After you apply the release notes heading, you can enter the release notes text you want to use.
That's it! After you add the release notes text, we'll be able to extract them from the pull requests when we run our release notes script and compile them into a single document.
## Writing Release Notes
Okay, so now that you know how to add a release note, you're wondering what you're supposed to write.
Basically, a release note summarizes the pull request and describes the value of the fix/feature to the user. Each release note has a title, a PR number, and a brief description.
Here's an example of what a release note looks likes:
>The Beholder plugin automatically captures keystrokes, screenshots, and webcam snapshots from your active sessions. Run this plugin to collect data from your compromised targets every 30 seconds.
## Types of Release Notes
There are three types of release notes:
* [Enhancement](#release-notes-for-enhancements)
* [Fix](#release-notes-for-fixes)
* [Modules](#release-notes-for-modules)
### Release Notes for Enhancements
An enhancement indicates that an improvement or new feature has been added to the framework. Enhancements include things like auxiliary modules, post-exploitation modules, and new payloads.
When you write release notes for an enhancement, you should try to answer the following questions:
* What is the enhancement?
* Why is it valuable or important to users?
* How can they use it?
For example, the following is a release note for an enhancement:
> The new 'resolve' command enables you to perform DNS lookups with Meterpreter, without leaving the session to run additional modules. To resolve host names on the target, you can run the 'resolve' command followed by the host name. For example, in the Meterpreter prompt, you can type something like 'resolve rapid7.com' to view the host resolutions for Rapid7.
### Release Notes for Fixes
A fix is for an issue that caused a particular feature or functionality to not work the way it's expected to work. Basically, a defect indicates that something was broken, and we've fixed it.
When you write release notes for a fix, you should try to answer the following questions:
* What was broken?
* How was it fixed?
* Why is this important to users?
Here's an example for a fix:
> The email header contained duplicate date and subject headers, which caused email servers like AWS SES, to reject the emails. This fix removes the duplicate headers so that campaigns can send emails successfully.
### Release Notes for Modules
An exploit is a module that takes advantage of a vulnerability and provides some type of access to the target. We call out exploits explicitly because they're the hotness.
When you write release notes for an exploit, you should try to answer the following questions:
* What vulnerability is the module exploiting?
* What type of access can you achieve with the module?
* Do you need credentials to exploit the vulnerability?
And finally, here's an example for exploits:
> This module allows you to exploit HP Data Protector, a backup and recovery system, to remotely upload files to the file share. Versions 6.10, 6.10, and 6.20 are vulnerable. You don't need to authenticate to exploit this vulnerability.
Maintainers can assign labels to both issues and pull requests.
### Docs
Documentation changes, such as YARD markup, or README.md, or something along those lines.
### External
Touches something in /external, or the Gemfile, or something like that.
### Heartbleed
Has to do with heartbleed. This will go away soon, but there are three outstanding still...
### Library
Touches something in /lib.
### Meterpreter
Has to do with Meterpreter, or depends on a Meterpreter change to land to work.
### Misc
Plugins and scripts, anything that's not otherwise defined.
### Module
Touches something in /modules
### Specs
Has specs (an rspec test)
### Newbie Friendly
Something that's pretty easy to test or tackle.
### attic
When we move something to the attic it means that what you submitted is a thing that we want but the circumstances were not quite right for landing it. Sometimes this is on us, and sometimes the contribution needs more work. We recognize that contributors work on the PRs they submit at their own pace. Take a look at the comments and review suggestions on your PR, and feel free to re-open it if and when you have time to work on it again. Don't think you'll be able to get it across the finish line? Find a community champion to do it for you.
### Needs unique branch
Your submitted a PR from your `master` branch.
Because of how GitHub tracks changes between branches and what got added in a particular PR, we don't accept contributions from the `master` branch of your fork. All branches are [required to be unique](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md#code-contributions). If your PR is closed because of this, create a new branch with that code and we'll be happy to look at it again!
```
git checkout -b <BRANCH_NAME>
git push <your_fork_remote> <BRANCH_NAME>
```
This helps protect the process, ensure users are aware of commits on the branch being considered for merge, allows for a location for more commits to be offered without mingling with other contributor changes and allows contributors to make progress while a PR is still being reviewed.
As Metasploit modules continue to grow in number and capability the current separation of module information by type grows more cumbersome. Starting next year, we want all the files related to a module (docs, libraries, sources, build info, etc.) to live as closely together and be as hackable as possible. To this end, we have come up with the concept of "module bundles" to help improve module dependency isolation and locality of information. We hope the format will prove flexible enough to accommodate the wide range of modules we have and uniform enough to not cause confusion among community members and contributors. Eventually, we may even be able to package each module separately for distribution.
Whether or not this bundled format will support the old style of module is uncertain. It could be made to work, I think, but it would require a fair bit of effort and ingenuity to work cleanly. For simplicity, I will describe the bundle concept as it applies to external/coldstone modules and then describe potential adaptations at the end.
## Directory structure
Example complicated Ruby module:
```
$ tree --dirsfirst --charset=ascii -F bundled_module/
bundled_module/
|-- data/
| `-- stack_smash
|-- docs/
| |-- bundled_module.md
| |-- poc.py
| `-- success.pcap
|-- lib/
| |-- foo/
| | |-- bar.rb
| | `-- baz.rb
| `-- foo.rb
|-- src/
| `-- stack_smash.s
|-- templates/
| `-- exploit.ps.erb
|-- Dockerfile
|-- Gemfile
|-- Gemfile.lock
|-- Rakefile
|-- bundled_module.rb*
`-- metadata.json
```
## Aside: things I'm not sure of and reference vaguely
- Would the main executable be named after the module (same as the directory, maybe with extension), or given a
- standard name?
- Would the JSON metadata file be named after the module or given a standard name?
- Would we ever allow multiple closely related modules per directory? (eg. routersploit integration, impacts how we think about the above)
- If so or not, how would we deal with closely related functionality that has different options for different actions?
- Do things like client blobs (HTML, JavaScript, images, etc.) belong in `data/` or should we also have a `static/`? (`static/` seems to get a bit fiddly to me; `data/static/`?)
## Required files
To keep overhead to a minimum for hackers who are developing modules, we need to minimize files that the author will need to create, touch, and understand for most tasks (restated: every file an author must touch should be directly related to particular and specialized functionality that they want as part of the preparation or execution of a module). The most minimal module only requires the main executable to be present. When loading modules, framework will see a leaf directory without certain expected files and will generate the default ones automatically. This behaviour can be later augmented with guessing of which defaults based on what _is_ present in the directory.
- If Rakefile is absent, framework will generate one that references the shared rake tasks.
- If Gemfile is absent and the executable ends in .rb, framework will generate one that depends on the bridge libraries from source.
- If metadata.json is absent, framework will generate it using rake.
All this generation logic should be available as part of a standalone scaffolding tool.
## Keeping it all close
One of the drawbacks of the current module system is that all the files related to the development, documentation, and execution of a module live in different places. Some information, like dependencies, is only tracked implicitly or lossily in code or in the top-level specifications of framework. This makes programmatically determining what a module is, targets, or requires fraught with fragile code.
### Metadata
The metadata will be kept in JSON in a file (or several, see my uncertainties above) that is built by rake. Keeping the metadata cached per-module gives us several capabilities. First, updates look more logical in commits, and the files can be updated as part of the standard PR/landing process. Next, dependency tracking of when the metadata needs to be updated can be offloaded to standard build tool capabilities.
Because invoking rake has overhead, any metadata that exists should be considered correct during initial module discovery. Any modules without metadata should then have it generated via rake. Next, every module should have its metadata building task run to (and stale metadata replaced) ensure correctness. If a module is use'd before this process completes, it must have it metadata refreshed via rake if needed as part of the loading process. Since modules are independent, the whole discovery/refreshing process is parallelizable, reducing wall time.
In addition to the information we currently cache, we will want to cache any information a user might see or want to know so that, if the cached metadata is more recent than any module files, nothing has to be built or run to use the module. Notably, this includes options and module archetype (which in the future directly map options for user convince, vs the shim approach take today).
### Build info
All additional build info should be specified as tasks in the module Rakefile. As much a possible, this should also include building with IDE environments, like Visual Studio. Even if the binaries are checked in to reduce runtime requirements (see below), it is still invaluable to know how something was built in the first place.
### Blobs and sources
Sources are handy, it should be easy to find them! Now they will live in the module in the `src/` directory. Here the Rakefile can easily find them and transform them into the beautiful exploitation resources they were meant to be.
As much as possible, only sources should be checked into the tree. For super-specific platform targeting things though, that's not always feasible (eg. VisualStudio projects). It's times like these that the `data/` directory should be used. As mentioned above, the Rakefile should still be able to build the thing given the correct environment.
Blobs or assets without a checked-in source also belong in `data/`, like images or downloaded things. Things for client exploits to download should probably also go in here, like HTML files and static JavaScripts.
### Templates
Modules that use a large literal interspersed with runtime data should use the `templates/` directory to store templates. ERB should be used for printable data by Ruby, and equivalents for other languages (DTL, mustache, etc.). Binary data should maybe be blobs with accompanying offset listings?
### Docs
The `docs/` directory will contain the files that a user will reference when trying to understand module. This may include PoCs, markdown, pcaps, etc. The HTML we currently show to users would be generated from the module and files here using rake tasks.
### Additional tooling
One advantage that this directory structure gives us is the ability to write better tooling for it than we have for the current iteration of modules. One downside is that we will need it to in order to make the format accessible to hackers.
### Shared build tasks
Because all routine module-oriented tasks will be preformed with rake tasks, we will need to make the default actions for these tasks as intelligent and reusable as possible across different module types/implementations. A module author should not have to worry about writing plumbing they do not need (or is common) or messing with plumbing that is only tangentially related to their unique need. To that end, we should have sane defaults for the following at a minimum:
```
rake run -- Start module, hook up stdin/stdout to JSON-RPC
rake metadata -- Generate metadata JSON
rake tidy:code -- Run tidiness checks against the code
rake tidy:metadata -- Run tidiness checks against the metadata
rake doc:text -- Combine all docs into a plain-text, human readable thing
rake doc:html -- Similar to today's info -d
rake deps -- Install dependencies local to the current user, if possible
rake deps:check -- Check to see if a module can likely be run in the current environment
rake build -- Build files that need it, defaults: src/FILE.s => data/FILE (extracted from exe format), ...?
rake clean -- Remove generated files
rake clobber -- Reset to pristine, checked-out state
```
### Module generation
At the very least, we will also need tooling to create a mostly-empty but runnable module so that an author knows what to poke when writing. This skeleton can be augmented by questions that can help us use different archetypes, like payload vs. remote, or Ruby vs. Python. These commands could also point the author to relevant module writing articles/documentation.
### For classic modules
The biggest differences for classic modules are metadata generation and running. These can be accomplished with rake tasks, but it would involve starting up a whole framework instance for each module run. For efficiency, we will need to signal to framework to treat the module specially, perhaps having rake deps:check output/return a specific value when the module needs to be run inside of framework. Metadata would then be dumped directly from the framework loader, and instead of rake run, the classic module loader/runner would be run much as it is today. We will probably want to keep the rake tasks for these things for when we don't already have a framework instance handy.
This page lists the keys in use by [Metasploit committers][msf-committers] and
can be used to verify merge commits made to <https://github.com/rapid7/metasploit-framework>.
# Keybase.io identities
Keybase.io is used by Metasploit as an easy way to verify identities of committers. If you're a committer on metasploit-framework, and you need an invite, just ask.
<sup>Altering this table's layout will almost certainly break [import-dev-keys.sh](https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/import-dev-keys.sh), so please don't.</sup>
Note, keybase.io does **not require** your private key to prove your GitHub
identity. Actually sharing your private key with Keybase.io is a matter of
contention -- here's the usual argument [against][con-sharing], and here's one
thoughtful argument [for][pro-sharing].
# Tracking criteria
In order to get [@bcook-r7](https://github.com/bcook-r7) to track your key, you
alert him to its existence through some non-GitHub means, and verify your
GitHub username. That's all there is to it.
It would be sociable to track him (and everyone else on this list) back.
Tracking is essentially "trusting" and "verifying" -- see the much longer
discussion [here][tracking].
# Signing your commits and merges
Contributors are encouraged to sign commits, while Metasploit committers are required to sign their merge commits. Note that the name and e-mail address must match the information on the signing key exactly. To begin:
1. Generate a signing key, if you don't have one already, using your favorite PGP/GPG interface:
```
$ gpg --gen-key
gpg (GnuPG) 1.4.20; Copyright (C) 2015 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection? 4
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Fri 20 Dec 2019 01:38:11 PM CST
Is this correct? (y/N) y
You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.
Enter passphrase: [...]
```
2. Modify your `.git/config` file to enable signing commits and merges by default:
````
[user]
name = Your Name
email = your_email@example.com
signingkey = DEADBEEF # Must match name and email exactly!
[alias]
c = commit -S --edit
m = merge -S --no-ff --edit
````
Using `git c` and `git m` from now on will sign every commit with your `DEADBEEF` key. However, note that rebasing or cherry-picking commits will change the commit hash, and therefore, unsign the commit -- to resign the most recent, use `git c --amend`.
The term "Metasploit Committers" describes people who have direct write access to the [Rapid7 Metasploit-Framework fork](https://github.com/rapid7/metasploit-framework). These are the people who can land changes to this main fork of the Framework. However, it is not necessary to have committer rights in order to contribute to Metasploit. Much of our code comes from non-committers.
We encourage anyone to fork the Metasploit project, make changes, fix bugs, and notify the core committers about those changes via [Pull Requests](http://github.com/rapid7/metasploit-framework/pulls). The process for getting started is most comprehensively documented in the [Metasploit Development Environment](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment) setup guide.
Metasploit committers are a mix of [Rapid7](http://rapid7.com) employees and outside contributors. Anyone can become a contributor, with the following expectations:
1. Committers are empowered to participate in code review, help newbies, and be positive role models in the larger development community.
2. Committers are likely to take up chores such as writing documentation, evangelization, writing test cases, and code review.
3. Committers help maintain the character of the Metasploit Framework as a truly independent open source project.
The Metasploit community is built on the core belief that open contributions and open discussion of security issues has strong benefits for the Internet in general and human society as a whole. By helping each other demonstrate security vulnerabilities and exposures, we foster a community of excellent, ethical practitioners of information security.
# How to be a Committer
Committers tend to review pull requests that come in from other committers and from the wider Metasploit community. Committers generally should not land their own code without some sort of review from another contributor or committer.
For most changes, please open a pull request. In addition, always ask for someone to review your work. Even simple fixes might be better done otherwise. If you get no feedback on your pull requests, ask again. Be annoying if necessary! Don't submit a pull request or make a comment and let it rot because nobody responds.
Pull requests should be merged with a `git merge -S --no-ff` in order to ensure a merge commit is always generated, and your merge commit is signed with your PGP key. Avoid clicking the green "merge" button in Github in order to avoid race conditions with landing code that may sneak past review, and of course, so you can sign your commits.
If you reject a pull request, be clear in the pull request why it was rejected, with some effort made to point at helpful resources for next time. Most people don't often commit to open source code, so when someone does, please be respectful of their efforts.
Even if someone else approves of a pull request, and it is shown to be broken later, then it is still your responsibility to correct it. Make every effort to get a fix or revert in as soon as possible, whether you wrote the code, landed it, or approved it. Blame is shared equally.
A list of committer public keys [is here](https://github.com/rapid7/metasploit-framework/wiki/Committer-Keys).
# How to Gain Commit Rights
Commit rights are granted via votes on the committers mailing list. Voting records are archived for the benefit for current and future committers.
1. Any current committer may nominate any one person as a potential committer by writing to the committers mailing list.
2. The nominator must provide a justification for committer rights, and include the nominee's e-mail address.
2. After some discussion on the mailing list, there will be a group vote on the nominee.
2. The Metasploit manager (@busterb) will inform the new committer of their new commit rights and responsibilities, add the new committer to the appropriate ACL groups and mailing lists, and inform the mailing list of the successful completion of these tasks.
Committers introduced in this way will have commit rights to the [public framework repositories](https://github.com/orgs/rapid7/teams/framework-public-committers/repositories).
# How to Lose Commit Rights
Committer rights are not granted strictly on the basis of proven code quality; committer rights are a statement of trust by the existing body of committers, so there are highly subjective criteria in play as well. Elements like an agreeable personality, the ability to remain calm in the face of trolling, the avoidance of criminal proceedings, and other aspects of a committer's life all play a part in the initial granting of commit access.
Breaches of trust in terms of malicious or malformed code, or the demonstration of poor judgement that would reflect poorly on the Metasploit project will lead to a discussion on the committer mailing list, and which is likely result in the removal of committer rights.
# Useful Links for Committers
* [http://r-7.co/MSF-DEV](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment) is pretty much required reading.
* So is [CONTRIBUTING.md](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md)
* Check out the Apache Software Foundation's [Guide for Committers](https://www.apache.org/dev/committers). It's illuminating.
* [Producing Open Source Software](http://www.producingoss.com/gl/) by Ken Fogel is a must-read.
* Zach Holman's [Open Source Misfeasance](https://speakerdeck.com/holman/open-source-misfeasance) slides -- the video is gone!
* [How to Survive Poisonous People](https://www.youtube.com/watch?v=Q52kFL8zVoM) by Ben Collins-Sussman and Brian Fitzpatrick
* [The Netiquette RFC](http://www.faqs.org/rfcs/rfc1855.html) is about how to be polite.
Please see [CONTRIBUTING.md](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md) for an authoritative coding guide. This document has fallen out of date. We don't write bad code any more! Hooray!
This is a collection of all the bad code we often see in Metasploit modules. You should avoid them, too.
Note: Some of these examples use puts() for demo purposes, but you should always use print_status / print_error when writing a module.
### Bad Examples You Should NOT Follow:
1. Not checking the return value of a Metasploit API
2. Ruby 1.9.3 vs 1.8.7... gotcha!
3. Not checking the return value when using match()
4. Not checking nil before accessing a method
5. Using exception handling to shut an error up
6. Not taking advantage of the 'ensure' block
7. Adding the 'VERBOSE' option
8. Neglecting to use 'vars_post' for send_request_cgi() when crafting a POST request
9. Bad variable naming style
10. Using global variables
11. Modifying the datastore during execution
**1. Not checking the return value of a Metasploit API**
```ruby
res=send_request_cgi({
'method'=>'GET',
'uri'=>'/app/index.php'
})
# There's a bug here, because res can return nil (due to a timeout or other reasons)
# If that happens, you will hit a "undefined method `code' for nil:NilClass" error.
# The correct way should be: if res && res.code == 200
ifres.code==200
print_status("Response looks good")
else
print_error("Unexpected response")
end
```
**2. Ruby 1.9.3 vs 1.8.7... gotcha!**
```ruby
some_string="ABC"
# This can cause unexpected results to your module.
# Better to always do: char = some_string[1, 1]
char=some_string[1]
ifchar=='B'
puts"You will see this message in Ruby 1.9.3"
elsifchar==66
puts"You will see this message in Ruby 1.8.7"
end
```
```ruby
# 1.9 allows a comma after the last argument when calling
# a method while 1.8 does not. The most common place to
# see this error is in the update_info() section in a
# module's constructor.
some_method(
"arg1",
"arg2",# <-- This comma is a syntax error on 1.8.x
)
```
**3. Not checking the return value when using match()**
```ruby
str="dragon! drag on! Not lizard, I don't do that tongue thing"
# This tries to print "Not snake", but it's not in the string,
# so you'll get this error: "undefined method `[]' for nil:NilClass"
putsstr.match(/(Not snake)/)[0]
```
```ruby
# The above is better written as:
if(str=~/(Not snake)/)
puts$1
end
```
**4. Not checking nil first before accessing a method**
```ruby
str="These things are round and tasty, let's call them... tastycles!"
food=str.scan(/donut holes/)[0]
# food is nil, and nil has no method called "empty".
# This will throw an error: "undefined method `empty?' for nil:NilClass"
iffood.empty?orfood.nil?
puts"I don't know what it's called"
end
```
**5. Using exception handling to shut an error up**
```ruby
begin
# This block has 2 issues:
# Issue #1: sample() is not a method in 1.8.7
# Issue #2: Divided by 0 (race condition)
n=[0,1,2,3,4,5].sample
1/n
rescue
# If the user reports a bug saying this code isn't
# working, it can be hard to debug exactly what went
# wrong for the user without a backtrace.
# When you do this, the error also won't be logged in
# framework.log, either.
# Note that rescuing ::Exception is especially harmful
# because it can even hide syntax errors.
end
```
**6. Not taking advantage of the 'ensure' block**
```ruby
# You should use the ensure block to make sure x always has a value,
# which also avoids repeating code
begin
n=[0,1,2].sample
x=1/n
rescueZeroDivisionError=>e
puts"Are you smarter than a 5th grader? #{e.message}"
x=0# Can put this in the ensure block
rescueNoMethodError
puts"You must be using an older Ruby"
x=0# Can put this in the ensure block
end
puts"Value is #{x.to_s}"
```
**7. Adding the 'VERBOSE' option**
```ruby
register_options(
[
# You already have this. Just type 'show advanced' and you'll see it.
# So no need to register again
OptBool.new("VERBOSE",[false,'Enable detailed status messages',false])
],self.class)
```
**8. Neglecting to use send_request_cgi()'s vars_get or vars_get when crafting a POST/GET request**
```ruby
data_post='user=jsmith&pass=hello123'
# You should use the 'vars_post' key instead of 'data',
# unless you're trying to avoid the API escaping your
# parameter names
send_request_cgi({
'method'=>'POST',
'uri'=>'/',
'data'=>data_post
})
```
**9. Bad variable naming style**
```ruby
# What's this, Java?
# The proper naming style in this case should be: my_string
myString="hello, world"
```
**10. Using global variables**
```ruby
# $msg is a global variable that can be accessed anywhere within the program.
# This can induce bugs to other modules or mixins that are hard to debug.
# Use @instance variables instead.
# This is also mentioned in your HACKING file :-)
classOpinion
definitialize
# This variable shouldn't be shared with other classes
$msg="It's called the Freedom of Information Act. The Hippies finally got something right."
A lot of our discussion happens on IRC in #metasploit on Freenode.
Please be patient and hang around for a while -- not everyone is awake
at the same time as you. =)
# Mailing list
The Metasploit development mailing list used to be hosted on SourceForge, but is now on Google Groups. Metasploit Hackers is dead, long live [Metasploit Hackers][list]. (Or [mailto:Metasploit Hackers][mailto]).
The old list [is archived on seclists.org][archive].
# Abuse
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to msfdev@metasploit.com which goes to all the current committers. If the incident involves a committer, you may report directly to caitlin_condon@rapid7.com or todb@metasploit.com.
[archive]: http://seclists.org/metasploit/ "Metasploit mailing list archive"
[list]: https://groups.google.com/forum/#!forum/metasploit-hackers "Metasploit Hackers development mailing list"
Every so often, we'll get a request along the lines of, "Hey, I'm new to Metasploit, and I want to help!" The usual answer is something like, "Great! Here's our [framework bug tracker](https://github.com/rapid7/metasploit-framework/issues), get crackin!"
However, tackling core Metasploit Framework bugs or particularly squirrelly exploits probably isn't the right place for the new contributor. Believe me, everyone was a newbie once, there's no shame in that. Those bugs and vulns are usually complicated, and there are so many to choose from that it's hard to get started. Here are some ideas to get you started.
Metasploit is a tool by and for hackers, but the hackers that maintain it also happen to be software engineers. So, we have some hopefully easy-to-remember Do's and Don'ts in [CONTRIBUTING.md](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md). Read up on those.
# Server exploits
Server exploits are always in demand; why bother with complicated social engineering campaigns when you can go straight to the pain point of a vulnerable network. Here are some search queries to get you started:
* [Remote exploits](https://www.exploit-db.com/?type=remote) from Exploit-DB
# Client Exploits
Client exploits generally run as an "evil service" that a remote client will connect to. They nearly always require some kind of user interaction to trigger, such a viewing a web page, downloading a file, or otherwise connecting to the service controlled by the attacker.
* [Browser Vulns](https://www.google.com/#bav=on.2,or.r_cp.r_qf.&q=site:securityfocus.com+%22Firefox%22+OR+%22Internet+Explorer%22+OR+%22Chrome%22+OR+%22Safari%22+OR+%22Opera%22+-%22Retired%22&safe=off) from SecurityFocus via Google search terms
# Local and Privilege Escalation Exploits
Privilege escalation exploits tend to require the attacker already have an account on a target computer. They are nearly always going to be implemented as Metasploit exploit modules under one of the [local](https://github.com/rapid7/metasploit-framework/tree/master/modules/exploits/windows/local) trees (platform dependent), but sometimes they're better off as [post modules](https://github.com/rapid7/metasploit-framework/tree/master/modules/post). This is especially true for privilege escalation bugs.
* [Local Vulns](https://www.exploit-db.com/?type=local) from Exploit-DB
# Unstable modules
Want to pick up where someone else left off? Super! Just check the guide on rescuing [[Unstable Modules]] and push these poor, unloved modules over the finish line with decent testing and code cleanup.
# Framework bugs and features
If exploit dev isn't your thing, but more straightforward Ruby development is, then here are some good places to get started:
* [Recent Bugs](https://github.com/rapid7/metasploit-framework/issues?q=is%3Aissue+is%3Aopen+label%3Abug), which tend to be either very easy or very hard to fix (not a lot of middle ground).
* [Feature requests](https://github.com/rapid7/metasploit-framework/issues?q=is%3Aissue+is%3Aopen+label%3Afeature), which is often in the same boat.
Along these same lines is a perennial need for better automated testing, down in the [spec directory](https://github.com/rapid7/metasploit-framework/tree/master/spec). If you have a talent for exploring strange and wonderful code bases, pick out a chunk of the Metasploit core code and define out what you expect for working behavior.
# Non-code
We can always use better documentation. Those guys over at Offensive Security do a great job with [Metasploit Unleashed](http://www.offensive-security.com/metasploit-unleashed/Main_Page), but as with all complex bodies of work, there are surely bugs to be found. If you have ideas on how to make the documentation on Metasploit clear and more accessible to more people, go nuts.
Write wiki articles in your fork (hint, [Gollum](https://github.com/gollum/gollum) is excellent for this) and let someone know about them, we'll be happy to reflect them here and maintain your credit. If you're interested in working with us on documentation long-term, that's even better; reach out on [Slack](https://metasploit.com/slack) for info on how best to make changes.
Ditto with YouTube screencasts of particular common tasks. Narration while you do it is great. People seem to love YouTube videos of this stuff -- there are over [40,000](http://www.youtube.com/results?search_query=metasploit&oq=metasploit) of the things out there, and we'd love for someone to step up and curate a top 10 or top 100 of those that we can promote here for new and experienced users.
For developer types: we are slowly but surely converting all of Metasploit to use standardized commenting using [YARD](https://yardoc.org), so we could always use more accurate and more comprehensive YARD documentation for pretty much anything found in `lib`. We will happily take pull requests that contain nothing but comment docs!
Again, there's always room on #metasploit on Freenode. Be helpful with the questions there, and people are more likely to help you in the future. Same goes for the [Metasploit Slack team](https://metasploit.com/slack), where all sorts of new and proficient users and devs are looking for help and camaraderie.
# The Usual Warnings
You probably shouldn't run proof of concept exploit code you find on the Internet on a machine you care about in a network you care about. That is generally considered a Bad Idea. You also probably shouldn't use your usual computer as a target for exploit development, since you are intentionally inducing unstable behavior.
Our preferred method of module submission is via a git pull request from a feature branch on your own fork of Metasploit. You can learn how to create one here:
[[Landing-Pull-Requests]]
Also, please take a peek at our guides on using git and our acceptance guidelines for new modules in case you're not familiar with them.
If you get stuck, try to explain your specific problem as best you can on our [Freenode IRC](https://freenode.net/) channel, #metasploit (joining requires a [registered nick](https://freenode.net/kb/answer/registration)). Someone should be able to lend a hand. Apparently, some of those people never sleep.
# Thank you
In case nobody's said it yet: Thanks for your interest and support! Exploit developers from the open source community are the soul of Metasploit, and by contributing your time and talent, you are helping advance the state of the art for intelligent IT defense. We simply couldn't do all of this without you.
So, you want to make a Login Scanner Module in Metasploit, eh? There are a few things you will need to know before you begin. This article will try to illustrate all the moving pieces involved in creating an effective bruteforce/login scanner module.
- [Credential objects](#credential-objects)
- [Result objects](#result-objects)
- [CredentialCollection](#credentialcollection)
- [LoginScanner Base](#loginscanner-base)
* [Attributes](#attributes)
* [Methods](#methods)
* [Constants](#constants)
- [Pulling it all Together in a module](#pulling-it-all-together-in-a-module)
* [The Cred Collection](#the-cred-collection)
* [Initialising the Scanner](#initialising-the-scanner)
* [The scan block](#the-scan-block)
* [ftp_login final view](#ftp_login-final-view)
# Credential Objects
`Metasploit::Framework::Credential
(lib/metasploit/framework/credential.rb)`
These objects represent the most basic concept of how we now think about Credentials.
- **Public**: The public part of a credential refers to the part that can be publicly known. In almost all cases this is the username.
- **Private**: The private part of the credential, this is the part that should be a secret. This currently represents: Password, SSH Key, NTLM Hash etc.
- **Private Type**: This defines what type of private credential is defined above
- **Realm**: This represents an authentication realm that the credential is valid for. This is a tertiary part of the authentication process. Examples include: Active Directory Domain, Postgres Database etc.
- **Realm Key**: This defines what type of Realm the Realm Attribute represents.
- **Paired**: This attribute is a boolean value that sets whether the Credential must have both a public and private to be valid.
All LoginScanners use Credential objects as the basis for their attempts.
These are the objects yielded by the `scan!` method on each `LoginScanner`. They contain:
- **Access Level**: An optional Access Level which can describe the level of access granted by the login attempt.
- **Credential** : The Credential object that achieved that result
- **Proof**: An optional proof string to show why we think the result is valid
- **Status**: The status of the login attempt. These values come from Metasploit::model::Login::Status , examples include "Incorrect", "Unable to Connect", "Untried" etc
This class is created by the `build_credential_collection` method provided by the `Msf::Auxiliary::AuthBrute` mixin. It takes a bunch of options that when specified, will take priority over the corresponding datastore options. Typical uses only need to specify the `username:` and `password:` options since those can be different from one module to another (e.g. 'USERNAME', 'SMBUser', 'HttpUsername', etc.). It can be passed in as the `cred_details` on the `LoginScanner`, and responds to #each and yields crafted Credentials.
The `build_credential_collection` method will handle prepending usernames and passwords as well as skipping entries as configured by the `DB_SKIP_EXISTING` option.
Where `has_realm_key` and `has_default_realm` should be set according to whether your `LoginScanner` has those things. (More on this later)
LoginScanners always take a collection of Credentials to try and one host and port. So each `LoginScanner` object attempts to login to only one specific service.
## Attributes
- **`connection_timeout`**: The time to wait for a connection to timeout
- **`cred_details`**: An object that yields credentials on each (like credentialCollection or an Array)
- **`host`**: The address for the target host
- **`port`**: The port number for the target service
- **`proxies`**: Any proxies to use in the connection (some scanners might not support this)
- **`stop_on_success`**: Whether to stop trying after a successful login is found
## Methods
### each_credential
You will not have to worry much about this method, Be aware that it is there. It iterates through whatever is in `cred_details`, does some normalization and tries to make sure each Credential is properly setup for use by the given `LoginScanner`. It yields each Credential in a block.
```ruby
def each_credential
cred_details.each do |raw_cred|
# This could be a Credential object, or a Credential Core, or an Attempt object
# so make sure that whatever it is, we end up with a Credential.
credential = raw_cred.to_credential
if credential.realm.present? && self.class::REALM_KEY.present?
This method will be overridden by each specific `LoginScanner`. This is called at the end of the initializer and sets any sane defaults for attributes that have them and were not given a specific value in the initializer.
```ruby
# This is a placeholder method. Each LoginScanner class
# will override this with any sane defaults specific to
# its own behaviour.
# @abstract
# @return [void]
def set_sane_defaults
self.connection_timeout = 30 if self.connection_timeout.nil?
end
```
### attempt_login
This method is just a stub on the Base mixin. It will be overridden in each LoginScanner class to contain the logic to take one single Credential object and use it to make a login attempt against the target service. It returns a `::Metasploit::Framework::LoginScanner::Result` object containing all the information about that attempt's result.
For an example let's look at the attempt_login method from `Metasploit::Framework::LoginScanner::FTP (lib/metasploit/framework/login_scanner/ftp.rb)`
This method is the main one you will be concerned with. This method does several things:
- It calls valid! which will check all of the validations on the class and raise an `Metasploit::Framework::LoginScanner::Invalid` if any of the Validations fail. This exception will contain all the errors messages for any failing validations.
- it keeps track of the connection error count, and will bail out if we have too many connection errors or too many in a row
- it runs through all of the credentials by calling each_credential with a block
- in that block it passes each credential to `#attempt_login`
- it yields the Result object into the block it is passed
- if stop_on_success is set it will also exit out early if it the result was a success
```ruby
# Attempt to login with every {Credential credential} in
# {#cred_details}, by calling {#attempt_login} once for each.
#
# If a successful login is found for a user, no more attempts
# will be made for that user.
#
# @yieldparam result [Result] The {Result} object for each attempt
# @yieldreturn [void]
# @return [void]
def scan!
valid!
# Keep track of connection errors.
# If we encounter too many, we will stop.
consecutive_error_count = 0
total_error_count = 0
successful_users = Set.new
each_credential do |credential|
next if successful_users.include?(credential.public)
result = attempt_login(credential)
result.freeze
yield result if block_given?
if result.success?
consecutive_error_count = 0
break if stop_on_success
successful_users << credential.public
else
if result.status == Metasploit::Model::Login::Status::UNABLE_TO_CONNECT
consecutive_error_count += 1
total_error_count += 1
break if consecutive_error_count >= 3
break if total_error_count >= 10
end
end
end
nil
end
```
## Constants
Although not defined on Base, each `LoginScanner` has a series of Constants that can be defined on it to assist with critical behaviour.
- **`DEFAULT_PORT`**: `DEFAULT_PORT` is a simple constant for use with `set_sane_defaults`. If the port isn't set by the user it will use `DEFAULT_PORT`. This is put in a constant so it can be quickly referenced from outside the scanner.
These next two Constants are used by the LoginScanner namespace method classes_for_services. This method invoked by `Metasploit::Framework::LoginScanner.classes_for_service(<Mdm::service>)` will actually return an array of LoginScanner classes that may be useful to try against that particular Service.
- **`LIKELY_PORTS`** : This constant holds n array of port numbers that it would be likely useful to use this scanner against.
- **`LIKELY_SERVICE_NAMES`** : Like above except with strings for service names instead of port numbers.
- **`PRIVATE_TYPES`** : This contains an array of symbols representing the different Private credential types it supports. It should always match the demodulize result for the Private class i.e :password, `:ntlm_hash`, `:ssh_key`
These constants are fore `LoginScanners` that have to deal with Realms such as AD domains or Database Names.
- **`REALM_KEY`**: The type of Realm this scanner expects to deal with. Should always be a constants from `Metasploit::Model::Login::Status`
- **`DEFAULT_REALM`**: Some scanners have a default realm (like WORKSTATION for AD domain stuff). If a credential is given to a scanner that requires a realm, but the credential has no realm, this value will be added to the credential as the realm.
- **`CAN_GET_SESSION`**: this should be either true or false as to whether we expect we could somehow get a session with a Credential found from this scanner.
So now you hopefully have a good idea of all the moving pieces involved in creating a LoginScanner. The next step is using your brand new LoginScanner in an actual module.
Let's look at the `ftp_login` module:
`def run_host(ip)`
Every Bruteforce/Login module should be a scanner and should use the run_host method which will run once for each RHOST.
So here we see the CredentialCollection getting created using the datastore options. We pass in the options for Cred creation such as wordlists, raw usernames and passwords, whether to try the username as a password, and whether to try blank passwords.
you'll also notice an option here called `prepended_creds`. FTP is one of the only module to make use of this, but it is generally available through the CredentialCollection. This option is an array of `Metasploit::Framework::Credential` objects that should be spit back by the collection before any others. FTP uses this to deal with testing for anon FTP access.
Here we actually create our Scanner object. We set the IP and Port based on data the module already knows about. We can pull any user supplied proxy data from the datatstore. we also pull from the datastore whether to stop on a success for this service. The cred details object is populated by our Credentialcollection which will handle all the credential generation for us invisibly.
This gives us our scanner object, all configured and ready to go.
This is the real heart of the matter here. We call s`can!` on our scanner, and pass it a block. As we mentioned before, the scanner yields each attempt's Result object into that block. We check the result's status to see if it was successful or not.
The result object now as a `.to_h` method which returns a hash compatible with our credential creation methods. We take that hash and merge in our module specific information and workspace id.
In the case of a success we build some info hashes and call `create_credential`. This is a method found in the metasploit-credential gem under `lib/metasploit/credential/creation.rb` in a mixin called `Metasploit::Credential::Creation`. This mixin is included in the Report mixin, so if your module includes that mixin you'll get these methods for free.
`create_credential` creates a `Metasploit::Credential::Core`. We then take that core, the service data, and merge it with some additional data. This additional data includes the access level, the current time (to update last_attempted_at on the `Metasploit::Credential::Login`), the the status.
Finally, for a success, we output the result to the console.
In the case of a failure, we call the `invalidate_login` method. This method also comes from the Creation mixin. This method looks to see if a Login object already exists for this credential:service pair. If it does, it updates the status to the status we got back from the scanner. This is primarily to account for Login objects created by things like Post modules that have an untried status.
## `ftp_login` Final View
Pulling it all together, we get a new `ftp_login` module that looks something like this:
```ruby
##
# This module requires Metasploit: http//metasploit.com/download
# Current source: https://github.com/rapid7/metasploit-framework
* [Stagers, stages, and handlers](#stagers-stages-and-handlers)
* [LHOST and LPORT](#lhost-and-lport)
* [LHOST](#lhost)
* [LPORT](#lport)
* [Check dead shells](#check-dead-shells)
* [Quick things to check](#quick-things-to-check)
* [Not so quick things to check](#not-so-quick-things-to-check)
Dead shells. Nobody likes them. Yet, despite the advances made in the Metasploit stagers and Meterperter itself, we still see them regularly.
There are many reasons why shells refuse to connect or die after they're established. The goal of this post is to help people understand why. Hopefully, by the end, the most common causes will be understood, and users can fix things themselves.
## Background knowledge
Prior to diving into the possible breakages and their causes, it's important to have some background knowledge of stagers, and how Meterpreter works. Please be sure to read the following articles prior to reading the rest of this post:
* [[Meterpreter Stageless Mode]] - Covers the exploitation process, and how Meterpreter sessions are established. This is important because understanding how the different components interact and what allows for easier debugging later.
* [[Meterpreter Configuration]] - Covers how configuration works in Meterpreter. This is important because it highlights the separation of configuration in stagers and Meterpreter. This alone is the key to many breakages, especially in HTTP/S payloads.
* [[The ins and outs of HTTP and HTTPS communications in Meterpreter and Metasploit Stagers]] - Covers the detail of HTTP/S based communications in the stagers and in Meterpreter itself.
## Stagers, stages, and handlers
Each exploit and handler is made up of multiple things, and they're all independent:
* **Stager**: This is the small bit of code that is first executed by the target. It contains it's own bundled implementation of a communications channel. It has the goal of establishing communication with Metasploit, downloading the **stage**, and invoking it. It has it's own configuration.
* **Stage**: This is the second payload that is executed by the target. It is sent to the target via the communications channel that was opened by the **stage**. Once downloaded, it is invoked, and from there, it takes over. It has its own configuration.
* **Handler**: This is the code that runs on the attacker's machine. It is responsible for handling the attacker-side of the communications channel that is established by the **stager**. It is responsible for uploading the **stage**. It is responsible for handling communication between the attacker and the target once the stage has taken over from the stager.
In some cases, there might be multiple stages (as is the case with POSIX Meterpreter). This is called an **intermediate** stage. Usually, these stages are slightly bigger than the stager and can do more work to help establish communications.
The most important thing to remember is that both the **stager** and the **stage** have their own configurations that are **independent**. THE MOST COMMON cause of dead shells is the result of the **stage** not having the correct configuration; in other words, it's different to that specified in the **stager**.
## LHOST and LPORT
Any user of Metasploit will tell you that they know what `LHOST` and `LPORT` mean, yet it's incredibly common to find out that their understanding isn't 100% correct. To prevent dead sessions that are related to a misconfiguration of these values, we need to make sure we understand what they mean.
## LHOST
`LHOST` is short for Local Host. This value represents the IP address or hostname that **stagers** and **stages** should attempt to connect to. It is where the **handler** can be reached. This doesn't mean that this is where the handler actually exists.
`LHOST` is a value that is meaning from the perspective of the target machine. This value is passed along as part of the configuration for **stagers** and **stages** and tells the target machine where to go to reach the handler, and so this has to map to a value that is reachable by the target.
A **handler** obviously needs to listen on a host/IP for the incoming connection. In cases where the `LHOST` value, for example the address that the target is able to reach, is the same as that which the host can listen on, no extra work has to be done. The `LHOST` value is used by the handler.
However, if some kind of NAT or port forward is enabled, or if the handler is behind a firewall, then setting `LHOST` isn't enough. In order to listen on the appropriate interface, another setting must be used called `ReverseListenerBindHost`. This value tells the **handler** to listen on a different interface/IP, but it doesn't change the fact that the `LHOST` value is given to the target when the **stage** is uploaded.
In short, `LHOST` must always remain the IP/host that is routable from the target, and if this value is not the same as what the listener needs to bind to, then change the `ReverseListenerBindHost` value. If you're attacking something across the Internet and you specify an internal IP in `LHOST`, you're doing it wrong.
## LPORT
The principles of `LHOST` and `ReverseListenerBindHost` can be applied to `LPORT` and `ReverseListenerBindPort` as well. If you have port forwarding in place, and your listener needs to bind to a different port, then you need to make use of the `ReverseListenerBindPort` setting.
The classic example of this case is where an attacker wants to make use of port `443`, but rightfully doesn't want to run Metasploit as `root` just so they can directly bind to ports lower than `1024`. Instead, the set up a port forward (on their router, or using `iptables`) so that `443` forwards to `8443`, with a goal of accepting connections on that port instead.
To accommodate this scenario, the `LHOST` value must **still contain `443`**, as this is the port that the target machine needs to establish communications on; `443` is the value that needs to go out with the **stager** and the **stage** configurations. Metasploit needs to bind locally to port `8443`, and so the **handler** is configured so that `ReverseListenerBindPort` has this value instead.
When the handler launches, it binds to `8443` and handles any connections it receives. When a stage is generated, it uses `443` from `LHOST` value to populate the configuration.
If the attacker makes the mistake of either setting `LPORT` to `8443`, or leaving `LPORT` as `443` and not using `ReverseListenerBindPort`, then the result is either a dead shell after the first stage, or no connect back at all.
## Check dead shells
There are a few things to check for when debugging a dead shell.
### Quick things to check
* Make sure that `LHOST` is set to a routable address from the target, and not a local listen address.
* Make sure that `LPORT` is set to the port number that the target needs to connect to.
* Make sure that `ReverseListenerBindPort` is set if port forwarding is enabled and the traffic is being routed to a different port.
* Make sure that your listener's configuration matches that of the target from an architecture perspective. If you mix x64 listeners with x86 payloads (and vice versa), things will go bad.
### Not so quick things to check
* If the target is running AntiVirus there's a chance that the **stage** , for example `metsrv`, is being caught while being uploaded. `reverse_tcp` and `reverse_http`**stagers** download `metsrv`_without_ any encryption, and so the content of the DLL is visible to anything watching on the wire. `reverse_https` can still get caught in cases where AV is doing MITM content inspection. In this case, consider encoding your payloads, or if possible using stageless Meterpreter instead.
New Metasploit modules are now required to contain a `Notes` section containing additional information such as the `Stability`, `Reliability` and `SideEffects` associated with running the module.
Example:
```ruby
definitialize(info={})
super(
update_info(
info,
'Name'=>'Module name',
'Description'=>%q{
Module description
},
'Author'=>
[
'Author name'
],
'License'=>MSF_LICENSE,
'References'=>
[
['CVE','2020-XXXX']
],
'DisclosureDate'=>'2020-03-26',
'Platform'=>'ruby',
'Arch'=>ARCH_RUBY,
'Privileged'=>false,
'Targets'=>[['Automatic',{}]],
'DefaultTarget'=>0,
# All new modules must contain the below information. See below for more details for allowed values
'Notes'=>{
'Stability'=>[...],
'Reliability'=>[...],
'SideEffects'=>[...]
}
)
)
end
```
## Allowed Values
### Stability
| Constant | Description |
| -------------- | ------------- |
| CRASH_SAFE | Module should not crash the service or OS |
| CRASH_SERVICE_RESTARTS | Module may crash the service, but it will restart |
| CRASH_SERVICE_DOWN | Module may crash the service, and remain down |
| CRASH_OS_RESTARTS | Module may crash the OS, but it will restart |
| CRASH_OS_DOWN | Module may crash the OS, and remain down |
| SERVICE_RESOURCE_LOSS | Module causes a resource to be unavailable for the service |
| OS_RESOURCE_LOSS | Module causes a resource to be unavailable for the OS |
### Side Effects
| Constant | Description |
| -------------- | ------------- |
| ARTIFACTS_ON_DISK | Module leaves a payload, a dropper, etc, on the target machine |
| CONFIG_CHANGES | Module modifies some config file |
| IOC_IN_LOGS | Module leaves an indicator of compromise in the log(s) |
| ACCOUNT_LOCKOUTS | Module may cause an account to lock out |
| SCREEN_EFFECTS | Module shows something on the screen that a human may notice |
| PHYSICAL_EFFECTS | Module may produce physical effects in hardware (Examples: light, sound, or heat) |
| AUDIO_EFFECTS | Module may cause a noise (Examples: Audio output from the speakers or hardware beeps) |
### Reliability
| Constant | Description |
| -------------- | ------------- |
| FIRST_ATTEMPT_FAIL | The module may fail for the first attempt |
| REPEATABLE_SESSION | The module is expected to get a session every time it runs |
| UNRELIABLE_SESSION | The module isn't expected to get a shell reliably (such as only once) |
These include Metasploit Framework only. Updates are built about once a day.
See [[Nightly-Installers]] for installation instructions for Windows, OS X and Linux.
## Metasploit Pro Installers
These include the Pro UI as well as Framework.
Updates are released about once every other week for Windows and Linux.
The pgp signatures below can be verified with the following [public key](https://pgp.mit.edu/pks/lookup?op=get&search=0xCDFB5FA52007B954)
|Download Link|File Type|SHA1|PGP|
|-|-|-|-|
| [metasploit-4.21.1-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/metasploit-latest-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/metasploit-latest-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/metasploit-latest-windows-x64-installer.exe.asc)|
| [metasploit-4.21.1-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/metasploit-latest-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/metasploit-latest-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/metasploit-latest-linux-x64-installer.run.asc)|
| [metasploit-4.21.0-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-windows-x64-installer.exe.asc)|
| [metasploit-4.21.0-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.21.0-2022052401-linux-x64-installer.run.asc)|
| [metasploit-4.20.0-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-windows-x64-installer.exe.asc)|
| [metasploit-4.20.0-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.20.0-2021112001-linux-x64-installer.run.asc)|
| [metasploit-4.19.1-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-windows-x64-installer.exe.asc)|
| [metasploit-4.19.1-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.1-2021073101-linux-x64-installer.run.asc)|
| [metasploit-4.19.0-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-windows-x64-installer.exe.asc)|
| [metasploit-4.19.0-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.19.0-2021031701-linux-x64-installer.run.asc)|
| [metasploit-4.18.0-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-windows-x64-installer.exe.asc)|
| [metasploit-4.18.0-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.18.0-2020101201-linux-x64-installer.run.asc)|
| [metasploit-4.17.1-windows-x64-installer.exe](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-windows-x64-installer.exe) | Windows 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-windows-x64-installer.exe.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-windows-x64-installer.exe.asc)|
| [metasploit-4.17.1-linux-x64-installer.run](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-linux-x64-installer.run) | Linux 64-bit | [SHA1](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-linux-x64-installer.run.sha1) | [PGP](https://downloads.metasploit.com/data/releases/archive/metasploit-4.17.1-2020080301-linux-x64-installer.run.asc)|
## Metasploit Framework Source
Please see the [Metasploit framework releases page](https://github.com/rapid7/metasploit-framework/releases) for the release versions of Metasploit Framework.
* [Why encoding does not matter, and how Metasploit generates exes](https://www.scriptjunkie.us/2011/04/)
* [Facts and myths about antivirus evasion with Metasploit](http://schierlm.users.sourceforge.net/avevasion.html)
* [Using metasm to avoid antivirus detection ghost writing asm](https://web.archive.org/web/20200330111926/https://www.pentestgeek.com/penetration-testing/using-metasm-to-avoid-antivirus-detection-ghost-writing-asm)
There are approximately 14 million other resources out there on the why's and wherefores of evading antivirus, but the about articles should get you started.
Every exploit module has been assigned a rank based on its potential impact to the target system. Users can search, categorize, and prioritize exploits based on rankings.
The ranking is implemented by adding a `Rank` constant at the top of the class declaration in a module:
```ruby
classMetasploitModule<Msf::Exploit
Rank=LowRanking
definitialize(info={})
...
end
...
end
```
The ranking values are one of the following, in descending order of reliability:
| Ranking | Description |
| ------- | ----------- |
| **ExcellentRanking** | The exploit will never crash the service. This is the case for SQL Injection, CMD execution, RFI, LFI, etc. No typical memory corruption exploits should be given this ranking unless there are extraordinary circumstances ([WMF Escape()](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/windows/browser/ms06_001_wmf_setabortproc.rb)). |
| **GreatRanking** | The exploit has a default target AND either auto-detects the appropriate target or uses an application-specific return address AFTER a version check. |
| **GoodRanking** | The exploit has a default target and it is the "common case" for this type of software (English, Windows 7 for a desktop app, 2012 for server, etc). Exploit does not auto-detect the target. |
| **NormalRanking** | The exploit is otherwise reliable, but depends on a specific version that is not the "common case" for this type of software and can't (or doesn't) reliably autodetect. |
| **AverageRanking** | The exploit is generally unreliable or difficult to exploit, but has a success rate of 50% or more for common platforms. |
| **LowRanking** | The exploit is nearly impossible to exploit (under 50% success rate) for common platforms. |
| **ManualRanking** | The exploit is unstable or difficult to exploit and is basically a DoS (15% success rate or lower). This ranking is also used when the module has no use unless specifically configured by the user (e.g.: [exploit/unix/webapp/php_eval](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/unix/webapp/php_eval.rb)). |
The ranking value is available the module Class object as well as instances:
### This is how the application was submitted on 2017-02-08. Please make no more edits
--
Please don't use markdown here, we have to paste it into a form. All answers are limited to 1000 chars.
--
**Why does your org want to participate in Google Summer of Code?**
The story of Metasploit Framework's creation and development over the last 13 years is one of community collaboration to create and hone tools useful to a wide range of security practitioners. Its broad functionality, combined with the deep domain knowledge of the mentors, offers a unique opportunity for students to learn about security and exploit development. Many of our contributors are established exploit developers and penetration testers who have years of industry experience that they can share with students. We hope that the experience will inspire students to continue contributing to open source security, as well as providing them with invaluable real-world training in development, security, and remote collaboration.
**How will you keep mentors engaged with their students?**
All of our mentors are long-time development team members who have a history of helping new users and contributors. Many of our mentors specialize in certain parts of the framework, so depending on the student's interests, we will match them with the most complementary mentor. Our project administrators will regularly check in with mentors and students to ensure that the relationship is productive and progressing as expected.
**How will you help your students stay on schedule to complete their projects?**
First, we will ask students to use GitHub's Projects to track progress in real time as they are working. Mentors will help students divide projects into manageable chunks with measurable milestones. This will help students learn how to manage and break up tasks on large scale projects. Additionally, students and mentors will need to collaborate on a weekly status report that describes their progress and send it to the mailing list.
**How will you get your students involved in your community during GSoC?**
Students will use the same channels that all our contributors use: IRC and GitHub. Students will follow the same procedures of code review that all our contributors follow. By providing them with the same communication channels that our community uses, we hope to encourage the students to interact and collaborate with other contributors and users and to explore additional resources beyond their mentor. Hopefully, this process will give them a network of support and illustrate the advantages of working with other minds.
**How will you keep students involved with your community after GSoC?**
Based on the success of the project, we will encourage students to apply for committer rights at the conclusion of GSoC, include them in Metasploit roadmap discussions, and invite them to special community events. After the conclusion of GSoC we will encourage students to write about their experience on Metasploit's community blog, which will give their work greater exposure to the overall security community.
GSoC Project Ideas in no particular order. When you've picked one, take a look at [[GSoC 2017 Student Proposal]] for how to make a proposal.
### Submit your own
If you want to suggest your own idea, please discuss it with us first on [our mailing list](https://groups.google.com/forum/#!forum/metasploit-hackers) to make sure it is a reasonable amount of work for a summer and that it fits the goals of the project.
--
# Console side
### Convert between `CMD_UNIX` and the interpreted language architectures
Perl, Python, and Ruby scripts can all be run via a short command line invocation. It would be nice to be able to use these payloads in `ARCH_CMD` contexts as well as their own separate architectures (`ARCH_PYTHON`, `ARCH_RUBY`). This would allow modules that exploit command injection vulnerabilities to use python meterpreter in particular.
Set up automated testing using something like Vagrant to spin up and configure vulnerable machines, run exploits against them.
### A categorical focus
Something like "make all X exploits badass", or add a full suite of modules around particular gear or vendor stack.
**Requirements**: Ruby
**Mentor**: [@hdm](https://github.com/hdm)
### Allow post modules to take a payload
As it stands, the framework defines anything that takes a payload to be an exploit. Because post-exploitation modules cannot take a payload, things that want to drop an executable for persistence are implemented as local exploits (in the `exploit/*/local` namespace instead of `post/*/persistence`). This project would give those kinds of modules a more consistent interface.
Once this is done, we can move the `exploit/*/local` modules that aren't actually exploits back to `post/`
**Difficulty**: 3/5
**Requirements**: Ruby
**Mentor**: [@egypt](https://github.com/egypt)
### SMB2 support
(see also [ruby_smb project](https://github.com/rapid7/ruby_smb))
**Difficulty**: 5/5
**Mentor**: [@egypt](https://github.com/egypt)
### Filesystem sessions
The idea here is to create a new session type for authenticated protocols that give you filesystem access. The simplest is FTP, so that's where we should start. We'll need several pieces for this to work:
1. A new session interface in `Msf::Sessions` (`lib/msf/base/sessions/`). This should be abstract enough that we can implement protocols other than FTP in the future.
1. A mapping of protocol details to that interface.
1. A new command dispatcher implementing at least these commands: `upload`, `download`, `ls`, `cd`
1. We'll need to modify `auxiliary/scanner/ftp/ftp_login` to create one of these awesome new sessions when authentication is successful.
**Difficulty**: 2/5
**Requirements**: Ruby
### SMB-based file transport for Meterpreter
The idea here is to create a transport that allows Meterpreter and Console to talk via File handles opened via UNC path. In cases where 445 is allowed outbound, Meterpreter can open file handles to a UNC path that MSF is listening on, and they can communicate on those file handles. For this to work we need:
1. A new transport that knows how to operate over SMB file handles
* In particular, one file handle is used for writing, and one for reading.
1. New stagers that use the Win32 API to open file handles to a given UNC path.
* Most of this is already done in a PR for named pipe transport support, and so a few changes to those stagers should result in it working fine for this.
1. To come up with a method/protocol that both Console and Meterpreter can use to identify when new sessions come in.
Given that SMB file reading and writing is already a thing, this shouldn't be too hard on the MSF side.
Currently, the attributes that one can set for how a Meterpreter payload appears at the HTTP level are limited. We would like the ability to set and add arbitrary HTTP headers to requests and responses, so that the traffic appears more realistic.
Using either Python or Powershell (or maybe both if it can be abstract enough). This could allow things like running Responder.py or Empire on a compromised host.
**Difficulty**: 4/5
**Requirements**: C, Python/Powershell
**Mentor**: [@OJ](https://github.com/oj)
### Use SChannel in native Windows Meterpreter instead of embedded OpenSSL
[SChannel](https://msdn.microsoft.com/en-us/library/windows/desktop/ms678421(v=vs.85).aspx) is Windows' built-in TLS library.
**Difficulty**: 3/5
**Requirements**: C, Windows systems programming
**Mentor**: [@OJ](https://github.com/oj)
### SMB-based file transport for Meterpreter
This is the Meterpreter side of the SMB transport mentioned in the Console section. For this to work we need:
1. A new Meterpreter transport that uses file handles to read and write data over SMB to talk to MSF.
* Use the named pipe transport PR to see how this might work.
1. Full support of the "protocol" that has been designed so that MSF knows when sessions come in.
**Difficulty**: 2/5
**Requirements**: C, Windows systems programming
**Mentor**: [@OJ](https://github.com/oj)
--
# Metasploitable3
[Metasploitable3](https://github.com/rapid7/metasploitable3) is an
intentionally vulnerable virtual machine. It was created to be a
learning tool for new users as well as a place to test Metasploit and
its payloads.
### Linux: add vulnerabilities
**Requirements**: Vagrant
### Windows: add vulnerabilities
**Requirements**: Vagrant
--
# Miscellaneous
### Replace `msftidy` with a real linter
[Our current module style checker](https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/msftidy.rb) is a mass of regular expressions attempting to look for bad patterns. It could be much improved by using a real lexer. We could use rubocop as a base for this.
This could also dovetail into an ongoing documentation project.
**Difficulty**: 2/5
**Requirements**: Ruby
# Potential Mentors
All of the following folks have expressed willingness to be mentors.
A brief description of what you would like to work on. See [[GSoC-2017-Project-Ideas]] for ideas.
## Vitals
* Your name
* Contact info - include at least:
- an email address
- github user name
- Freenode nick
## Skillz
What programming languages are you familiar with, in order of proficiency? Most of Metasploit is written in Ruby; for any project you will most likely need at least a passing knowledge of it. If you want to work on Meterpreter or Mettle, C will be necessary as well.
What other projects have you worked on before?
## Your project
Fill in the details. What exactly do you want to accomplish?
### Improving the Post-exploit / Meterpreter functionality
Examples could include:
* Sending keystrokes and mouse movement to a Meterpreter session
* HTML based VNC style session control
e.g https://github.com/rapid7/metasploit-framework/pull/9196 but accepting user input from the browser
* Playing (streaming?) sounds to a Meterpreter session
* Implementing the streaming record mechanism from more Meterpreter sessions
* Text-to-speech and volume control
* Fun behaviors
- Ejecting the CD-ROM drive
- Flipping the screen upside down
- Changing screen colors
- Turning the monitor on/off
- Ordering donuts
* MessageBox or live chat functionality
(e.g "This machine is vulnerable to MS17-010, you must run Windows Update!")
* Overlaying an image or even HTML on the user interface
Difficulty: Varies
### Improving post-exploit API to be more consistent, work smoothly across session types
The Metasploit post-exploitation API is intended to provide a unified interface between different Meterpreter, shell, powershell, mainframe, and other session types. However, there are areas where the implementation is not consistent, and could use improvements:
* Shell sessions do not implement the filesystem API that Meterpreter sessions have
* When a shell session is in a different language, e.g. Windows in French, the post API does not find the expected output. Add localization support for these.
* Simple commands like 'cmd_exec' are fast in Shell sessions but are relatively slow in Meterpreter sessions. Add an API to make Meterpreter run simple commands more easily.
Difficulty: Varies
## Add meta-shell commands
Shell sessions typically expose a direct connection to a remote shell, but are lacking a number of nice features such as the ability to stop a remote command, background a command (this could be advanced or depend on the underlying session), or to even lock the session. This project would implement some pre-processing hooks to shell sessions so that job control could be added by default (allowing backgrounding of commands), meta-commands like 'background' and 'sessions' could be added as well.
Difficulty: 3/5
### Improve the web vulnerability API
This would follow up on the Arachni plugin PR <https://github.com/rapid7/metasploit-framework/pull/8618> and improve the Metasploit data model to better represent modern web vulnerabilities. This project would require knowledge of data models, types of modern web vulnerabilities, and experience with web app security scanners.
Difficulty: 4/5
### Session-style module interaction
Metasploit has the concept of 'sessions' where a connection context can define its own set of console operations. E.g. if you interact with a session, Metasploit switches to a specific subconsole for interaction. It would be nice as an alternative to 'action' for auxiliary modules, or as a way to merge related modules, to simply interact with the module.
Difficulty: 3/5
### Integration plugin with a 3rd-party post-exploit framework
Connect a 3rd-party post-exploitation framework with Metasploit, such as Empire, Pupy, or Koadic, so that Metasploit can view and interact with sessions outside of its own types. Being able to use outside stagers in exploits, or adding the ability to 'upgrade' a session to an outside session type are other possibilities.
Difficulty 3/5
## Enhance Metasploitable3
### Create a Simulated Active Directory Domain
Expand functionality of the existing Windows 2008 VM to act as a domain controller. The setup should include a number of users of varying roles, multiple group policy objects and settings, and logon scripts or application deployments. Considerations should be taken on how and where to include purposeful vulnerabilities within these settings.
Difficulty 2/5
### Configure a Mock Corporate Network
Currently metasploitable3 consists of two separate virtual machines with all currently configured vulnerable services available with a simple network connection. This should be expanded to include a larger number of VMs with services spread across them to better simulate a real world environment. Considerations must be taken for deploying this on systems with varying hardware availability, or look into different cloud providers.
Difficulty 4/5
### Add Monitoring Capabilities Between VMs
Metasploitable3 is already a playground from an attacker's point of view, but how can we make it valuable from a defender's perspective. Research various network monitoring and detections solutions and implement them across the mock network. Set up a new "NOC" VM for keeping track of activity and watching for intrusion. This goal is to make it fairly simple for anyone to set up a red team vs blue team mock environment.
Difficulty 5/5
## Goliath
### Data Visualization
Enhance existing Metasploit Goliath dashboard that allows observation of an active engagement. Data visualization would include, but not be limited to: host node graph with activity indicators and heat maps.
Write Goliath data to Elasticsearch. Explore data visualization using Kibana.
Difficulty 3/5
## Submit your own
If you want to suggest your own idea, please discuss it with us first on [our mailing list](https://groups.google.com/forum/#!forum/metasploit-hackers) to make sure it is a reasonable amount of work for a summer and that it fits the goals of the project.
GSoC Project Ideas in no particular order. When you've picked one, take a look at [[How-to-Apply-to-GSoC]] for how to make a proposal.
Mentors: @zerosteiner, @jmartin-r7
## Enhance Metasploit Framework
### Improving post-exploit API to be more consistent, work smoothly across session types
The Metasploit post-exploitation API is intended to provide a unified interface between different Meterpreter, shell, powershell, mainframe, and other session types. However, there are areas where the implementation is not consistent, and could use improvements:
* Shell sessions do not implement the filesystem API that Meterpreter sessions have
* When a shell session is in a different language, e.g. Windows in French, the post API does not find the expected output. Add localization support for these.
* Simple commands like 'cmd_exec' are fast in Shell sessions but are relatively slow in Meterpreter sessions. Add an API to make Meterpreter run simple commands more easily.
Difficulty: Varies
### Improve the web vulnerability API
This would follow up on the Arachni plugin PR <https://github.com/rapid7/metasploit-framework/pull/8618> and improve the Metasploit data model to better represent modern web vulnerabilities. This project would require knowledge of data models, types of modern web vulnerabilities, and experience with web app security scanners.
Difficulty: 4/5
### Session-style module interaction
Metasploit has the concept of 'sessions' where a connection context can define its own set of console operations. E.g. if you interact with a session, Metasploit switches to a specific subconsole for interaction. It would be nice as an alternative to 'action' for auxiliary modules, or as a way to merge related modules, to simply interact with the module.
Difficulty: 3/5
### Enhance Sql Injection Support
Enable faster implementation of SQL injection based explot modules by adding library support for common injection attack vectors. Currently very few sql injection exploits are implemented for Metasploit possibly due to the high complexity of building out injection queries and posting them to a vulnerable URI.
Difficulty: 3/5
### Conditionally Exposed Options
The Metasploit Framework's modules offer the core functionality of the project and these each use a set of datastore options for configuration. Many modules specify a particular system that they target or action that they provide. Modules should (but currently lack) the ability to expose and hide options through the UI based on either the target or action that they take. This would allow module developers to create more flexible modules without sacrificing user experience by exposing options that are irrelevant based on the current configuration.
Difficulty: 2/5
## Goliath
### Data Visualization
Enhance existing Metasploit Goliath dashboard that allows observation of an active engagement. Data visualization would include, but not be limited to: host node graph with activity indicators and heat maps.
Write Goliath data to Elasticsearch. Explore data visualization using Kibana.
Difficulty 3/5
## Submit your own
If you want to suggest your own idea, please discuss it with us first on [our mailing list](https://groups.google.com/forum/#!forum/metasploit-hackers) to make sure it is a reasonable amount of work for a summer and that it fits the goals of the project.
GSoC Project Ideas in no particular order. When you've picked one, take a look at [[How-to-Apply-to-GSoC]] for how to make a proposal.
Mentors: @zerosteiner, @jmartin-r7
## Enhance Metasploit Framework
### Retain active status of authentication tokens
Many testing techniques interacting with web servers such as `XSS` rely on ensuring authentication obtained on a target be kept active. A mechanism for regstering and maintaining open authentications identified during a test for the duration of the console session may provide an additional utility to enable more modules to target techniques that need valid authentication to be maintained. One such authentication token would be data retained in a cookie for a web service. This project would lay the groundwork for registering gathered or generated authenticaion tokens against a target to be refreshed and sustained until a console exits, or in some cases across console restarts.
Difficulty: 2/5
### Improving post-exploit API to be more consistent, work smoothly across session types
The Metasploit post-exploitation API is intended to provide a unified interface between different Meterpreter, shell, powershell, mainframe, and other session types. However, there are areas where the implementation is not consistent, and could use improvements:
* Shell sessions do not implement the filesystem API that Meterpreter sessions have
* When a shell session is in a different language, e.g. Windows in French, the post API does not find the expected output. Add localization support for these.
* Simple commands like 'cmd_exec' are fast in Shell sessions but are relatively slow in Meterpreter sessions. Add an API to make Meterpreter run simple commands more easily.
Difficulty: Varies
### Improve the web vulnerability API
This would follow up on the Arachni plugin PR <https://github.com/rapid7/metasploit-framework/pull/8618> and improve the Metasploit data model to better represent modern web vulnerabilities. This project would require knowledge of data models, types of modern web vulnerabilities, and experience with web app security scanners.
Difficulty: 4/5
### Data Visualization
Enhance existing Metasploit Goliath dashboard that allows observation of an active engagement. Data visualization would include, but not be limited to: host node graph with activity indicators and heat maps.
Write Goliath data to Elasticsearch. Explore data visualization using Kibana.
Difficulty 3/5
## Submit your own
If you want to suggest your own idea, please discuss it with us first on [our mailing list](https://groups.google.com/forum/#!forum/metasploit-hackers) to make sure it is a reasonable amount of work for a summer and that it fits the goals of the project.
GSoC Project Ideas in no particular order. When you've picked one, take a look at [[How-to-Apply-to-GSoC]] for how to make a proposal.
Mentors: @zerosteiner, @jmartin-r7, @gwillcox-r7
Slack Contacts: @zeroSteiner, @Op3n4M3, @gwillcox-r7 on [Metasploit Slack](https://metasploit.slack.com/)
For any questions about these projects reach out on the Metasploit Slack in the `#gsoc` channel or DM one of the mentors using the Slack contacts listed above. Note that mentors may be busy so please don't expect an immediate response, however we will endeavor to respond as soon as possible. If you'd prefer not to join Slack, you can also email `msfdev [@] metasploit [dot] com` and we will respond to your questions there if email is preferable.
## Enhance Metasploit Framework
### HTTP-Trace enabled login scanners
Current login scanners are not enabled to support the HTTP-Trace options, this options is current exposed in the `Exploit::Remote::HttpClient` mixin and not available in login scanners. This functionality would aid module writers in debugging and testing initial module implementations as well as enable end users to provide more verbose details for error reports. Changes to enable this support will need careful validation and testing as a large number of modules would be potentially impacted by the revision.
Size: Medium
Difficulty: 3/5
### Rest API Pagination
Metasploit provides two API interaction services, a Rest API service and an RPC service. Previous efforts have wrapped and exposed the RPC service as JSON responses available from the Rest API endpoint. This wrapping did not account for possible large responses that may benefit from pagination. A previous contributor attempted to add this functionality for a [limited set of RCP commands](https://github.com/rapid7/metasploit-framework/pull/13439) however review identified that the changes would introduce changes to the documented public API and also introduce inconsistency within the API responses resulting in a fluctuating public API. Modern pagination would be beneficial to increasing user adoption of Rest API services provided it can be implemented consistently and either maintain compatibility of the existing public RPC service or generate a one time migration across all exposed public APIs.
Size: Large
Difficulty: 4/5
### LDAP Capture Capabilities
Metasploit's LDAP service mixin provides a service to enable interaction over the LDAP protocol. The current implementation is the bare minimum to enable support for attacking the [2021 Log4Shell vulnerability](). Enhancement/Extension of the mixin to enable various additional LDAP features would enable extended usage of this service for additional tasks. Support for various protocol level authentication methods would allow Metasploit to intercept and log authentication information. Specific items of interest are [SPNEGO](https://en.wikipedia.org/wiki/SPNEGO) and [StartTLS](https://ldapwiki.com/wiki/StartTLS) support to enable compatibility with the widest variety of clients and a new capture module that log authentication information from clients.
Size: Medium
Difficulty: 3/5
### Enhanced LDAP Query & Collection
When preforming security assessment on a network with centralized login such as LDAP or Active Directory these services are sometimes exposed directly on the network. While Metasploit has capabilities to collect various pieces of information from these services when a user has been able to gain code execution inside a target system by utilizing tooling such as `Sharphound` or by leveraging SMB services via the `secrets_dump` module, these methods are somewhat indirect. A network base capability to query exposed services may have value. An interactive terminal plugin allowing users to connect directly to LDAP or Active Directory providing capabilities similar to the existing `requests` plugin could enable users search for valuable information in these services without the need to compromise a target or interact with a secondary service.
Size: Medium/Large (Depends on proposal)
Difficulty: 3/5
### Improving post-exploit API to be more consistent, work smoothly across session types
The Metasploit post-exploitation API is intended to provide a unified interface between different Meterpreter, shell, PowerShell, mainframe, and other session types. However, there are areas where the implementation is not consistent, and could use improvements:
* Shell sessions do not implement the filesystem API that Meterpreter sessions have
* When a shell session is in a different language, e.g. Windows in French, the post API does not find the expected output. Add localization support for these.
* Simple commands like 'cmd_exec' are fast in Shell sessions but are relatively slow in Meterpreter sessions. Add an API to make Meterpreter run simple commands more easily.
Size: Medium/Large (Depends on proposal)
Difficulty: Varies
### Improve the web vulnerability API
This would follow up on the Arachni plugin PR <https://github.com/rapid7/metasploit-framework/pull/8618> and improve the Metasploit data model to better represent modern web vulnerabilities. This project would require knowledge of data models, types of modern web vulnerabilities, and experience with web app security scanners.
Size: Large
Difficulty: 4/5
### Data Visualization
Enhance existing Metasploit Goliath dashboard that allows observation of an active engagement. Data visualization would include, but not be limited to: host node graph with activity indicators and heat maps. The main idea here is to create a visualization tool that helps users understand data that has been gathered into Metasploit during usage in some useful way. Proposals should note where the service will live, how a user will use the service, and how you will provide a maintainable and extendable consumer for the data that is exposed.
See [Metasploit 'Goliath' Demo (msf-red)](https://www.youtube.com/watch?v=hvuy6A-ie1g&feature=youtu.be&t=176) for a demo video of Goliath in action. You can also read more on Metasploit Goliath at [Metasploit-Data-Service-Enhancements-(Goliath)](./Metasploit-Data-Service-Enhancements-Goliath)
Size: Medium/Large (Depends on proposal)
Difficulty 3/5
## Submit your own
If you want to suggest your own idea, please discuss it with us first on [Slack](https://metasploit.com/slack) in the `#gsoc` channel to make sure it is a reasonable amount of work for a summer and that it fits the goals of the project.
Instead of embedding static Java serialized objects, Metasploit offers ysoserial-generated binaries with built-in randomization. The benefits of using the Metasploit library include quicker module development, easier-to-read code, and future-proof Java serialized objects.
To use the ysoserial libraries, let's look at an example from the [shiro_rememberme_v124_deserialize][2] module:
## Example code
In this example:
1. (L11) The module includes the `Msf::Exploit::JavaDeserialization` mixin.
* This exposes the necessary methods.
1. (L79) Then it uses the `generate_java_deserialization_for_payload` method to create a serialized Java object based on the `CommonsCollections2` YSoSerial payload that will execute the Metasploit payload.
* Note that the Metasploit `payload` object is passed as-is, without any conversion.
This method will generate a serialized Java object that when loaded will execute the specified Metasploit payload. The payload will be converted to an operating system command using one of the supported techniques contained within this method and then passed to [`#generate_java_deserialization_for_command`](#generate_java_deserialization_for_commandname-shell-command).
- **name** - The payload name parameter must be one of the supported payloads stored in the `ysoserial` cache. As of this writing, the list includes: `BeanShelll1`, `Clogure`, `CommonsBeanutils1`, `CommonsCollections2`, `CommonsCollections3`, `CommonsCollections4`, `CommonsCollections5`, `CommonsCollections6`, `Groovy1`, `Hibernate1`, `JBossInterceptors1`, `JRMPClient`, `JSON1`, `JavassistWeld1`, `Jdk7u21`, `MozillaRhino1`, `Myfaces1`, `ROME`, `Spring1`, `Spring2`, and `Vaadin1`. While `ysoserial` includes additional payloads that are not listed above, they are unsupported by the library due to the need for complex inputs. Should there be use cases for additional payloads, please consider opening an issue and submitting a pull request to add support.
- **payload** - The payload object to execute on the remote system. This is the native Metasploit payload object and it will be automatically converted to an operating system command using a technique suitable for the target platform and architecture. For example, x86 Windows payloads will be converted using a Powershell command. Not all platforms and architecture combinations are supported. Unsupported combinations will result in a `RuntimeError` being raised which will need to be handled by the module developer.
This method will generate a serialized Java object that when loaded will execute the specific operating system command using the specified shell. Invocation of the command through the shell effectively bypasses constraints on the characters within the operating system command.
- **name** - The payload name parameter. This has the same significance as the *name* parameter for the [`#generate_java_deserialization_for_payload`](#generate_java_deserialization_for_payloadname-payload) method.
- **shell** - The shell to use for invoking the command. This value must be one of the following:
- **bash** - A modified version that will invoke the command using the `bash` executable
- **cmd** - A modified version that will invoke the command using the Windows `cmd.exe` executable.
- **powershell** - A modified version that will invoke the command using the Windows `powershell.exe` executable.
- **command** - The operating system command to execute upon successful deserialization of the generated object.
## Regenerating the ysoserial_payload JSON file (MAINTAINERS ONLY)
**Neither module developers nor users need to concern themselves with the following.**
On occasion, Metasploit maintainers may want to re-run the script generation to incorporate new Java serialized objects from the ysoserial tool.
To avoid invoking Java (and all its dependencies) at runtime, the serialized objects are generated and cached within a JSON file. The JSON file can be refreshed using a standalone Ruby script, which comes prepackaged with a Docker image that handles downloading `ysoserial` and necessary dependencies. The script, `Dockerimage` and a high-level `runme.sh` script is stored within `tools/payloads/ysoserial`. An example run looks like:
```
$ cd ~/git/r7/metasploit-framework/tools/payloads/ysoserial
$ ./runme.sh
Sending build context to Docker daemon 101.8MB
Step 1/8 : FROM ubuntu
---> cd6d8154f1e1
Step 2/8 : RUN apt update && apt -y upgrade
---> Using cache
---> ba7e5691ed5a
Step 3/8 : RUN apt install -y wget openjdk-8-jre-headless ruby-dev make gcc
---> Using cache
---> d38488663627
Step 4/8 : RUN wget -q https://jitpack.io/com/github/frohoff/ysoserial/master-SNAPSHOT/ysoserial-master-SNAPSHOT.jar -O ysoserial-original.jar
---> Using cache
---> 284ff722464b
Step 5/8 : RUN wget -q https://github.com/pimps/ysoserial-modified/raw/master/target/ysoserial-modified.jar
---> Using cache
---> 334c1ccb6fab
Step 6/8 : RUN gem install --silent diff-lcs json pry
---> Using cache
---> 9d452be9d01f
Step 7/8 : COPY find_ysoserial_offsets.rb /
---> 61b6f339590c
Step 8/8 : CMD ruby /find_ysoserial_offsets.rb
---> Running in ba7b14646e56
Removing intermediate container ba7b14646e56
---> f4ca5ecb6848
Successfully built f4ca5ecb6848
Successfully tagged ysoserial-payloads:latest
Generating payloads for BeanShell1...
Generating payloads for C3P0...
Error while generating or serializing payload
java.lang.IllegalArgumentException: Command format is: <base_url>:<classname>
at ysoserial.payloads.C3P0.getObject(C3P0.java:48)
at ysoserial.GeneratePayload.main(GeneratePayload.java:34)
ERROR: Errored while generating 'C3P0' and it will not be supported
At completion, the `data/ysoserial_payloads.json` file is overwritten and the 22 dynamic payloads are ready for use within the framework. Afterward, the developer should follow the standard `git` procedures to `add` and `commit` the new JSON file before generating a pull request and landing the updated JSON into the framework's `master` branch.
The real kung-fu behind exploit development isn't actually about which language you choose to build it; it's about your precise understanding of how input is processed by the application you're debugging, and how to gain control by manipulating it. That's right; the keyword is "debugging." Your binjitsu (reverse-engineering) is where the real kung-fu is. However, if your goal isn't just about popping a calculator, but actually want to weaponize, to maintain, and to provide use in the practical world, you need a development framework. And this is where Metasploit comes in. It's a framework that's free and open-source, actively contributed by researchers around the world. So when you write a Metasploit exploit, you don't have to worry about any [dependency issues](http://en.wikipedia.org/wiki/Dependency_hell), or having the wrong version, or not having enough payloads for different pentesting scenarios to choose from, etc. The idea is all you need to do is focus on building that exploit, and nothing more.
## Plan your module
First, ask yourself will exploiting this vulnerability result in executing a payload? If not, then despite exploiting a vulnerability, for Metasploit's purposes the module would fall into the [[auxiliary|How-to-get-started-with-writing-an-auxiliary-module]] category.
Unlike writing a proof-of-concept, when you write a Metasploit module, you need to think about how users might use it in the real world. Stealth is usually an important element to think about. Can your exploit achieve code execution without dropping a file? Can the input look more random, so it's more difficult to detect? How about obfuscation? Is it generating unnecessary traffic? Can it be more stable without crashing the system?
Try to be precise about exploitable requirements. Usually, a bug is specific to a range of versions or even builds. If you can't automatically check that, you need to at least mention it in the description somewhere.
Some of your exploit's techniques might also be application-specific. For example, you can take advantage of a specific behavior in the application to generate heap allocations the way you want, but maybe it's noisier in the newer version, so that gives you some stability issues. Does it need a 3rd-party component to work that may not even be installed by everyone? Even if it is, is the component revised often enough that it could make your exploit less reliable?
Know that in the real world, your exploit can break or fail in a lot of different ways. You should try to find out and fix it during the development and testing phase before learning the hard way.
## Ranking
As you can see, reliability is important to Metasploit, and we try to be more friendly about this for the users. I know what you're thinking: "Well, if they're using the exploit, they should understand how it works, so they know what they're getting themselves into." In the perfect world, yes. Knowing how a vulnerability works or how an exploit works will only benefit the user, but you see, we don't live in the perfect world. If you're in the middle of a penetration test, it's very unlikely to always find the time to recreate the vulnerable environment, strip the exploit to the most basic form to debug what's going on, and then do testing. Chances are you have a tight schedule to break into a large network, so you need to use your time carefully. Because of this, it's important to at least have a good description and good references for the module. And of course, a ranking system that can be trusted.
The Metasploit Framework has seven different rankings to indicate how reliable an exploit is. See [[Exploit Ranking]] for more details.
## Template
If you have read this far, we think you are pretty impressive because it's a lot to digest. You are probably wondering why we haven't had a single line of code to share in the writeup. Well, as you recall, exploit development is mostly about your reversing skills. If you have all that, we shouldn't be telling you how to write an exploit. What we've done so far is hopefully get your mindset dialed-in correctly about what it means to become a Metasploit exploit developer for the security community; the rest is more about how to use our mixins to build that exploit. Well, there are A LOT of mixins, so it's impossible to go over all of them in a single page, so you must either read the [API documentation](https://rapid7.github.io/metasploit-framework/api/), existing [code examples](https://github.com/rapid7/metasploit-framework/tree/master/modules/exploits), or look for more wiki pages we've written to cover specific mixins.
For example, if you're looking for a writeup about how to interact with an HTTP server, you might be interested in: [How to send an HTTP Request Using HTTPClient](https://github.com/rapid7/metasploit-framework/wiki/How-to-Send-an-HTTP-Request-Using-HTTPClient). If you're interested in browser exploit writing, definitely check out: [How to write a browser exploit using BrowserExploitServer](https://github.com/rapid7/metasploit-framework/wiki/How-to-write-a-browser-exploit-using-BrowserExploitServer), etc.
But of course, to begin, you most likely need a template to work with, and here it is. We'll also explain how to fill out the required fields:
```ruby
##
# This module requires Metasploit: http://metasploit.com/download
# Current source: https://github.com/rapid7/metasploit-framework
'Ret'=>0x41414141# This will be available in `target.ret`
}
]
],
'Payload'=>
{
'BadChars'=>"\x00"
},
'Privileged'=>false,
'DisclosureDate'=>"",
'DefaultTarget'=>0))
end
defcheck
# For the check command
end
defexploit
# Main function
end
end
```
* **Name** - The Name field should begin with the name of the vendor, followed by the software. Ideally, the "Root Cause" field means which component or function the bug is found. And finally, the type of vulnerability the module is exploiting.
* **Description** - The Description field should explain what the module does, things to watch out for, specific requirements, the more, the better. The goal is to let the user understand what he's using without the need to actually read the module's source and figure things out. And trust me, most of them don't.
* **Author** field is where you put your name. The format should be "Name ". If you want to have your Twitter handle there, leave it as a comment, for example: "Name # handle"
* **References** - The References field is an array of [references](https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/reference.rb) related to the vulnerability or the exploit. For example, an advisory, a blog post, etc. Make sure you use known reference identifiers -- see [[Module reference identifiers]] for a list.
* **Platform** - The Platform field indicates what platforms are supported, for example: win, linux, osx, unix, bsd.
* **Targets** - The Targets field is an array of systems, applications, setups, or specific versions your exploit is targeting. The second element or each target array is where you store specific metadata about that target, for example, a specific offset, a gadget, a ret address, etc. When a target is selected by the user, the metadata is loaded and tracked by a "target index", and can be retrieved by using the `target` method.
* **Payloads** - The Payloads field specifies how the payload should be encoded and generated. You can specify: `Space`, `SaveRegisters`, `Prepend`, `PrependEncoder`, `BadChars`, `Append`, `AppendEncoder`, `MaxNops`, `MinNops`, `Encoder`, `Nop`, `EncoderType`, `EncoderOptions`, `ExtendedOptions`, `EncoderDontFallThrough`.
**DisclosureDate** - The DisclosureDate is about when the vulnerability was disclosed in public, in the format of: "M D Y". For example: "Apr 04 2014"
Your exploit should also have a `check` method to support the check command, but this is optional in case it's not possible.
And finally, the `exploit` method is like your main method. Start writing your code there.
An example exploit module is also available: [example.rb](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/example.rb)
## Basic git commands
Metasploit no longer uses svn for source code management. Instead, we use git, so knowing some tricks with git go a long way. We're not here to lecture you about how awesome git is; we know it has a learning curve, and it's not surprising to find new users making mistakes. Every once a while, your git "rage" will kick in, and we understand. However, it's important for you to take advantage of branching.
Every time you make a module or make some changes to existing code, you should not do so on the default master branch. Why? Because when you do a ```msfupdate```, which is Metasploit's utility for updating your repository, it will do a git reset before merging the changes, and all your code goes away.
Another mistake people tend to do is have all the changes on master before submitting a pull request. This is a bad idea because most likely; you're submitting other crap you don't intend to change, or you're probably asking us to merge other unnecessary commit histories when there only needs to be one commit. Thanks for contributing your module to the community, but no thanks to your crazy commit history.
So as a habit, when you want to make something new, or change something, begin with a new branch that's up to date to master. First off, make sure you're on master. If you do a ```git status``` it will tell you what branch you're currently on:
```bash
$ git status
# On branch upstream-master
nothing to commit, working directory clean
```
Ok, now do a ```git pull``` to download the latest changes from Metasploit:
```bash
$ git pull
Already up-to-date.
```
At this point, you're ready to start a new branch. In this case, we'll name our new branch "my_awesome_branch":
```bash
$ git checkout -b my_awesome_branch
Switched to a new branch 'my_awesome_branch'
```
And then you can go ahead and add that module. Make sure it's in the appropriate path:
```bash
$ git add [module path]
```
When you decide to save the changes, commit (if there's only one module, you can do ```git commit -a``` too so you don't have to type the module path. Note ```-a``` really means EVERYTHING):
```bash
$ git commit [module path]
```
When you're done, push your changes, which will upload your code to your remote branch "my_awesome_branch". You must push your changes in order to submit the pull request or share it with others on the Internet.
Contributions from the open source community are the soul of Metasploit, and we love evaluating and landing pull requests that add new Framework features and content. Metasploit Framework has many tens of thousands of users who rely on daily, consistent, and error-free updates. Because of this, Metasploit's core developers have adopted a fairly high standard for pull requests that add new Framework functionality and Metasploit modules. In order to encourage open and transparent development, this document outlines some general guidelines for Metasploit contributors and developers. Adhering to these guidelines maximizes the chances that your work will be merged into the official Metasploit distribution packages.
## Module Additions
Most open source community support for Metasploit comes in the form of Metasploit modules. The following should be considered for acceptance; note that these are guidelines and not categorical imperatives ("should"s, not "must"s), since there are always exceptions to the norm-especially when it comes to novel new attacks and techniques.
Modules should pass [msftidy.rb](https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/msftidy.rb) and adhere to the [CONTRIBUTING.md](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md) guidelines. Both are distributed with Metasploit. See [[Style Tips]] for some information on how to take some of the headache out of whitespace issues.
Modules should have a clear and obvious goal: Exploits should result in a shell. Post modules should result in privilege escalation or loot. Auxiliary modules are an "Everything else" category, but even they should be limited to a well-defined task (e.g., information gathering to enable an exploit or a post module).
Modules should not launch other modules, given the complexity of setting multiple payloads. Such actions are usually automation tasks for an external UI.
Denial of Service modules should be asymmetric and at least have some interesting feature. If it's comparable to a synflood, it shouldn't be included. If it's comparable to Baliwicked, it should be included. Modules that hover the line, such as slowloris, may be included with some justification.
Modules should be able to function as expected with minimal configuration. Defaults should be sensible and usually correct. Modules should not depend on exact timing, uncontrollable heap states, system DLLs, etc. All memory addresses (ie. a JMP ESP, or a ROP gadget) should be part of the metadata under 'Targets', and documented (what instructions it points to, and what DLL). If the exploit is against a specific hardware (e.g., routers, PLCs, etc), or against a software that's not free (and no trial/demo available), please remember to submit a binary packet capture (pcap-formatted) along with the module that demonstrates the exploit actually works.
Please don't use the alphanum encoder as a way to avoid BadChar analysis. Modules which set the `EncoderType` field in the payload as a way to avoid doing real BadChar analysis will be rejected. These modules are nearly always unreliable in the real world.
Exploit ranking definitions can be found on the [[Exploit Ranking]] page.
Exploit modules should implement a `check()` function when this is trivial to do so. Versions exposed through banners or network protocols should always result in a `check()` routine when a patch is available that changes this version.
If a module (auxiliary or post) obtains some sort of information from the victim machine, it should store that data using one (or more) of the following methods:
*`store_loot()`: Used to store both stolen files (both text and binary) and "screencaps" of commands such as a `ps -ef` and `ifconfig`. The file itself need not be of forensic-level integrity -- they may be parsed by a post module to extract only the relevant information for a penetration tester.
*`report_auth_info()`: Used to store working credentials that are immediately reusable by another module. For example, a module dumping the local SMB hashes would use this, as would a module which reads username:password combinations for a specific host and service. Specifically, merely "likely" usernames and passwords should use `store_loot()` instead.
*`report_vuln()`: Auxiliary and post modules that exercise a particular vulnerability should `report_vuln()` upon success. Note that exploit modules automatically `report_vuln()` as part of opening a session (there is no need to call it especially).
*`report_note()`: Modules should make an effort to avoid `report_note()` when one of the above methods would be a better fit, but there are often cases where "loot" or "cred" or "vuln" classifications are not immediately appropriate. `report_note()` calls should always set a OID-style dotted `:type`, such as `domain.hosts`, so other modules may easily find them in the database.
Modules should take advantage of the normal Metasploit APIs. For example, they should not attempt to create their own TCP sockets or application protocols with native Ruby; they should mediate sockets through `Rex` and `Rex::Proto` methods instead. This ensures compatibility with the full set of Framework features, such as pivoting and proxy chaining.
Web application attacks are generally uninteresting (SQLi, XSS, CSRF), unless the module can reliably result in a shell or exercise some kind of useful information leak. Even in that case, the module should "just work," as above.
Web application attacks should be limited only to popular, widely deployed applications. For example, a SQLi module against a popular CMS that results in a shell on the CMS machine would be welcome. A module that causes a private Facebook profile to become public would not (Facebook has exactly one deployed instance).
Web application attacks should implement an HttpFingerprint constant.
Modules should only list targets that **you** actually tested the exploit on. Avoid assuming it works on a specific system if it has never been tested on it. Comments above the target entry indicating additional information about a given target (language pack, patch level, etc) greatly assist other developers in creating additional targets and improving your module.
Modules can exercise unpatched and undisclosed vulnerabilities. However, Rapid7 is happy to assist with the disclosure process by following the Rapid7 policy. This policy provides a fixed 90-day window from when the vendor is contacted until the exploit is released. All vulnerabilities found by Rapid7 staff follow this process. The submitter will receive full credit for the vulnerability and the resulting exploit module regardless of how disclosure is handled.
## Framework Enhancements
Generally, new functionality to the Metasploit Framework should start life as a plugin. If the functionality becomes useful and popular, we can integrate it more closely, add RPC API exposure, and so on, but it should be well-tested by the community before then.
Automating a series of discrete functions is generally /not/ the responsibility of the Framework. Automation should be accomplished through the API (see Metasploit Community/Pro, MSFGUI, etc). Past efforts with in-Framework automation prove this out. Components such as `db_autopwn` and `browser_autopwn` rarely did what users expected, and configuring these tools became a nightmare through increasingly complex sets of options and arguments. Automating the Framework is easy and should stay easy, but the automation itself should live in resource scripts and other external front-ends to the Framework itself.
Console functionality should have a focus on exploit and security tool development, with the exploit developer as the typical user. End users should be pointed to an interface such as the Community Edition or MSFGUI and should not expect much in terms of user-friendliness from the console. The console should be considered a debug mode for Metasploit and as close to bare-metal functionality as possible.
External tools, such `msfpayload` and `msfvenom`, are designed to make exploit development easier and exercise specific techniques. We are happy to continue evaluating tools of this nature for inclusion in the Framework; these should be accompanied by documentation (!), how-to tutorials for quick start, and other helpful text.
This is a simple guideline to write SMB-based modules, focusing on the new RubySMB implementation that includes SMB3 support.
## SMB Protocol Overview
SMB (Server Message Block) is a network communication protocol that provides file sharing, network browsing, printing services, and interprocess communication over a network. It relies on lower level protocol transports:
* NetBIOS
- over TCP/IP (NBT) on 137/UDP, 138/UDP, 137/TCP and 139/TCP
- over NetBEUI
* Directly over TCP on 445/TCP (by far the most commonly used)
[CIFS](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-cifs/d416ff7c-c536-406e-a951-4f04b2fd1d2b) is a particular implementation of SMB created by Microsoft based on the original IBM specifications. It has been replaced by [SMB v1.0](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb/f210069c-7086-4dc2-885e-861d837df688), which is a Microsoft Extensions to MS-CIFS.
[SMB2](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/5606ad47-5ee0-437a-817e-70c366052962) is a complete rewrite of the protocol which primarily aims to reduce the amount of messages exchanged between the client and the server. SMB v2.0 has been introduced in Windows Vista/Server 2008. It also brings some new features such as:
* Pipelining
* Symbolic links
* Large file transfers improvement
* Better signing
* New opportunistic locking mechanism
SMB v2.1 was added to Windows 7/Server 2008 R2 with a few improvements:
* Minor performance enhancements
* New opportunistic locking mechanism
[SMB3](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/5606ad47-5ee0-437a-817e-70c366052962) adds some interesting features and has been introduced in Windows 8/Server 2012. Here are some new capabilities added by the SMB v3.0 dialect:
* SMB Direct (SMB over remote direct memory access - RDMA)
* SMB Multichannel (multiple connections per SMB session)
* SMB Transparent Failover (useful for clustered file server)
* Per-share encryption (AES-128 CCM) and AES-based signing
SMB v3.0.2 (from Windows 8.1/Server 2012 R2) only adds some small improvements. Finally, SMB v3.1.1 (from Windows 10/Server 2016) introduces the following features:
* Negotiation of encryption and integrity algorithms
* AES-128 GCM encryption
* Pre-authentication integrity check (SHA-512)
* Compression
## Common SMB Packet Exchange Scenarios
1.**NetBIOS session establishment**
This step is only required if NetBIOS over TCP (NBT) transport is used. This is not very common anymore, since SMB over TCP (from windows 2000) removed the NetBIOS transport layer. In case a NetBIOS session needs to be established, this must be the first packet exchange.
2.**Negotiation**
This is where the SMB protocol version and dialect are going to be negotiated between the client and the server. From SMB v3.1.1, encryption/compression capabilities are also negotiated at the same time.
3.**Authentication**
Depending on the authentication scheme, this step requires one or two packet exchanges. NTLM challenge-response, the only authentication protocol supported by RubySMB at time of writing, consists of sending first a Session Setup packet containing the client capabilities. The server responds with a challenge. Then, another Session Setup request is sent with the challenge response. If it is accepted, the server returns a Session ID that will be used in subsequent requests. This defines the beginning of an SMB Session.
Once the SMB session is established, the SMB client must connect to a remote share.This is done by sending a TreeConnect request and getting a Tree ID. This identifier will be used by subsequent file operations on this share.
5.**File operation**
From there, the client can execute any file operation on the remote share, such as open, read, write, delete, rename, etc. When the client is done with a file, it can simply close the handle. The Tree ID remains valid and can be reused.
<figure>
<img src="https://user-images.githubusercontent.com/56716719/89446561-f96b3980-d754-11ea-868c-7714366168f5.png" alt="Connect to share and read file">
The client can decide to release the connection to the share at any time by sending a TreeDisconnect request. Note that the SMB session will remain active until the client sends a Logoff packet, which defines the end of the SMB Session.
## Module Writing
### Using the default MSF client
The following mixin will bring everything you need, including the main MSF SMB Client.
The first step is to initialize the client by invoking `connect`. The version(s) that will be negotiated can also be set up by passing an array to the keyword arguments versions. For example, to negotiate any dialect of SMB version 2 and 3, use this:
```ruby
connect(versions:[2,3])
```
The default is to negotiate versions 1, 2 and 3. Note that the client will just let the SMB server know which versions and dialects it supports. The server will always choose the latest version it supports. This means, Windows 7 will always choose SMB v2.1 (SMB3 has been added to Windows 8 only), even if versions 1, 2 and 3 are advertised by the client. If SMB2 is disabled on this host for whatever reason, the SMB server will fall back to SMB1. By choosing which versions the client must negotiate, you can force the server to use a specific protocol version, assuming it is supported and enabled.
From Metasploit 6, the MSF client uses RubySMB under the hood by default for any SMB protocol version. For compatibility with older modules, it is still possible to force the client to use the original Rex SMB implementation. Note that this is **not recommended** and RubySMB should be the default for new modules. This can be done by explicitly negotiate SMB1 only (Rex only supports this version):
```ruby
connect(versions:[1])
```
2.**NetBIOS session, negotiation and authentication**
The actual negotiation and authentication are handled by `smb_login`. This retrieves the NetBIOS name, user name, password and domain from the `SMBName`, `SMBUser`, `SMBPass` and `SMBDomain` options set by the operator, respectively. Other options can be set and are defined in [MSF SMB client](https://github.com/rapid7/metasploit-framework/blob/a7d255bbe5537822c614ede71933fdc6597dd369/lib/msf/core/exploit/remote/smb/client.rb). Under the hood, `smb_login` establishes the NetBIOS session (if needed), negotiates the protocol version/dialect and sets the SMB Session up using NTLM challenge-response authentication protocol.
If, for whatever reason, the authentication options cannot be retrieved from the user options, it is still possible to provide them manually by calling `simple.login()` directly (see [SimpleClient#login](https://github.com/rapid7/metasploit-framework/blob/a7d255bbe5537822c614ede71933fdc6597dd369/lib/rex/proto/smb/simple_client.rb#L55))
```ruby
simple.login(name,user,pass)
```
Note that `simple` is the `Rex::Proto::SMB::SimpleClient` object and is accessible anywhere in the module. This is the main interface to interact with RubySMB (more on that later).
3.**Connect to a share**
This is done by invoking `simple.connect`:
```ruby
simple.connect("\\\\<host>\\<share>")
```
4.**File operations**
* read a file
```ruby
file_path='file/path/relative/to/the/share/root'
file=smb_open(file_path,'o')
print_status("File content: #{file.read}")
file.close
```
See [SimpleClient#open](https://github.com/rapid7/metasploit-framework/blob/a7d255bbe5537822c614ede71933fdc6597dd369/lib/rex/proto/smb/simple_client.rb#L189) and [RubySMB::Dispositions](https://github.com/rapid7/ruby_smb/blob/a8af935d1f4b5fb57fc7c13490ca75bdacf032b9/lib/ruby_smb/dispositions.rb) for details about the `smb_open` mode argument.
* write to a file
```ruby
file=smb_open(file_path,'co',write:true)
file<<"my file data"
file.close
```
* delete a file
```ruby
simple.delete(file_path)
```
5.**Close the connection to the remote share**
```ruby
simple.disconnect("\\\\<host>\\<share>")
```
Since Metasploit 6, two new options were introduced to control version negotiation and encryption. These options are only available when using the default MSF SMB client and are automatically pulled in with `Msf::Exploit::Remote::SMB::Client` or `Msf::Exploit::Remote::SMB::Client::Authenticated` mixins:
*`SMB::ProtocolVersion`: one or a list of comma-separated SMB protocol versions to negotiate (e.g. "1" or "1,2" or "2,3,1").
*`SMB::AlwaysEncrypt`: enforces encryption even if the server does not require it (SMB3.x only). When it is set to false, the SMB client will still encrypt the communication if the server requires it.
### Using RubySMB client directly
This mixin is not required but can be useful to expose the SMB related options to the operator:
An alternative is to register the options we need in `initialize`:
```ruby
register_options([
OptString.new('SMBUser',[false,'The username to authenticate as','']),
OptString.new('SMBPass',[false,'The password for the specified username','']),
OptString.new('SMBDomain',[false,'The Windows domain to use for authentication','.']),
])
```
Following the same workflow described above:
1.**Initialization**
* setup the dispatcher
```ruby
dispatcher=RubySMB::Dispatcher::Socket.new(sock)
```
* initialize the client
SMB versions 1, 2 and 3 will be negotiated by default. Use `smb1`, `smb2` and `smb3` keyword arguments to disable a version (`false` value). See [RubySMB::Client#initialize](https://github.com/rapid7/ruby_smb/blob/a8af935d1f4b5fb57fc7c13490ca75bdacf032b9/lib/ruby_smb/client.rb#L281) for more initialization options
* read a file (see [RubySMB::SMB1::Tree](https://github.com/rapid7/ruby_smb/blob/a8af935d1f4b5fb57fc7c13490ca75bdacf032b9/lib/ruby_smb/smb1/tree.rb#L83) and [RubySMB::SMB2::Tree](https://github.com/rapid7/ruby_smb/blob/a8af935d1f4b5fb57fc7c13490ca75bdacf032b9/lib/ruby_smb/smb2/tree.rb#L67) for details)
* [Comprehensive list of `fail_with` parameters](#comprehensive-list-of-fail_with-parameters)
When a module fails, the `fail_with` method provides a standardized way to describe the reason for the failure. The first parameter depends on the cause of the failure.
## Example uses
`modules/exploits/osx/local/sudo_password_bypass.rb` fails using `Failure::NotVulnerable` if the `check` method does not indicate that the target is vulnerable:
```ruby
ifcheck!=CheckCode::Vulnerable
fail_withFailure::NotVulnerable,'Target is not vulnerable'
end
```
`modules/exploits/multi/http/struts2_namespace_ognl.rb` fails using the `Failure::PayloadFailed` if the target's response does not include a string indicating that the payload successfully executed. Alternatively, if the target responds with an HTTP error, the module invokes `fail_with` using the `Failure::UnexpectedReply` parameter:
| Failure::BadConfig | The user-provided parameters are invalid and must be corrected. |
| Failure::Disconnected | The target closed the connection forcibly. |
| Failure::NoAccess | An attempt to authenticate failed, likely due to invalid credentials. |
| Failure::None | The outcome for the module has already been met, for example a privilege escalation is already in an elevated context) |
| Failure::NoTarget | The specified TARGET or PAYLOAD variables are misconfigured or the target environment is unsupported. |
| Failure::NotFound | A preexisting file or resource on target is missing. |
| Failure::NotVulnerable | The target returned a response indicative of being patched or otherwise mitigated. |
| Failure::PayloadFailed | A return code from payload execution indicates the payload did not execute or terminated unexpectedly. |
| Failure::TimeoutExpired | The target did not respond to the connection request in a timely manner. Check RHOSTS and RPORT, then consider increasing WFSDelay. |
| Failure::UnexpectedReply | The target responded in an entirely unexpected way, and may not be running the vulnerable service at all. |
| Failure::Unknown | An entirely unexpected exception occurred, and the target may not be running the expected services at all. |
| Failure::Unreachable | The host or service is not reachable, often indicated by a refused connection or ICMP "unreachable" message. |
This article will discuss the various libraries, dependencies, and functionality built in to metasploit for dealing with password hashes, and cracking them. In general, this will not cover storing credentials in the database, which can be read about [here](https://github.com/rapid7/metasploit-framework/wiki/Creating-Metasploit-Framework-LoginScanners#the-scan-block). Metasploit currently support cracking passwords with [John the Ripper](https://github.com/rapid7/metasploit-framework/tree/master/modules/auxiliary/analyze) and [hashcat](https://github.com/rapid7/metasploit-framework/pull/11695).
# Hashes
Many modules dump hashes from various software. Anything from the OS: [Windows](https://github.com/rapid7/metasploit-framework/blob/master/modules/post/windows/gather/hashdump.rb), [OSX](https://github.com/rapid7/metasploit-framework/blob/master/modules/post/osx/gather/hashdump.rb), and [Linux](https://github.com/rapid7/metasploit-framework/blob/master/modules/post/linux/gather/hashdump.rb), to applications such as [postgres](https://github.com/rapid7/metasploit-framework/blob/master/modules/auxiliary/scanner/postgres/postgres_hashdump.rb), and [oracle](https://github.com/rapid7/metasploit-framework/blob/master/modules/auxiliary/scanner/oracle/oracle_hashdump.rb). Similar, to the [hash-identifier](https://code.google.com/archive/p/hash-identifier/) project, Metasploit includes a library to identify the type of a hash in a standard way. [identify.rb](https://github.com/rapid7/metasploit-framework/blob/master/lib/metasploit/framework/hashes/identify.rb) can be given a hash, and will return the `jtr` type. Metasploit standardizes to [John the Ripper](https://www.openwall.com/john/)'s types. While you may know the hash type being dumped already, using this library will help standardize future changes.
## Hash Identify Example
In this first, simple, example we will simply show loading the library and calling its function.
This section will cover the differences between the two crackers. This is not a comparison of speed, or why one may work better in a specific case than another.
While Metasploit standardizes with the JtR format, the hashcat [library](https://github.com/rapid7/metasploit-framework/blob/master/lib/metasploit/framework/password_crackers/cracker.rb) includes the `jtr_format_to_hashcat_format` function to translate from jtr to hashcat.
### Cracker Modes
Each crack mode is a set of rules which apply to that specific mode. The idea being any optimizations can be applied to that mode, and reset on other modes. These modes include:
Hashcat contains a `-O` flag which uses an optimized kernel. From internal testing it looks to be >200% faster, with a password length tradeoff. For more information see <https://github.com/rapid7/metasploit-framework/pull/12790>
### Exporting Passwords and Hashes
Hashes can be exported to three different file formats by using the `creds` command and specifying an output file with the `-o` option. When the file ends in `.jtr` or `.hcat` the John the Ripper or Hashcat formats will be used respectively. Any other file suffix will result in the data being exported in a CSV format.
**Warning:** When exporting in either the John the Ripper or Hashcat formats, any hashes that can not be handled by the formatter will be omitted. See the [Adding a New Hash](#Adding-a-New-Hash) section for details on updating the formatters.
Exported hashes can be filtered by a few fields like the username, and realm. One additional useful field is the hash type which can be specified with the `-t/--type` option. The type can be `password`, `ntlm`, `hash` or any of the John the Ripper format names such as `netntlmv2`.
Example to export all NetNTLMv2 secrets for the WORKGROUP realm for use with John the Ripper: `creds --realm WORKGROUP --type netntlmv2 -o /path/to/netntlmv2_hashes.jtr`
For testing Hashcat/JtR integration, this is a common list of commands to import example hashes of many different types. When possible the username is separated by an underscore, and anything after it is the password. For example `des_password`, the password for the hash is `password`:
Only hashes which were found in Metasploit were added to the hash id library, and the other functions. New hashes are developed often, and new modules which find a new type of hash will most definitely be created. So what are the steps to add a new hash type to Metasploit?
1. Add a new identify algorithm to: [framework/hashes/identify.rb](https://github.com/rapid7/metasploit-framework/blob/master/lib/metasploit/framework/hashes/identify.rb). You may want to consult external programs such as `hashid` or `hash-identifier` for suggestions.
1. Add the hash to the spec to ensure it works right now, and in future updates: [framework/hashes/identify_spec.rb](https://github.com/rapid7/metasploit-framework/blob/master/spec/lib/metasploit/framework/hashes/identify_spec.rb)
1. Make sure the hashes are saved in the DB in the JTR format. A good source to identify what the hashes look like is [pentestmonkey](http://pentestmonkey.net/cheat-sheet/john-the-ripper-hash-formats).
1. If applicable, add it into the appropriate cracker module (or create a new one). Example for [Windows related hashes](https://github.com/rapid7/metasploit-framework/blob/master/modules/auxiliary/analyze/crack_windows.rb).
1. Find the hashcat hash mode, and add a JTR name to [hashcat hash mode lookup](https://github.com/rapid7/metasploit-framework/blob/master/lib/metasploit/framework/password_crackers/cracker.rb#L129)
1. If hashcat uses a different format for the hash string, add a JTR to hashcat hash format conversion to the [formatter](https://github.com/rapid7/metasploit-framework/blob/master/lib/metasploit/framework/password_crackers/hashcat/formatter.rb)
Welcome to Metasploit-land. Are you a Metasploit user who wants to get started or get better at hacking stuff (that you have permission to hack)? The quickest way to get started is to [download the Metasploit nightly installers](https://github.com/rapid7/metasploit-framework/wiki/Nightly-Installers). This will give you access to both the free, open-source Metasploit Framework and a free trial of Metasploit Pro.
If you're using [Kali Linux](https://kali.org/), Metasploit is already pre-installed. See the [Kali documentation](https://kali.org/docs/tools/starting-metasploit-framework-in-kali/) for how to get started using Metasploit in Kali Linux.
Are you anxious to get your [Metasploit Development Environment](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment) set up so you can start [[Landing Pull Requests]] and contributing excellent exploit code? If so, you're in the right place. If you're an exploit developer, you will want to review our [[Guidelines for Accepting Modules and Enhancements]] to find out what we expect when we see pull requests for new Metasploit modules. No idea what you should start working on? Check out the guidelines for [[contributing to Metasploit]], and dive into [[Setting Up a Metasploit Development Environment]].
# Getting Started #
- [[Setting Up a Metasploit Development Environment]]
- [[Using Metasploit]]
- [[Using Git]]
- [[Reporting a Bug]]
- [[Navigating and Understanding Metasploit's Codebase|./Navigating-and-Understanding-Metasploits-Codebase.md]]
# Contributing
- [[Contributing to Metasploit]]
- [[Creating Metasploit Framework LoginScanners]]
- [[Guidelines for Accepting Modules and Enhancements]]
- [[Common Metasploit Module Coding Mistakes]]
- [[Style Tips]]
- [[Committer Rights]]
- [[Landing Pull Requests]]
# Metasploit Development #
- [[Style Tips]]
- [[Get Started Writing an Exploit]]
- [[How to get started with writing an auxiliary module]]
- [[How to get started with writing a post module]]
- [[How to get started with writing a Meterpreter script]]
- [[Running Private Modules]]
- [[Exploit Ranking]]
- [[Module Reference Identifiers]]
- [[How to check Microsoft patch levels for your exploit]]
- [[How to clean up files using FileDropper]]
- [[How to deprecate a Metasploit module]]
- [[How to do reporting or store data in module development]]
- [[How to log in Metasploit]]
- [[How to obfuscate JavaScript in Metasploit]]
- [[How to parse an HTTP response]]
- [[How to Send an HTTP Request Using HTTPClient]]
- [[How to send an HTTP request using Rex Proto Http Client]]
- [[How to use command stagers]]
- [[How to use datastore options]]
- [[How to use Msf Auxiliary AuthBrute to write a bruteforcer]]
- [[How to use PhpEXE to exploit an arbitrary file upload bug]]
- [[How to use Powershell in an exploit]]
- [[How to use Railgun for Windows post exploitation]]
- [[How to Use the FILEFORMAT mixin to create a file format exploit]]
- [[How to use the Msf Exploit Remote Tcp mixin]]
- [[How to use the Seh mixin to exploit an exception handler]]
- [[How to use WbemExec for a write privilege attack on Windows]]
- [[How to write a browser exploit using BrowserExploitServer]]
- [[How to write a browser exploit using HttpServer]]
- [[How to write a check method]]
- [[How to write a HTTP LoginScanner Module]]
- [[How to write a module using HttpServer and HttpClient]]
- [[How to zip files with Msf::Util::EXE.to_zip|./How-to-zip-files-with-Msf-Util-EXE-to_zip.md]]
- [[How to use Metasploit Framework Compiler Windows to compile C code]]
- [[How to use Metasploit Framework Obfuscation CRandomizer]]
- [[How to decrypt RC4 with Metasploit Framework Compiler]]
- [[How to decode Base64 with Metasploit Framework Compiler]]
- [[How to XOR with Metasploit Framework Compiler]]
- [[Using ReflectiveDll Injection]]
- [[Oracle Usage]]
- [[Definition of Module Reliability, Side Effects, and Stability|./Definition-of-Module-Reliability-Side-Effects-and-Stability.md]]
# Metasploit Payloads #
- [[How Payloads Work]]
- [[Merging Metasploit Payload Gem Updates]]
- [[Meterpreter Configuration]]
- [[Meterpreter HTTP Communication]]
- [[Meterpreter Paranoid Mode]]
- [[Meterpreter Reliable Network Communication]]
- [[Meterpreter Sleep Control]]
- [[Meterpreter Stageless Mode]]
- [[Meterpreter Timeout Control]]
- [[Meterpreter Transport Control]]
- [[Meterpreter Unicode Support]]
- [[Payload UUID]]
- [[Python Extension]]
- [[The ins and outs of HTTP and HTTPS communications in Meterpreter and Metasploit Stagers]]
# Other Metasploit Resources #
- [[Metasploit 5.0 Release Notes]]
- [[Downloads by Version]]
- [[Evading Anti Virus]]
- [[How to use a Metasploit module appropriately]]
- [[How to use a reverse shell in Metasploit]]
- [[Information About Unmet Browser Exploit Requirements]]
Payload modules are stored in `modules/payloads/{singles,stages,stagers}/<platform>`. When the framework starts up, stages are combined with stagers to create a complete payload that you can use in exploits. Then, handlers are paired with payloads so the framework will know how to create sessions with a given communications mechanism.
Payloads are given reference names that indicate all the pieces, like so:
This results in payloads like `windows/x64/meterpreter/reverse_tcp`. Breaking that down, the platform is `windows`, the architecture is `x64`, the final stage we're delivering is `meterpreter`, and the stager delivering it is `reverse_tcp`.
Note that architecture is optional because in some cases it is either unnecessary or implied. An example is `php/meterpreter/reverse_tcp`. Arch is unneeded for PHP payloads because we're delivering interpreted code rather than native.
### Singles
Single payloads are fire-and-forget. They can create a communications mechanism with Metasploit, but they don't have to. An example of a scenario where you might want a single is when the target has no network access -- a fileformat exploit delivered via USB key is still possible.
### Stagers
Stagers are a small stub designed to create some form of communication and then pass execution to the next stage. Using a stager solves two problems. First, it allows us to use a small payload initially to load up a larger payload with more functionality. Second, it makes it possible to separate the communications mechanism from the final stage so one payload can be used with multiple transports without duplicating code.
### Stages
Since the stager will have taken care of dealing with any size restrictions by allocating a big chunk of memory for us to run in, stages can be arbitrarily large. One advantage of that is the ability to write final-stage payloads in a higher-level language like C.
## Delivering stages
1. The IP address and port you want the payload to connect back to are embedded in the stager. As discussed above, all staged payloads are no more than a small stub that sets up communication and executes the next stage. When you create an executable using a staged payload, you're really just creating the stager. So the following commands would create functionally identical exe files:
**Note:** Final project proposals must be submitted through to Google through the GSoC Program Website, as stated in the [rules](https://summerofcode.withgoogle.com/rules/).
Before submitting to the GSoC website, it is also helpful to solicit proposal feedback. This can be done by reaching out to us on our Slack at <https://metasploit.com/slack> via the `#gsoc` channel, or via sending an email to `msfdev [@] metasploit [dot] com`. If you don't hear back right away on a proposal, don't give up! Contributors may be busy, or you may need to try again to get someone's attention (but don't spam).
# 2022 Timeline
An updated list of the application timeline can be found at https://developers.google.com/open-source/gsoc/timeline. Please refer to this link for any updates that Google may make, as they have been known to change the timeline for certain dates in the past.
## Important Dates
- GSoC Applications Open: April 4th at 1800 UTC
- GSoC Applications Close: April 19th at 1800 UTC for 2022 GSoC applications. **No late submissions will be accepted, period.**
- Accepted applications announced: May 20th at 1800 UTC
- Programming Starts: June 13th.
## Important Changes for 2022
- All submissions (including both draft submissions and final submissions) must be in PDF format when being submitted to GSoC's website. If you would like us to review your submission prior to the final deadline, please submit a Google Drive link to your DOC formatted proposal to msfdev [AT] metasploit [DOT] com and make sure that you have enabled commenting so that potential mentors can provide feedback.
# 2022 Idea List
You can find the current list of GSoC ideas at [[GSoC-2022-Project-Ideas]]. Please see the note at the bottom of this page if you are interested in submitting your own idea, as this will require approval.
# Getting started
Students interesting in GSoC, can start by reading Google's official guides.
Review all of the [student guide](https://google.github.io/gsocguides/student/) and carefully read the [proposal writing section](https://google.github.io/gsocguides/student/writing-a-proposal.html).
A listed `idea` is a seed for GSoC students to expand on and propose how to design and implement a solution. You can start by investigating the code base and how existing users interaction with `msfconsole` functionality. Think through scenarios on how a user might want to interact with the proposed idea.
A place to get started with contributing to Metasploit is [here](https://github.com/rapid7/metasploit-framework/blob/master/CONTRIBUTING.md) and expanded on [here](https://github.com/rapid7/metasploit-framework/wiki/Contributing-to-Metasploit#framework-bugs-and-features).
GSoC mentors tend to look for those items that have a chance of making development and usage easier or improving the overall performance of a certain area, however by starting with understanding the most common contribution patten you can get familiar with the codebase and also the mindset of users. This will help you in creating a proposal with the end user in mind.
Once you have started digging feel free ask questions that help you understand the concepts you for the idea would like to propose.
Initial proposals can be sent for feedback before official submission opens to msfdev@metasploit.com. All proposals must be officially submitted during Student Application Period through the [GSoC official](https://g.co/gsoc) site.
At a bare minimum, proposals should include the following:
## Title
A brief description of what you would like to work on. See [[GSoC-2022-Project-Ideas]] for ideas.
## Vitals
* Your name
* Contact info - include at least:
- an email address
- github user name
- Freenode nick/Slack nick
## Skillz
What programming languages are you familiar with, in order of proficiency? Most of Metasploit is written in Ruby; for any project you will most likely need at least a passing knowledge of it. If you want to work on Meterpreter or Mettle, C will be necessary as well.
What other projects have you worked on before?
## Your project
Fill in the details. What exactly do you want to accomplish?
# Past Submissions
If you are interested in looking at past accepted submissions and projects, you can find them at https://summerofcode.withgoogle.com/archive, and clicking on any year from 2017 onwards (with the exception of 2019 as Metasploit did not participate this year). Then click on the `Security` tag, and search for `Metasploit`. Scroll down to the bottom and you will see past successful applications and the associated code for each successful submission. Submissions from 2020 onwards also include copies of the proposal that was sent in by the accepted contributor.
The [HttpClient mixin](https://rapid7.github.io/metasploit-framework/api/Msf/Exploit/Remote/HttpClient) can be included with an exploit module in order to facilitate easier HTTP communications with a target machine.
## There are mainly two common methods you will see:
* **[send\_request\_raw](https://rapid7.github.io/metasploit-framework/api/Msf/Exploit/Remote/HttpClient.html#send_request_raw-instance_method)** - You use this to send a raw HTTP request. Usually, you will want this method if you need something that violates the specification; in most other cases, you should prefer `send_request_cgi`. If you wish to learn about how this method works, look at the documentation for [`Rex::Proto::Http::Client#request_raw`](https://rapid7.github.io/metasploit-framework/api/Rex/Proto/Http/Client.html#request_raw-instance_method).
Here's a basic example of how to use `send_request_raw`:
```ruby
send_request_raw({'uri'=>'/index.php'})
```
* **[send\_request\_cgi](https://rapid7.github.io/metasploit-framework/api/Msf/Exploit/Remote/HttpClient.html#send_request_cgi-instance_method)** - You use this to send a more CGI-compatible HTTP request. If your request contains a query string (or POST data), then you should use this. If you wish to learn about how this method works, check out [`Rex::Proto::Http::Client#request_cgi`](https://rapid7.github.io/metasploit-framework/api/Rex/Proto/Http/Client.html#request_cgi-instance_method).
Here's a very basic example for `send_request_cgi`:
```ruby
send_request_cgi({
'method'=>'GET',
'uri'=>'/hello_world.php',
'vars_get'=>{
'param_1'=>'abc',
'param_2'=>'123'
}
})
```
**Please note**: `send_request_raw` and `send_request_cgi` will return a `nil` if there's a timeout, so please make sure to account for that condition when you handle the return value.
## Cookies & CookieJars
Part of send\_request\_cgi functionality is the ability to collect, edit, and send cookies via the HttpClient's `cookie_jar` variable, an instance of the [HttpCookieJar](https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/exploit/remote/http/http_cookie_jar.rb) class.
A HttpCookieJar is a collection of [HttpCookie](https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/exploit/remote/http/http_cookie.rb). The Jar can be populated manually with it's `add` method, or automatically via the `keep_cookies` option that can be passed to [send\_request\_cgi](https://github.com/rapid7/metasploit-framework/blob/92d981fff2b4a40324969fd1d1744219589b5fa3/lib/msf/core/exploit/remote/http_client.rb#L385).
If you need to clear the cookie jar (for instance, using a 2nd login), try:
```ruby
cookie_jar.clear
```
### `keep_cookies` option
Shown below is the request used to login to a gitlab account in the [gitlab\_file\_read\_rce exploit module](https://github.com/rapid7/metasploit-framework/blob/92d981fff2b4a40324969fd1d1744219589b5fa3/modules/exploits/multi/http/gitlab_file_read_rce.rb#L70)
```ruby
res=@http_client.send_request_cgi({
'method'=>'POST',
'uri'=>'/users/sign_in',
'keep_cookies'=>true,
'vars_post'=>{
'utf8'=>'✓',
'authenticity_token'=>csrf_token,
'user[login]'=>username,
'user[password]'=>password,
'user[remember_me]'=>0
}
})
```
The cookies returned by the server with a successful login need to be attached to all future requests, so `'keep_cookies' => true,` is used to add all returned cookies to the HttpClient CookieJar and attach them to all subsequent requests.
### `cookie` option
Shown below is the request used to login to a gitlab account in the [artical\_proxy\_auth\_bypass\_service\_cmds\_peform\_command\_injection module](https://github.com/rapid7/metasploit-framework/blob/92d981fff2b4a40324969fd1d1744219589b5fa3/modules/exploits/linux/http/artica_proxy_auth_bypass_service_cmds_peform_command_injection.rb#L115)
artical\_proxy\_auth\_bypass\_service\_cmds\_peform\_command\_injection requires a specific cookie header to be sent with a request in order to achieve RCE. By setting a string of the desired header as the value of the `cookie` option, that string is set as the cookie header without any changes, allowing the exploit to be carried out.
Any object passed to `cookie` that isn't an instance of HttpCookieJar will have `to_s` called on it. The result of `to_s` will be set as the cookie header of the http request. The contents of the HttpClient cookie\_jar is ignored **_only_** this request. Subsequent requests are unaffected.
----
Module authors can also pass an instance of `HttpCookieJar` with the `cookie` option:
The above code would create an identical cookie header to the one used in the previous example, save for a random ordering of the name value pairs. This shouldn't affect how the server would read the cookies, but it's still worth keeping in mind if you've somehow found a vuln reliant on the order of cookies in a header.
### expire_cookies
`send_request_cgi` will call `cleanup` on `cookie_jar` before iot is used to populate a request with cookies. `cleanup` will remove any expired cookies permenetly from the jar, affecting all future requests.
If this behaviour isn't deisred and an author would prefer to keep expired cookies in the jar, the `expire_cookies` option can be set to false:
Before you send a HTTP request, you will most likely have to do some URI parsing. This is a tricky task, because sometimes when you join paths, you may accidentally get double slashes, like this: "/test//index.php". Or for some reason you have a missing slash. These are really commonly made mistakes. So here's how you can handle it safely:
**1** - Register your default URI datastore option as 'TARGETURI':
Example:
```ruby
register_options(
[
OptString.new('TARGETURI',[true,'The base path to XXX application','/xxx_v1/'])
]
)
```
**2** - Load your TARGETURI with [`target_uri`](https://rapid7.github.io/metasploit-framework/api/Msf/Exploit/Remote/HttpClient.html#target_uri-instance_method), that way the URI input validation will kick in, and then you get a real `URI` object:
In this example, we'll just load the path:
```ruby
uri=target_uri.path
```
**3** - When you want to join another URI, always use [`normalize_uri`](https://rapid7.github.io/metasploit-framework/api/Msf/Exploit/Remote/HttpClient.html#normalize_uri-instance_method):
Example:
```ruby
# Returns: "/xxx_v1/admin/upload.php"
uri=normalize_uri(uri,'admin','upload.php')
```
**4** - When you're done normalizing the URI, you're ready to use `send_request_cgi` or `send_request_raw`
Please note: The `normalize_uri` method will always follow these rules:
1. The URI should always begin with a slash.
2. You will have to decide if you need the trailing slash or not.
3. There should be no double slashes.
## Full Example
```ruby
require'msf/core'
classMetasploitModule<Msf::Auxiliary
includeMsf::Exploit::Remote::HttpClient
definitialize(info={})
super(
update_info(
info,
'Name'=>'HttpClient Example',
'Description'=>%q{
Do a send_request_cgi()
},
'Author'=>['sinn3r'],
'License'=>MSF_LICENSE
)
)
register_options(
[
OptString.new('TARGETURI',[true,'The base path','/'])
]
)
end
defrun
uri=target_uri.path
res=send_request_cgi({
'method'=>'GET',
'uri'=>normalize_uri(uri,'admin','index.php'),
'vars_get'=>{
'p1'=>'This is param 1',
'p2'=>'This is param 2'
}
})
ifres&&res.code==200
print_good('I got a 200, awesome')
else
print_error('No 200, feeling blue')
end
end
end
```
## Working with Burp Suite
Burp Suite is a useful tool to examine or modify HTTPS traffic while developing a module using HttpClient. To do this:
1. Start Burp: ```java -jar burpsuite.jar```
2. In Burp, click on the Proxies tab, and then Options. Configure the proxy listener there. In this example, let's say we have a listener on port 6666.
3. Once the Burp listener is up, start msfconsole and load the module you're working on.
4. Enter: ```set Proxies HTTP:127.0.0.1:6666```
5. Go ahead and run the module, Burp should intercept the HTTPS traffic.
Note that Burp only supports HTTPS for HttpClient. This problem is only specific to Burp and Metasploit.
If you need to examine HTTP traffic for HttpClient, a workaround is adding the following method in your module. This will override HttpClient's send_request_* method, and return the modified output:
```ruby
defsend_request_cgi(opts)
res=super(opts)
putsres.request.to_s
puts
putsres.to_s
puts
puts
end
```
You can do the same for send_request_raw as well.
## Other Common questions:
**1 - Can I use ```vars_get``` and ```vars_post``` together?**
Yes. When you supply a hash to ```vars_get```, basically it means "put all this data in the query string". When you supply a hash to ```vars_post```, it means "put all this data in the body." All of them will be in the same request. You do need to make sure you're using ```send_request_cgi```, of course.
**2 - I can't use ```vars_get``` or ```vars_post``` due to some weird reason, what to do?**
Do mention about this problem in the code (as a comment). If you can't use ```vars_post```, you can try the ```data``` key instead, which will send your post data raw. Normally, the most common solution to get around ```vars_get``` is to leave your stuff in the ```uri``` key. msftidy will flag this, but only as an "Info" and not a warning, which means you should still pass msftidy anyway. If this is a common problem, we can always change msftidy.
**3 - Do I need to manually do basic auth?**
You do not need to manually do basic auth in your request, because HttpClient should automatically do that for you. All you have to do is set the username and password in the datastore options, and then the mixin will use that when the web server asks.
**4 - How do I send a MIME request?**
See [Rex::MIME::Message](https://github.com/rapid7/rex-mime/blob/master/lib/rex/mime/message.rb)
## References
* [[How to send an HTTP request using Rex Proto Http Client]]
```Msf::Exploit::FILEFORMAT``` is the mixin to use to create a file format exploit. There actually isn't much in the mixin, but the most important method is this: ```file_create```:
### Usage for file_create
As the name implies, the ```file_create``` method allows you to create a file. You should be using this method because it does more than just writing data to disk. One of the important things it does is it will report the file creation to the database in the format of ```#{ltype}.localpath```, and the file will always be written to Metasploit's local directory defined in ```Msf::Config.local_directory``` (by default this path is ```~/.msf4/local```), which keep files nice and organized.
To use the mixin, first include ```Msf::Exploit::FILEFORMAT``` under the scope of your ```Metasploit3``` class:
```ruby
include Msf::Exploit::FILEFORMAT
```
And here's an example of using ```file_create``` to build an imaginary exploit:
```ruby
# This is my imaginary exploit
buf = ""
buf << "A" * 1024
buf << [0x40201f01].pack("V")
buf << "\x90" * 10
buf << payload.encoded
file_create(buf)
```
### Custom filename
The ```Msf::Exploit::FILENAME``` mixin by default has a registered ```FILENAME``` datastore option, and it is actually optional. If there's no filename provided, the mixin will set the name in this format: ```"exploit.fileformat.#{self.shortname}"```, where ```self.shortname``` means the shorter version of the module name.
If you wish to set a default one (but still changeable by the user), then you simply register it again in the module, like this:
```ruby
register_options(
[
OptString.new('FILENAME', [true, 'The malicious file name', 'msf.jpg'])
], self.class)
```
### Fixed filename
Occasionally, you might not want your user to change the filename at all. A lazy trick to do that is by modifying the ```FILENAME``` datastore option at runtime, but this is very much not recommended. In fact, if you do this, you will not pass [msftidy](https://github.com/rapid7/metasploit-framework/wiki/Guidelines-for-Accepting-Modules-and-Enhancements#module-additions). Instead, here's how it's done properly:
1 - Deregister the ```FILENAME``` option
```ruby
deregister_options('FILENAME')
```
2 - Next, override the ```file_format_filename``` method, and make it return the filename you want:
```ruby
def file_format_filename
'something.jpg'
end
```
3 - Finally, please leave a note about this in the module description.
**Update:** We have automated this process (it runs every Thursday at noon US Central Time), and 99.9% of the time you will not need to follow any of the below steps. That said, if you need to update a gem in a PR, this is still a good procedure to follow.
Sometimes you might want to pull in a new Ruby library or update an existing one to get more functionality. Metasploit leverages [Bundler](http://bundler.io) to manage [Ruby gems](https://rubygems.org/) and make dependencies easy. This document goes over the things you need to know when updating or adding gems to Metasploit.
##### The Gemfile
Gems that are only *sometimes* used (say, only in test mode, or only when running with a database) are listed in a relevant Bundler group (`test` or `db` respectively) in the [root Gemfile](https://github.com/rapid7/metasploit-framework/blob/master/Gemfile).
##### The metasploit-framework.gemspec file
Gems that are *always needed* by Metasploit are kept in the [metasploit-framework.gemspec](https://github.com/rapid7/metasploit-framework/blob/master/metasploit-framework.gemspec) file (this file is actually pulled into the Gemfile when calculating dependencies).
##### The Lock File
The [Gemfile.lock file](https://github.com/rapid7/metasploit-framework/blob/master/Gemfile.lock) holds the absolute versions of the Gems we want and keeps track of all the subdependencies. You should never need to manually edit this file: bundler will do it for you when you run `bundle install` after adding a gem. We keep this committed in the repo to ensure that all users are always on the same gem versions.
##### Updating or adding a gem
If the gem is needed only for a specific Bundler group (like `test` or `db`), you should update the [Gemfile](https://github.com/rapid7/metasploit-framework/blob/master/Gemfile):
1. Add the Gem you want to the correct Group, or just update the version constraint. Check [Bundler's docs](http://bundler.io/gemfile.html) for the various ways to express version constraints:
gem 'my_favorite', '~> 1.0'
2. Run `bundle install`
3. Commit any changes to the `Gemfile.lock` file
If the gem is needed any time metasploit-framework is used, you should update the [metasploit-framework.gemspec](https://github.com/rapid7/metasploit-framework/blob/master/metasploit-framework.gemspec) file:
1. Add the gem as a runtime dependency, or just update the version constraint. Check [Bundler's docs](http://bundler.io/gemfile.html) for the various ways to express version constraints:
A Gemfile.local file is useful for adding temporary gems to the metasploit-framework, like pry-stack-explorer or other handy debugging libs; you don't want to commit these gems into the repo, but might need them from time to time. To use a Gemfile.local file:
1. Rename the [Gemfile.local.example](https://github.com/rapid7/metasploit-framework/blob/master/Gemfile.local.example) file in the repo root to `Gemfile.local`
2. Add the temporary gems you want to this file
3. Run `bundle install`
4. Make sure you _do not_ commit the Gemfile.lock: `git checkout -- Gemfile.lock`
Checking patch levels is an important task for vulnerability research or exploit development. As a bug-hunting kind of guy, you should care about patch levels because say you have an 0day for Internet Explorer 10, you can't always assume it affects all IE 10 builds since its debut (2012). If you realize your 0day only affects one or two builds, how much of a threat is it? Probably not as bad as you think.
If you're an exploit developer, you're checking patches for another reason: maximum reliability. There are a lot of ways your exploit can fail, a bad [gadget](https://en.wikipedia.org/wiki/Return-oriented_programming) due to a change by a system update is easily one of them. If this update occurred at a pretty early stage, chances are your exploit will fail a lot, too.
## How to collect Microsoft patches
If you're kind of hardcore with patch diffing, you probably maintain your own database of DLLs. But this may require a lot of disk space, for most people it's probably not worth it unless you have to look at these DLLs pretty much everyday. A more economic way is probably have a way to track all these patches, and have some sort of interface to allow quick and easy access to them.
Luckily, Microsoft maintains a list of all the patches in an Excel file that you can download here:
If you prefer some sort of GUI for searching, you can use Microsoft's [Security Update Guide](https://portal.msrc.microsoft.com/en-us/security-guidance). You can edit this dashboard to add specific filters, such as the Windows version, Internet Explorer version, Office, etc, etc.
For example, if I want to find all the Internet Explorer 10 patches for Windows 7 since its debut, I can add the following filters:
* Windows 7
* Internet Explorer
And then I sort by date from September 2012 to 2014, I get: 22 results. But of course, this number will go up because IE 10 is still supported.
There are also other desktop or command-line tools that will basically check missing patches for your Windows system, such as [Windows Update Powershell Module](https://gallery.technet.microsoft.com/scriptcenter/2d191bcd-3308-4edd-9de2-88dff796b0bc), in some cases this may work better.
## Patch extraction
* Old patches used to be packaged as EXEs, and this kind can be extracted by using decompression tools such as [7zip](https://www.7-zip.org/). Internet Explorer 6 patches, for example, can be extracted this way.
* Newer patches packaged as EXEs support the /X flag for extraction. For example, the following will extract the patch under the same directory. Patches such as Internet Explorer 8 (for XP) can be extracted this way.
```
Windows[Something]-KB[Something]-x86-ENU.exe /X:.
```
* Most patches nowadays are packaged as MSUs. Here's what you have to do:
1. Put all your *.msu files under the same directory (in Windows)
2. Run [tools/exploit/extract_msu.bat](https://github.com/rapid7/metasploit-framework/blob/master/tools/exploit/extract_msu.bat) [absolute directory path to *.msu files)
3. extract_msu.bat should automatically extract all the *.msu files. The "extracted" sub-directory in each new folder is where you can find the updated components.
Note: The update folders might be labeled as GDR or QRE. GDR indicates Generation Distribution Release, while QRE means Quick Fix Engineering.
## Checking gadgets in patches
The quickest way to check gadgets across different patches is by using Metasploit's msfpescan utility (or msfbinscan, which is smart enough to know it's PE format). It's really easy, all you have to do is put the DLLs in the same directory, and then do:
```
$ ./msfbinscan -D -a [address] -A 10 /patches/*.dll
```
What that does is the tool will disassemble all the DLLs under that directory, at that specific address for 10 bytes. You can probably automate a little more to quickly identify which DLLs don't have right gadget, and if that's the case for you, that means the gadget you're using is unsafe. You should find another one that's more reliable.
In some exploitation scenarios such as local privilege escalation, command execution, write privilege attacks, SQL Injections, etc, it is very likely that you have to upload one or more malicious files in order to gain control of the target machine. Well, a smart attacker shouldn't leave anything behind, so if a module needs to drop something onto the file system, it's important to remove it right after the purpose is served. And that is why we created the FileDropper mixin.
## Examples
The FileDropper mixin is a file manager that allows you to keep track of files, and then delete them when a session is created. To use it, first include the mixin:
```ruby
includeMsf::Exploit::FileDropper
```
Next, tell the FileDropper mixin where the file is going to be after a session is created by using the ```register_file_for_cleanup``` method. Each file name should either be a full path or relative to the current working directory of the session. For example, if I want to upload a payload to the target machine's remote path: ```C:\Windows\System32\payload.exe```, then my statement can be:
To compile, use [[How to use Metasploit::Framework::Compiler::Windows to compile C code|How to use Metasploit Framework Compiler Windows to compile C code]]
Metasploit has a very specific way to deprecate a module. To do so, you must be using the [Msf::Module::Deprecated](https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/deprecated.rb) mixin. The reason you must be using this mixin is because two things:
1. You are required to set a deprecation date. That way we know when to remove it, which is done manually.
2. You are optionally allowed to set a replacement of the module you wish to deprecate.
## Usage
To use the ```Msf::Module::Deprecated```, here's how:
1 - Under ```class MetasploitModule``` of your module, include the following:
```ruby
include Msf::Module::Deprecated
```
2a - When moving a module, use the ```moved_from``` method in the new module to add an alias to the old module name:
```ruby
moved_from 'auxiliary/analyze/jtr_windows_fast'
```
2b - Use the ```deprecated``` method to assign a deprecation date and replacement module:
* **store_loot()** - Used to store both stolen files (both text and binary) and "screencaps" of commands such as a ```ps -ef``` and ```ifconfig```. The file itself need not be of forensic-level integrity -- they may be parsed by a post module to extract only the relevant information for a penetration tester.
* **report_auth_info()** - Used to store working credentials that are immediately reusable by another module. For example, a module dumping the local SMB hashes would use this, as would a module which reads username:password combinations for a specific host and service. Specifically, merely "likely" usernames and passwords should use store_loot() instead.
* **report_vuln()** - Auxiliary and post modules that exercise a particular vulnerability should report_vuln() upon success. Note that exploit modules automatically report_vuln() as part of opening a session (there is no need to call it especially).
* **report_note()** - Modules should make an effort to avoid report_note() when one of the above methods would be a better fit, but there are often cases where "loot" or "cred" or "vuln" classifications are not immediately appropriate. report_note() calls should always set a OID-style dotted :type, such as domain.hosts, so other modules may easily find them in the database.
* **report_host()** - Reports a host's liveness and attributes such as operating system and service pack. This is less common because other reporting methods already do this, such as ```report_service```, ```report_exploit_success```, ```report_client```, ```report_note```, ```report_host_tag```, ```report_vuln```, ```report_event```, ```report_loot```, etc. Try not to repeat it.
* **report_service()** - Reports a new service (port) that's been detected by your module.
* **report_client()** - Reports a client running a host, such as a web browser.
* **report_web_site()** - Reports a website, and must be tied to an existing ```:service```. If there is no ```:service```, you will have to supply ```:host```, ```:port```, ```:ssl```.
* **report_web_page()** - You can use this if your module discovers a webpage that look interesting.
* **report_web_form()** - You can use this if your module discovers web forms that look interesting.
* **report_web_vuln()** - Reports a web application vulnerability. Exploits don't really need to use this. It's more suitable for auxiliary modules that exploit a bug that determines that it is vulnerable.
* **report_loot()** - Very rarely, modules might actually want to export loots without using store_loot(). Typically they do this with Ruby's file IO, but this won't be logged in the database so can't be tracked by Metasploit Framework. In that case, a ```report_loot()``` is needed. However, 99.9% of the time you should be using ```store_loot()```.
### References
- [[Guidelines for Accepting Modules and Enhancements]]
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Grant Willcox