Metasploit Framework: what the repository ships and how you run it

What you get when you clone the repository

rapid7/metasploit-framework is written in Ruby and is not archived; its last push was on 2026-09-28. The README describes it in one line as an open-source tool released under a BSD-style license and then sends readers to docs.metasploit.com for everything else, so the repository itself is the better guide to what the project is.

The top level makes the shape clear. A modules/ directory holds the module tree, and the executables sit beside it as plain files: msfconsole, msfvenom, msfd, msfdb, msfrpc, msfrpcd, msfupdate and msfmcpd. Two Rack entry points, msf-json-rpc.ru and msf-ws.ru, expose the framework over JSON-RPC and a websocket service. Around those are the parts you would expect of a large Ruby codebase: app/, lib/, config/, data/, db/, plugins/, external/, script/ and scripts/, with spec/ and test/ for the suites.

Packaging and deployment are committed too. There is a Dockerfile, a docker-compose.yml with a docker-compose.override.yml beside it, a docker/ directory, a kubernetes/ directory and a Vagrantfile. The Ruby toolchain is pinned through .ruby-version and .ruby-gemset, with Gemfile, Gemfile.lock and metasploit-framework.gemspec defining dependencies.

The four install paths, and which one the project prefers

The README is explicit about its preference: use the official Metasploit installers on Linux or macOS, which it links from its Nightly Installers page. The second path is to take the version that ships pre-installed with Kali. The third is a manual setup, which the README does not describe inline; it points to the Development Setup Guide for that.

The fourth path is not in the README's install section but is sitting in the repository: the committed Docker setup. That distinction matters when you are choosing, because the documented paths give you a packaged build while the Docker files give you a container pair you run yourself.

Worth noting before you start: the repository publishes no GitHub releases. There is no tagged version to pin, no release notes to read, and no checksum list on a releases page. Whatever you install comes from the installer page, the Kali package, or a build you make from the source you cloned. For anyone with a policy of pinning security tooling to signed, versioned artifacts, that is the first thing to resolve.

Reading the Docker setup before you run it

The committed docker-compose.yml defines two services. The framework runs from a published image and talks to a Postgres container:

services:
  ms:
    image: metasploitframework/metasploit-framework:latest
    environment:
      DATABASE_URL: postgres://postgres@db:5432/msf?pool=200&timeout=5
    links:
      - db
    ports:
      - 4444:4444
    volumes:
      - $HOME/.msf4:/home/msf/.msf4

Three details in those eight lines are worth reading carefully. The image tag is latest, so what you get depends on when you pull. Port 4444 is published to the host. And your $HOME/.msf4 directory is mounted into the container, which means the container writes to your real home directory rather than to disposable storage.

The database service is configured for convenience rather than for exposure:

  db:
    image: postgres:10-alpine
    environment:
      POSTGRES_HOST_AUTH_METHOD: trust

POSTGRES_HOST_AUTH_METHOD set to trust means the database accepts connections without a password. That is workable on an isolated Docker network and a bad idea anywhere the port is reachable. The Postgres image is also pinned to the 10 series, which is well behind current Postgres. Neither point makes the setup wrong for a lab, but both are things to change before this goes anywhere shared.

The Dockerfile builds from ruby:3.3.8-alpine3.21, carries LABEL maintainer="Rapid7", installs a long list of Alpine build dependencies through apk, and then builds Go 1.24.0 from source with GO111MODULE=off. That last step is why a local image build takes a while.

Starting it, and where the documentation actually lives

Once installed, the README gives one instruction for getting going: start msfconsole, which it names as the primary interface for interacting with Metasploit. Everything past that first command lives on the documentation site rather than in the repository README.

That split is worth planning around. docs.metasploit.com carries the usage guides, the getting-started material and the API documentation for writing modules. The repository holds documentation/ and docs/ directories, plus AGENTS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and a CURRENT.md at the top level. If you are working offline or auditing what you have, the repository directories are what you have to hand; the guides a newcomer needs are on the website.

The licence is not what GitHub reports

GitHub's licence detection returned NOASSERTION for this repository, which is what you see in its metadata. The README states something different: it says the framework is released under a BSD-style license and directs readers to the COPYING file for detailed licensing information.

Both files are present at the top level, COPYING and LICENSE, and there is a separate LICENSE_GEMS. That third file matters for anyone doing a compliance review, because a Ruby project of this size pulls in gems under their own terms, and Gemfile.lock records exactly which ones. If you need a licence answer you can defend, read COPYING and LICENSE_GEMS directly rather than relying on the summary GitHub shows.

Maintenance signals and how support is organised

The last push landed on 2026-09-28, so this is a repository under current development rather than one you are adopting after it went quiet. The support channels have been reorganised, and the README says so plainly: GitHub Discussions for community questions, a Metasploit Slack for real-time chat, and GitHub Issues for bugs and feature requests, with a MSF-BUGv1 form for new submissions. Updates are posted on X and on Mastodon.

The README also notes that some community members still use IRC channels and the metasploit-hackers mailing list, while stating that Discussions and Slack are now the primary channels. If you find advice pointing you at IRC, treat it as older material.

Contribution is a three-step path in the README: set up a development environment following the Development Setup Guide, clone the repository, then submit a pull request, with further detail in CONTRIBUTING.md. The repository backs that with the tooling you would expect for a project taking outside patches: .rubocop.yml for style, .rspec and .simplecov for tests and coverage, .snyk and .gitleaksignore for dependency and secret scanning, and .solargraph.yml and .yardopts for editor support and documentation generation.

Where it sits against other security tooling

Metasploit Framework is a module-driven framework with its own console, its own database and its own RPC surface. Nmap sits in a different place in a workflow: it is a network scanner, built to map hosts, ports and services, and it does not carry an exploitation module tree. Burp Suite is different again, focused on intercepting and manipulating web application traffic from a graphical proxy. Choosing between them is not really a comparison of quality; they answer different questions, and the framework here is the one with the module and payload tooling in the tree.

The practical caution with this repository is the same one its own structure suggests. The README is a directory of links rather than a manual, the project ships no releases, and the Docker setup committed here is configured for a lab with a trust-authentication database on an old Postgres series. Read COPYING for the licence, read docker-compose.yml before you bring it up, and get your usage answers from docs.metasploit.com.

Editorial conclusion

Use this repository if you want the framework from source, a container pair you control, or a base to write modules against; the API documentation for module authors is on the documentation site. Do not expect it to teach you the tool: the README is a set of links, and the usage guides live at docs.metasploit.com. Verify three things first: read COPYING and LICENSE_GEMS rather than trusting the NOASSERTION licence field, decide how you will pin a build given that there are no GitHub releases, and change the Postgres trust authentication and the latest image tag in docker-compose.yml before running it anywhere that is not isolated.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository