ronin-listener 0.1.0.rc1

data/gemspec.yml

@@ -0,0 +1,39 @@
+name: ronin-listener
+summary: A Ruby CLI utility for receiving exfiltrated data.
+description: |
+  ronin-listener is a small CLI utility for receiving exfiltrated data over DNS
+  or HTTP.
+
+license: LGPL-3.0
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://ronin-rb.dev/
+has_yard: true
+
+metadata:
+  documentation_uri: https://ronin-rb.dev/docs/ronin-listener
+  source_code_uri:   https://github.com/ronin-rb/ronin-listener
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-listener/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-listener/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+generated_files:
+ - data/completions/ronin-listener
+ - man/ronin-listener.1
+ - man/ronin-listener-completion.1
+ - man/ronin-listener-dns.1
+ - man/ronin-listener-http.1
+ - man/ronin-listener-new.1
+ - man/ronin-listener-new-dns.1
+ - man/ronin-listener-new-http.1
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  # Ronin dependencies:
+  ronin-listener-dns: ~> 0.1.0.rc1
+  ronin-listener-http: ~> 0.1.0.rc1
+  ronin-core: ~> 0.2.0.rc1
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/ronin/listener/cli/command.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/root'
+
+require 'ronin/core/cli/command'
+
+module Ronin
+  module Listener
+    class CLI
+      #
+      # Base command for all `ronin-listener` commands.
+      #
+      class Command < Core::CLI::Command
+
+        man_dir File.join(ROOT,'man')
+
+        bug_report_url 'https://github.com/ronin-rb/ronin-listener/issues/new'
+
+      end
+    end
+  end
+end

data/lib/ronin/listener/cli/commands/completion.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/root'
+require 'ronin/core/cli/completion_command'
+
+module Ronin
+  module Listener
+    class CLI
+      module Commands
+        #
+        # Manages the shell completion rules for `ronin-listener`.
+        #
+        # ## Usage
+        #
+        #     ronin-listener completion [options]
+        #
+        # ## Options
+        #
+        #         --print                      Prints the shell completion file
+        #         --install                    Installs the shell completion file
+        #         --uninstall                  Uninstalls the shell completion file
+        #     -h, --help                       Print help information
+        #
+        # ## Examples
+        #
+        #     ronin-listener completion --print
+        #     ronin-listener completion --install
+        #     ronin-listener completion --uninstall
+        #
+        class Completion < Core::CLI::CompletionCommand
+
+          completion_file File.join(ROOT,'data','completions','ronin-listener')
+
+          man_dir File.join(ROOT,'man')
+          man_page 'ronin-listener-completion.1'
+
+          description 'Manages the shell completion rules for ronin-listener'
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/listener/cli/commands/dns.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/cli/command'
+require 'ronin/listener/output_formats'
+require 'ronin/listener/dns'
+
+require 'ronin/core/cli/logging'
+
+module Ronin
+  module Listener
+    class CLI
+      module Commands
+        #
+        # Starts a DNS server for receiving exfiltrated data.
+        #
+        # ## Usage
+        #
+        #     ronin-listener dns [options] DOMAIN
+        #
+        # ## Options
+        #
+        #     -o, --output FILE                The output file to write DNS queries to
+        #     -F, --output-format txt|csv|json|ndjson
+        #                                      The output format
+        #     -H, --host IP                    The interface to listen on (Default: 0.0.0.0)
+        #     -p, --port PORT                  The port to listen on (Default: 53)
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     DOMAIN                           The domain to receive queries for
+        #
+        # ## Examples
+        #
+        #     ronin-listener dns -H 127.0.0.1 -p 5553 example.com
+        #
+        class Dns < Command
+
+          include Core::CLI::Logging
+
+          usage '[options] DOMAIN'
+
+          option :output, short: '-o',
+                          value: {
+                            type:  String,
+                            usage: 'FILE'
+                          },
+                          desc: 'The output file to write DNS queries to' do |path|
+                            options[:output]          = path
+                            options[:output_format] ||= OutputFormats.infer_from(path)
+                          end
+
+          option :output_format, short: '-F',
+                                 value: {
+                                   type: OutputFormats.formats
+                                 },
+                                 desc: 'The output format'
+
+          option :host, short: '-H',
+                        value: {
+                          type:    String,
+                          usage:   'IP',
+                          default: '0.0.0.0'
+                        },
+                        desc: 'The interface to listen on'
+
+          option :port, short: '-p',
+                        value: {
+                          type:    Integer,
+                          usage:   'PORT',
+                          default: 53
+                        },
+                        desc: 'The port to listen on'
+
+          argument :domain, required: true,
+                            desc:     'The domain to receive queries for'
+
+          description 'Starts a DNS server for receiving exfiltrated data'
+
+          examples [
+            '-H 127.0.0.1 -p 5553 example.com'
+          ]
+
+          man_page 'ronin-listener-dns.1'
+
+          #
+          # Runs the `ronin-listener dns` command.
+          #
+          # @param [String] domain
+          #   The `DOMAIN` argument.
+          #
+          def run(domain)
+            output_file = if options[:output] && options[:output_format]
+                            options[:output_format].open(options[:output])
+                          end
+
+            Ronin::Listener::DNS.listen(domain,**proxy_kwargs) do |query|
+              log_info "Received DNS query: #{query.type} #{query.label} from #{query.source}"
+              output_file << query if output_file
+            end
+          end
+
+          #
+          # Maps options to keyword arguments for `Ronin::Listener::DNS.listen`.
+          #
+          # @return [Hash{Symbol => Object}]
+          #
+          def proxy_kwargs
+            {
+              host: options[:host],
+              port: options[:port]
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/listener/cli/commands/http.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/cli/command'
+require 'ronin/listener/output_formats'
+require 'ronin/listener/http'
+
+require 'ronin/core/cli/logging'
+
+module Ronin
+  module Listener
+    class CLI
+      module Commands
+        #
+        # Starts a HTTP server for receiving exfiltrated data.
+        #
+        # ## Usage
+        #
+        #     ronin-listener http [options]
+        #
+        # ## Options
+        #
+        #     -o, --output FILE                The output file to write HTTP requests to
+        #     -F, --output-format txt|csv|json|ndjson
+        #                                      The output format
+        #     -H, --host IP                    The interface to listen on (Default: 0.0.0.0)
+        #     -p, --port PORT                  The port to listen on (Default: 8080)
+        #         --vhost HOST                 The Host: header to filter requests by
+        #     -R, --root DIR                   The root directory to filter requests by (Default: /)
+        #     -h, --help                       Print help information
+        #
+        # ## Examples
+        #
+        #     ronin-listener http -H 127.0.0.1 -p 8080
+        #     ronin-listener http -H 127.0.0.1 -p 8080 --vhost example.com
+        #
+        class Http < Command
+
+          include Core::CLI::Logging
+
+          usage '[options]'
+
+          option :output, short: '-o',
+                          value: {
+                            type:  String,
+                            usage: 'FILE'
+                          },
+                          desc: 'The output file to write HTTP requests to' do |path|
+                            options[:output]          = path
+                            options[:output_format] ||= OutputFormats.infer_from(path)
+                          end
+
+          option :output_format, short: '-F',
+                                 value: {
+                                   type: OutputFormats.formats
+                                 },
+                                 desc: 'The output format'
+
+          option :host, short: '-H',
+                        value: {
+                          type:    String,
+                          usage:   'IP',
+                          default: '0.0.0.0'
+                        },
+                        desc: 'The interface to listen on'
+
+          option :port, short: '-p',
+                        value: {
+                          type:    Integer,
+                          usage:   'PORT',
+                          default: 8080
+                        },
+                        desc: 'The port to listen on'
+
+          option :vhost, value: {
+                           type:  String,
+                           usage: 'HOST'
+                         },
+                         desc: 'The Host: header to filter requests by'
+
+          option :root, short: '-R',
+                        value: {
+                          type:    String,
+                          usage:   'DIR',
+                          default: '/'
+                        },
+                        desc: 'The root directory to filter requests by'
+
+          description 'Starts a HTTP server for receiving exfiltrated data'
+
+          examples [
+            '-H 127.0.0.1 -p 8080',
+            '-H 127.0.0.1 -p 8080 --vhost example.com'
+          ]
+
+          man_page 'ronin-listener-http.1'
+
+          #
+          # Runs the `ronin-listener http` command.
+          #
+          def run
+            output_file = if options[:output] && options[:output_format]
+                            options[:output_format].open(options[:output])
+                          end
+
+            Ronin::Listener::HTTP.listen(**server_kwargs) do |request|
+              remote_addr = request.remote_address
+
+              log_info "Received HTTP request from #{remote_addr.ip_address}:#{remote_addr.ip_port} ..."
+
+              puts "#{request.method} #{request.path}"
+
+              request.headers.each do |name,value|
+                puts "#{name}: #{value}"
+              end
+
+              puts request.body if request.body
+              puts
+
+              output_file << request if output_file
+            end
+          end
+
+          #
+          # Maps options to keyword arguments for `Ronin::Listener::HTTP.listen`.
+          #
+          # @return [Hash{Symbol => Object}]
+          #
+          def server_kwargs
+            {
+              host:  options[:host],
+              port:  options[:port],
+              vhost: options[:vhost],
+              root:  options[:root]
+            }
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/listener/cli/commands/new/dns.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/cli/command'
+require 'ronin/core/cli/generator'
+require 'ronin/listener/root'
+
+module Ronin
+  module Listener
+    class CLI
+      module Commands
+        class New < Command
+          #
+          # Creates a new standalone DNS listener Ruby script.
+          #
+          # ## Usage
+          #
+          #     ronin-listener new dns PATH
+          #
+          # ## Options
+          #
+          #     -H, --host IP                    The interface to listen on (Default: 0.0.0.0)
+          #     -p, --port PORT                  The port to listen on (Default: 5553)
+          #         --domain DOMAIN              The domain to receive queries for (Default: example.com)
+          #     -h, --help                       Print help information
+          #
+          # ## Arguments
+          #
+          #     PATH                             The script file to create
+          #
+          class Dns < Command
+
+            include Core::CLI::Generator
+
+            template_dir File.join(ROOT,'data','new')
+
+            usage '[options] PATH'
+
+            option :host, short: '-H',
+                          value: {
+                            type:    String,
+                            usage:   'IP',
+                            default: '0.0.0.0'
+                          },
+                          desc: 'The interface to listen on' do |host|
+                            @host = host
+                          end
+
+            option :port, short: '-p',
+                          value: {
+                            type:    Integer,
+                            usage:   'PORT',
+                            default: 5553
+                          },
+                          desc: 'The port to listen on' do |port|
+                            @port = port
+                          end
+
+            option :domain, short: '-d',
+                            value: {
+                              type:    String,
+                              usage:   'DOMAIN',
+                              default: 'example.com'
+                            },
+                            desc: 'The domain to receive queries for' do |domain|
+                              @domain = domain
+                            end
+
+            argument :path, required: true,
+                            desc:     'The script file to create'
+
+            description 'Creates a new standalone DNS listener Ruby script'
+
+            man_page 'ronin-listener-new-dns.1'
+
+            #
+            # Initializes the `ronin-listener new dns` command.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments for the command.
+            #
+            def initialize(**kwargs)
+              super(**kwargs)
+
+              @host   = '0.0.0.0'
+              @port   = 5553
+              @domain = 'example.com'
+            end
+
+            #
+            # Runs the `ronin-listener new dns` command.
+            #
+            # @param [String] path
+            #   The path to the new script file to create.
+            #
+            def run(path)
+              erb 'dns.rb.erb', path
+              chmod '+x', path
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/listener/cli/commands/new/http.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+#
+# ronin-listener - A Ruby CLI utility for receiving exfiltrated data.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-listener is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-listener is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-listener.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/listener/cli/command'
+require 'ronin/core/cli/generator'
+require 'ronin/listener/root'
+
+module Ronin
+  module Listener
+    class CLI
+      module Commands
+        class New < Command
+          #
+          # Creates a new standalone HTTP listener Ruby script.
+          #
+          # ## Usage
+          #
+          #     ronin-listener new http PATH
+          #
+          # ## Options
+          #
+          #     -H, --host IP                    The interface to listen on (Default: 0.0.0.0)
+          #     -p, --port PORT                  The port to listen on (Default: 8080)
+          #         --vhost HOST                 The Host: header to filter requests by
+          #     -R, --root DIR                   The root directory to filter requests by
+          #     -h, --help                       Print help information
+          #
+          # ## Arguments
+          #
+          #     PATH                             The script file to create
+          #
+          class Http < Command
+
+            include Core::CLI::Generator
+
+            template_dir File.join(ROOT,'data','new')
+
+            usage '[options] PATH'
+
+            option :host, short: '-H',
+                          value: {
+                            type:    String,
+                            usage:   'IP',
+                            default: '0.0.0.0'
+                          },
+                          desc: 'The interface to listen on' do |host|
+                            @host = host
+                          end
+
+            option :port, short: '-p',
+                          value: {
+                            type:    Integer,
+                            usage:   'PORT',
+                            default: 8080
+                          },
+                          desc: 'The port to listen on' do |port|
+                            @port = port
+                          end
+
+            option :vhost, value: {
+                             type:  String,
+                             usage: 'HOST'
+                           },
+                           desc: 'The Host: header to filter requests by' do |vhost|
+                             @vhost = vhost
+                           end
+
+            option :root, short: '-R',
+                          value: {
+                            type:  String,
+                            usage: 'DIR'
+                          },
+                          desc: 'The root directory to filter requests by' do |root|
+                            @root = root
+                          end
+
+            argument :path, required: true,
+                            desc:     'The script file to create'
+
+            description 'Creates a new standalone HTTP listener Ruby script'
+
+            man_page 'ronin-listener-new-http.1'
+
+            #
+            # Initializes the `ronin-listener new http` command.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments for the command.
+            #
+            def initialize(**kwargs)
+              super(**kwargs)
+
+              @host = '0.0.0.0'
+              @port = 5553
+            end
+
+            #
+            # Runs the `ronin-listener new http` command.
+            #
+            # @param [String] path
+            #   The path to the new script file to create.
+            #
+            def run(path)
+              erb 'http.rb.erb', path
+              chmod '+x', path
+            end
+
+          end
+        end
+      end
+    end
+  end
+end