{"id":20445839,"url":"https://github.com/rapid7/mettle","last_synced_at":"2025-05-15T12:05:18.085Z","repository":{"id":28047376,"uuid":"31543393","full_name":"rapid7/mettle","owner":"rapid7","description":"This is an implementation of a native-code Meterpreter, designed for portability, embeddability, and low resource utilization.","archived":false,"fork":false,"pushed_at":"2025-03-27T20:10:08.000Z","size":79592,"stargazers_count":440,"open_issues_count":27,"forks_count":124,"subscribers_count":80,"default_branch":"master","last_synced_at":"2025-04-14T22:18:34.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rapid7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-03-02T14:14:41.000Z","updated_at":"2025-03-28T11:29:23.000Z","dependencies_parsed_at":"2023-10-02T21:14:01.263Z","dependency_job_id":"dd3bef64-4c1c-49a5-ae2e-2df8645ad1cd","html_url":"https://github.com/rapid7/mettle","commit_stats":null,"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmettle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmettle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmettle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmettle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapid7","download_url":"https://codeload.github.com/rapid7/mettle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T10:14:38.507Z","updated_at":"2025-05-15T12:05:13.056Z","avatar_url":"https://github.com/rapid7.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Mettle\n======\n\nThis is an implementation of a native-code Meterpreter, designed for\nportability, embeddability, and low resource utilization. It can run on the\nsmallest embedded Linux targets to big iron, and targets Android, iOS, macOS,\nLinux, and Windows, but can be ported to almost any POSIX-compliant\nenvironment.\n\nBuilding on Linux\n------------\n\nDebain, Ubuntu, and derivatives are most supported for builds. To build, you need at least 5GB of free disk space, and the following packages available:\n\n```\n# Dependencies\napt install curl build-essential git autoconf automake libtool bison flex gcc ruby rake bundler git mingw-w64\n```\n\nThe Dockerfile under docker/Dockerfile contains a pre-configured build\nenvironment as well.\n\nBuilding on macOS\n------------\n\nOn macOS you will need to install the xcode command line tools as follows:\n\n```\nxcode-select --install\n```\n\nMake Targets\n------------\n\nFor general development, there are a few make targets defined:\n\nRunning `make` will build for the local environment. E.g. if you're on macOS,\nit will build for macOS using your native compiler and tools.\n\n`make TARGET=triple` will build for a specific host triple. See below for some\ncommon ones.\n\n`make clean` will clean the 'mettle' directory for the current build target\n\n`make distclean` will clean the entire build target`\n\n`make all-parallel` will build for every known target, useful with '-j' to build multiple targets at once.\n\n`make clean-parallel` and `make distclean-parallel` do similar for all targets.\n\nPackaging\n=========\n\nTo build the gem for distribution (currently requires Linux or macOS):\n\n```\nrake build\n```\n\nTo check the resulting binaries:\n\n```\nrake check\n```\n\nTo completely reset your dev environment and delete all binary artifacts:\n\n```\nrake mettle:ultraclean\n```\n\nGem API\n-------\n\nTo generate a payload with Mettle:\n```ruby\nmettle = MetasploitPayloads::Mettle.new(platform_triple, config={})\n```\n\nThe available platform triples for Linux targets are:\n\n* `aarch64-linux-musl`\n* `armv5l-linux-musleabi`\n* `armv5b-linux-musleabi`\n* `i486-linux-musl`\n* `x86_64-linux-musl`\n* `powerpc-linux-muslsf`\n* `powerpc64le-linux-musl`\n* `mips-linux-muslsf`\n* `mipsel-linux-muslsf`\n* `mips64-linux-muslsf`\n* `s390x-linux-musl`\n\nFor Mingw32-64 Windows targets, the following triples are added. On up-to-date\nDebian / Ubuntu systems, the `mingw-w64` package will install both toolchains.\n\n* `x86_64-w64-mingw32`\n* `i686-w64-mingw32`\n\nFor macOS/iOS builds, the following triples are added. To target older macOS/OSX\nversions, see https://github.com/phracker/MacOSX-SDKs to get the appropriate\nSDK folder.\n\n* `arm-iphone-darwin`\n* `aarch64-iphone-darwin`\n* `i386-apple-darwin`\n* `x86_64-apple-darwin`\n* `aarch64-apple-darwin`\n\nAvailable config options are:\n* `:background` - fork to background as a daemon\n* `:debug` - to turn on debug messages\n* `:log_file` - the file to send debug messages to instead of `stderr`\n* `:uri` - the uri to connect back to\n* `:uuid` - the UUID to identify the payload\n\nConfig options can also be set with:\n```ruby\nmettle.config[:key] = val\n```\n\nTo get a binary with installed options call:\n```ruby\nmettle.to_binary(format=:process_image)\n```\n\nThe formats are:\n* `:exec` - a standalone executable that can take command-line arguments (see `mettle -h`) or use pre-set ones\n* `:process_image` - a process image that must be started with a custom stack (see `doc/stack_requirements.md`)\n\n\nUsing with Metasploit\n---------------------\n\nTo pull your local changes of mettle into your Metasploit install:\n\n1. Add `-dev` to the version in `lib/metasploit_payloads/mettle/version.rb`\n2. Build the gem as above\n3. Copy `pkg/metasploit-payloads-mettle-X.X.X.pre.dev.gem` to the box you are using for Metasploit if it is different\n4. Change the version in your metasploit-framework.gemspec to match the one you just built\n5. `gem install \u003cpath to new gem\u003e` (for example: 'metasploit_payloads-mettle', '0.4.1.pre.dev')\n6. Run `bundle install` in your Framework directory, and ensure you see something like `Using metasploit_payloads-mettle 0.4.1.pre.dev (was 0.4.1)` in the output\n7. Congrats, you are now done!\n\nPushing out a New Gem\n----------------------\nBuild CI will automatically publish new gems when commits land to master and pass build.\n1. Test Locally\n2. Land the changes to upstream master\n3. Monitor for the new gem on rubygems.org\n4. Once the gem appears, make a PR for bumping the version in framework\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fmettle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapid7%2Fmettle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fmettle/lists"}