Add Kademlia scanner, lands rapid7#4210

Author: HD Moore

lib/msf/core/auxiliary/kademlia.rb

@@ -0,0 +1,15 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia'
+
+module Msf
+
+###
+#
+# This module provides methods for working with Kademlia
+#
+###
+module Auxiliary::Kademlia
+  include Rex::Proto::Kademlia
+end
+end

lib/msf/core/auxiliary/mixins.rb

@@ -19,6 +19,7 @@
 require 'msf/core/auxiliary/login'
 require 'msf/core/auxiliary/rservices'
 require 'msf/core/auxiliary/cisco'
+require 'msf/core/auxiliary/kademlia'
 require 'msf/core/auxiliary/nmap'
 require 'msf/core/auxiliary/natpmp'
 require 'msf/core/auxiliary/iax2'

lib/rex/proto/kademlia.rb

@@ -0,0 +1,8 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia/bootstrap_request'
+require 'rex/proto/kademlia/bootstrap_response'
+require 'rex/proto/kademlia/message'
+require 'rex/proto/kademlia/ping'
+require 'rex/proto/kademlia/pong'
+require 'rex/proto/kademlia/util'

lib/rex/proto/kademlia/bootstrap_request.rb

@@ -0,0 +1,19 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia/message'
+
+module Rex
+module Proto
+module Kademlia
+  # Opcode for a BOOTSTRAP request
+  BOOTSTRAP_REQUEST = 0x01
+
+  # A Kademlia bootstrap request message
+  class BootstrapRequest < Message
+    def initialize
+      super(BOOTSTRAP_REQUEST)
+    end
+  end
+end
+end
+end

lib/rex/proto/kademlia/bootstrap_response.rb

@@ -0,0 +1,79 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia/message'
+require 'rex/proto/kademlia/util'
+
+module Rex
+module Proto
+module Kademlia
+  # Opcode for a bootstrap response
+  BOOTSTRAP_RESPONSE = 0x09
+
+  # A Kademlia bootstrap response message
+  class BootstrapResponse < Message
+    # @return [String] the ID of the peer that send the bootstrap response
+    attr_reader :peer_id
+    # @return [Integer] the TCP port that the responding peer is listening on
+    attr_reader :tcp_port
+    # @return [Integer] the version of this peer
+    attr_reader :version
+    # @return [Array<Hash<String, Object>>] the peer ID, IP address, UDP/TCP ports and version of each peer
+    attr_reader :peers
+
+    # Constructs a new bootstrap response
+    #
+    # @param peer_id [String] the ID of this peer
+    # @param tcp_port [Integer] the TCP port that this peer is listening on
+    # @param version [Integer] the version of this peer
+    # @param peers [Array<Hash<String, Object>>] the peer ID, IP address, UDP/TCP ports and version of each peer
+    def initialize(peer_id, tcp_port, version, peers)
+      @peer_id = peer_id
+      @tcp_port = tcp_port
+      @version = version
+      @peers = peers
+    end
+
+    # The minimum size of a peer in a KADEMLIA2_BOOTSTRAP_RES message:
+    # peer ID (16-bytes), IP (4 bytes), UDP port (2 bytes), TCP port (2 bytes)
+    # and version (1 byte)
+    BOOTSTRAP_PEER_SIZE = 25
+
+    # Builds a bootstrap response from given data
+    #
+    # @param data [String] the data to decode
+    # @return [BootstrapResponse] the bootstrap response if the data is valid, nil otherwise
+    def self.from_data(data)
+      message = Message.from_data(data)
+      # abort if this isn't a valid response
+      return unless message
+      return unless message.type == BOOTSTRAP_RESPONSE
+      return unless message.body.size >= 23
+      bootstrap_peer_id = Rex::Proto::Kademlia.decode_peer_id(message.body.slice!(0, 16))
+      bootstrap_tcp_port, bootstrap_version, num_peers = message.body.slice!(0, 5).unpack('vCv')
+      # protocol says there are no peers and the body confirms this, so just return with no peers
+      if num_peers == 0 && message.body.blank?
+        peers = []
+      else
+        peers_data = message.body
+        # peers data is too long/short, abort
+        return if peers_data.size % BOOTSTRAP_PEER_SIZE != 0
+        peers = []
+        until peers_data.blank?
+          peer_data = peers_data.slice!(0, BOOTSTRAP_PEER_SIZE)
+          peer_id = Rex::Proto::Kademlia.decode_peer_id(peer_data.slice!(0, 16))
+          ip, udp_port, tcp_port, version = peer_data.unpack('VvvC')
+          peers << {
+            id: peer_id,
+            ip: Rex::Socket.addr_itoa(ip),
+            tcp_port: tcp_port,
+            udp_port: udp_port,
+            version: version
+          }
+        end
+      end
+      BootstrapResponse.new(bootstrap_peer_id, bootstrap_tcp_port, bootstrap_version, peers)
+    end
+  end
+end
+end
+end

lib/rex/proto/kademlia/message.rb

@@ -0,0 +1,72 @@
+# -*- coding: binary -*-
+
+module Rex
+module Proto
+##
+#
+# Minimal support for the newer Kademlia protocol, referred to here and often
+# elsewhere as Kademlia2.  It is unclear how this differs from the old protocol.
+#
+# Protocol details are hard to come by because most documentation is academic
+# in nature and glosses over the low-level network details.  The best
+# documents I found on the protocol are:
+#
+# http://gbmaster.wordpress.com/2013/05/05/botnets-surrounding-us-an-initial-focus-on-kad/
+# http://gbmaster.wordpress.com/2013/06/16/botnets-surrounding-us-sending-kademlia2_bootstrap_req-kademlia2_hello_req-and-their-strict-cousins/
+# http://gbmaster.wordpress.com/2013/11/23/botnets-surrounding-us-performing-requests-sending-out-kademlia2_req-and-asking-contact-where-art-thou/
+#
+##
+module Kademlia
+  # A simple Kademlia message
+  class Message
+    # The header that non-compressed Kad messages use
+    STANDARD_PACKET = 0xE4
+    # The header that compressed Kad messages use, which is currently unsupported
+    COMPRESSED_PACKET = 0xE5
+
+    # @return [Integer] the message type
+    attr_reader :type
+    # @return [String] the message body
+    attr_reader :body
+
+    # Construct a new Message from the provided type and body
+    #
+    # @param type [String] the message type
+    # @param body [String] the message body
+    def initialize(type, body = '')
+      @type = type
+      @body = body
+    end
+
+    # Construct a new Message from the provided data
+    #
+    # @param data [String] the data to interpret as a Kademlia message
+    # @return [Message] the message if valid, nil otherwise
+    def self.from_data(data)
+      return if data.length < 2
+      header, type = data.unpack('CC')
+      if header == COMPRESSED_PACKET
+        fail NotImplementedError, "Unable to handle #{data.length}-byte compressed Kademlia message"
+      end
+      return if header != STANDARD_PACKET
+      Message.new(type, data[2, data.length])
+    end
+
+    # Get this Message as a String
+    #
+    # @return [String] the string representation of this Message
+    def to_str
+      [STANDARD_PACKET, @type].pack('CC') + @body
+    end
+
+    # Compares this Message and another Message for equality
+    #
+    # @param other [Message] the Message to compare
+    # @return [Boolean] true iff the two messages have equal types and bodies, false otherwise
+    def ==(other)
+      type == other.type && body == other.body
+    end
+  end
+end
+end
+end

lib/rex/proto/kademlia/ping.rb

@@ -0,0 +1,19 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia/message'
+
+module Rex
+module Proto
+module Kademlia
+  # Opcode for a PING request
+  PING = 0x60
+
+  # A Kademlia ping message.
+  class Ping < Message
+    def initialize
+      super(PING)
+    end
+  end
+end
+end
+end

lib/rex/proto/kademlia/pong.rb

@@ -0,0 +1,41 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/kademlia/message'
+
+module Rex
+module Proto
+module Kademlia
+  # Opcode for a PING response
+  PONG = 0x61
+
+  # A Kademlia pong message.
+  class Pong < Message
+    # @return [Integer] the source port from which the PING was received
+    attr_reader :port
+
+    def initialize(port = nil)
+      super(PONG)
+      @port = port
+    end
+
+    # Builds a pong from given data
+    #
+    # @param data [String] the data to decode
+    # @return [Pong] the pong if the data is valid, nil otherwise
+    def self.from_data(data)
+      message = super(data)
+      return if message.type != PONG
+      return if message.body.size != 2
+      Pong.new(message.body.unpack('v')[0])
+    end
+
+    # Get this Pong as a String
+    #
+    # @return [String] the string representation of this Pong
+    def to_str
+      super + [@port].pack('v')
+    end
+  end
+end
+end
+end

lib/rex/proto/kademlia/util.rb

@@ -0,0 +1,22 @@
+# -*- coding: binary -*-
+
+module Rex
+module Proto
+module Kademlia
+  # Decodes an on-the-wire representation of a Kademlia peer to its 16-character hex equivalent
+  #
+  # @param bytes [String] the on-the-wire representation of a Kademlia peer
+  # @return [String] the peer ID if valid, nil otherwise
+  def self.decode_peer_id(bytes)
+    peer_id = 0
+    return nil unless bytes.size == 16
+    bytes.unpack('VVVV').map { |p| peer_id = ((peer_id << 32) ^ p) }
+    peer_id.to_s(16).upcase
+  end
+
+  # TODO
+  # def encode_peer_id(id)
+  # end
+end
+end
+end

modules/auxiliary/scanner/kademlia/server_info.rb

@@ -0,0 +1,96 @@
+##
+# This module requires Metasploit: http://metasploit.com/download
+# Current source: https://github.com/rapid7/metasploit-framework
+##
+
+require 'msf/core'
+
+class Metasploit3 < Msf::Auxiliary
+  include Msf::Auxiliary::Report
+  include Msf::Auxiliary::UDPScanner
+  include Msf::Auxiliary::Kademlia
+
+  def initialize(info = {})
+    super(
+      update_info(
+        info,
+        'Name'           => 'Gather Kademlia Server Information',
+        'Description'    => %q(
+          This module uses the Kademlia BOOTSTRAP and PING messages to identify
+          and extract information from Kademlia speaking UDP endpoints,
+          typically belonging to eMule/eDonkey/BitTorrent servers or other P2P
+          applications.
+        ),
+        'Author'         => 'Jon Hart <jon_hart[at]rapid7.com>',
+        'References'     =>
+          [
+            # There are lots of academic papers on the protocol but they tend to lack usable
+            # protocol details.  This is the best I've found
+            ['URL', 'http://gbmaster.wordpress.com/2013/06/16/botnets-surrounding-us-sending-kademlia2_bootstrap_req-kademlia2_hello_req-and-their-strict-cousins/#more-125']
+          ],
+        'License'        => MSF_LICENSE,
+        'Actions'        => [
+          ['BOOTSTRAP', 'Description' => 'Use a Kademlia2 BOOTSTRAP'],
+          ['PING', 'Description' => 'Use a Kademlia2 PING']
+        ],
+        'DefaultAction'  => 'BOOTSTRAP'
+      )
+    )
+
+    register_options(
+    [
+      Opt::RPORT(4672)
+    ], self.class)
+  end
+
+  def build_probe
+    @probe ||= case action.name
+               when 'BOOTSTRAP'
+                 BootstrapRequest.new
+               when 'PING'
+                 Ping.new
+               end
+  end
+
+  def scanner_process(response, src_host, src_port)
+    return if response.blank?
+    peer = "#{src_host}:#{src_port}"
+
+    case action.name
+    when 'BOOTSTRAP'
+      if bootstrap_res = BootstrapResponse.from_data(response)
+        info = {
+          peer_id: bootstrap_res.peer_id,
+          tcp_port: bootstrap_res.tcp_port,
+          version: bootstrap_res.version,
+          peers: bootstrap_res.peers
+        }
+        print_good("#{peer} ID #{bootstrap_res.peer_id}, TCP port #{bootstrap_res.tcp_port}," +
+                   " version #{bootstrap_res.version}, #{bootstrap_res.peers.size} peers")
+      end
+    when 'PING'
+      if pong = Pong.from_data(response)
+        print_good("#{peer} PONG port #{pong.port}")
+        # port should match the port we contacted it from.  TODO: validate this?
+        info = { udp_port: pong.port }
+      end
+    end
+
+    return unless info
+    @results[src_host] ||= []
+    @results[src_host] << info
+  end
+
+  def scanner_postscan(_batch)
+    @results.each_pair do |host, info|
+      report_host(host: host)
+      report_service(
+        host: host,
+        proto: 'udp',
+        port: rport,
+        name: 'kademlia',
+        info: info
+      )
+    end
+  end
+end