How to add and update gems in metasploit framework

Sometimes you might want to pull in a new Ruby library or update an existing one to get more functionality. Here's how to do it.

Metasploit leverages Ruby gems to make dependencies easy. Gems that are only sometimes used (say, only in test mode, or only when running with a database) are listed in the root Gemfile. Gems that are always needed by Metasploit are kept in the metasploit-framework.gemspec file (this file is actually pulled into the Gemfile).

The Lock File

The Gemfile.lock file 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. 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:

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 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:

        spec.add_runtime_dependency 'my_favorite_gem', '~> 3.0.1'

2. Run `bundle install`
3. Commit any changes to the `Gemfile.lock` file.

Gemfile.local

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 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