Add beginnings of Kademlia gather module and protocol support

Author: jhart-r7

lib/rex/proto/kademlia.rb

@@ -0,0 +1,3 @@
+# -*- coding: binary -*-
+
+require 'rex/proto/steam/message'

lib/rex/proto/kademlia/message.rb

@@ -0,0 +1,106 @@
+# -*- 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
+  STANDARD_PACKET = 0xE4
+  # TODO: support this format
+  COMPRESSED_PACKET = 0xE5
+
+  BOOTSTRAP_REQ = 0x01
+  BOOTSTRAP_RES = 0x09
+  PING = 0x60
+  PONG = 0x61
+
+  # 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
+
+  def decode_message(message)
+    # minimum size is header (1) + opcode (1) + stuff (0+)
+    return if message.length < 2
+    header, opcode = message.unpack('CC')
+    if header == COMPRESSED_PACKET
+      fail NotImplementedError, "Unable to handle compressed #{message.length}-byte compressed Kademlia message"
+    end
+    return if header != STANDARD_PACKET
+    [opcode, message[2, message.length]]
+  end
+
+  def encode_message(type, payload = '')
+    [STANDARD_PACKET, type].pack('CC') + payload
+  end
+
+  def bootstrap
+    encode_message(BOOTSTRAP_REQ)
+  end
+
+  def decode_bootstrap_res(message)
+    opcode, payload = decode_message(message)
+    # abort if this isn't a valid response
+    return nil unless opcode = BOOTSTRAP_RES
+    return nil unless payload.size >= 23
+    # XXX: unsure how to get the 128-bit contact ID just yet...
+    peer_id = payload.slice!(0,16)
+    tcp_port, version, num_peers = payload.slice!(0,5).unpack('vCv')
+    # protocol says there are no peers and the payload confirms this, so just return with no peers
+    return [ tcp_port, version, []] if num_peers == 0 && payload.blank?
+    peers = decode_bootstrap_peers(payload)
+    # abort if the peer data was invalid
+    return nil unless peers
+    [ peer_id, tcp_port, version, peers ]
+  end
+
+  # Returns a PING message
+  def ping
+    encode_message(PING)
+  end
+
+  # Decodes a PONG message, returning the port used by the peer
+  def decode_pong(message)
+    opcode, port = decode_message(message)
+    # abort if this isn't a pong
+    return nil unless opcode == PONG
+    # abort if the response is too large/small
+    return nil unless port && port.size == 2
+    # the port will be the port the true endpoint is actually listening on,
+    # which may not be the same as the port you contacted it on (NAT/etc)
+    port.unpack('v')[0]
+  end
+
+  def decode_bootstrap_peers(peers_data)
+    # sanity check total size
+    return nil unless peers_data.size % BOOTSTRAP_PEER_SIZE == 0
+    peers = []
+    until peers_data.blank?
+      peers << decode_bootstrap_peer(peers_data.slice!(0, BOOTSTRAP_PEER_SIZE))
+    end
+    peers
+  end
+
+  def decode_bootstrap_peer(peer_data)
+    # sanity check the size of this peer's data
+    return nil unless peer_data.size == BOOTSTRAP_PEER_SIZE
+    # TODO; interpret this properly
+    peer_id = peer_data.slice!(0, 16)
+    ip, udp_port, tcp_port, version = peer_data.unpack('VvvC')
+    [ peer_id, Rex::Socket.addr_itoa(ip), udp_port, tcp_port, version ]
+  end
+end
+end
+end

modules/auxiliary/scanner/kademlia/server_info.rb

@@ -0,0 +1,80 @@
+##
+# This module requires Metasploit: http://metasploit.com/download
+# Current source: https://github.com/rapid7/metasploit-framework
+##
+
+require 'msf/core'
+require 'rex/proto/kademlia'
+
+class Metasploit3 < Msf::Auxiliary
+  include Msf::Auxiliary::Report
+  include Msf::Auxiliary::UDPScanner
+  include Rex::Proto::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'
+                 bootstrap
+               when 'PING'
+                 ping
+               end
+  end
+
+  def scanner_process(response, src_host, src_port)
+    info = message_decode(response)
+    return unless info
+    @results[src_host] ||= []
+    if datastore['VERBOSE']
+      print_good("#{src_host}:#{src_port} found '#{info.inspect}'")
+    else
+      print_good("#{src_host}:#{src_port} found '#{info[:name]}'")
+    end
+    @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

spec/lib/rex/proto/kademlia/kademlia_bootstrap_res.bin

@@ -0,0 +1,121 @@
+# -*- coding: binary -*-
+require 'spec_helper'
+require 'rex/proto/kademlia/message'
+
+describe Rex::Proto::Kademlia do
+  subject do
+    mod = Module.new
+    mod.extend described_class
+    mod
+  end
+
+  describe '#encode_message' do
+    it 'should properly encode messages' do
+      expect(subject.encode_message(1)).to eq("\xE4\x01")
+      expect(subject.encode_message(1, 'p2p')).to eq("\xE4\x01p2p")
+    end
+  end
+
+  describe '#decode_message' do
+    it 'should not decode overly short messages' do
+      expect(subject.decode_message('f')).to eq(nil)
+    end
+
+    it 'should not decode unknown messages' do
+      expect(subject.decode_message("this is not kademlia")).to eq(nil)
+    end
+
+    it 'should raise on compressed messages' do
+      expect {
+        subject.decode_message("\xE5\x01blahblah")
+      }.to raise_error(NotImplementedError)
+    end
+
+    it 'should properly decode valid messages' do
+      type, payload = subject.decode_message("\xE4\xFF")
+      expect(type).to eq(0xFF)
+      expect(payload).to eq('')
+
+      _, payload = subject.decode_message("\xE4\xFFtesttesttest")
+      expect(payload).to eq('testtesttest')
+    end
+  end
+
+  describe '#decode_pong' do
+    it 'should not decode overly large/small pongs' do
+      expect(subject.decode_pong("\xE4\x61\x01")).to eq(nil)
+      expect(subject.decode_pong("\xE4\x61\x01\x02\x03")).to eq(nil)
+    end
+
+    it 'should properly decode valid pongs' do
+      expect(subject.decode_pong("\xE4\x61\x9E\x86")).to eq(34462)
+    end
+  end
+
+  describe '#decode_bootstrap_peer' do
+    it 'should not decode overly large/small peer' do
+      expect(subject.decode_bootstrap_peer("this is too small")).to eq(nil)
+      expect(subject.decode_bootstrap_peer("this is much, much, much too large")).to eq(nil)
+    end
+
+    it 'should properly extract peer info' do
+      data =
+          "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F" + # peer ID
+          "\x04\x28\xA8\xC0" + # 192.168.40.4
+          "\x31\xd4" + # UDP port 54321
+          "\x39\x30" + # TCP port 12345
+          "\x08" # peer type
+      peer_id, ip, udp_port, tcp_port, type = subject.decode_bootstrap_peer(data)
+      #expect(peer_id).to eq('something')
+      expect(ip).to eq('192.168.40.4')
+      expect(udp_port).to eq(54321)
+      expect(tcp_port).to eq(12345)
+      expect(type).to eq(8)
+    end
+  end
+
+  describe '#decode_bootstrap_peers' do
+    it 'should not decode overly small peers' do
+      expect(subject.decode_bootstrap_peer("this is too small")).to eq(nil)
+      expect(subject.decode_bootstrap_peer("this is large enough but truncated")).to eq(nil)
+    end
+
+    it 'should properly extract peers info' do
+      data =
+          "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F" + # peer ID
+          "\x04\x28\xA8\xC0" + # 192.168.40.4
+          "\x31\xd4" + # UDP port 54321
+          "\x39\x30" + # TCP port 12345
+          "\x08" + # peer type
+          "\x01\x01\x02\x02\x03\x03\x04\x04\x05\x05\x06\x06\x07\x07\x08\x08" + # peer ID
+          "\x05\x28\xA8\xC0" + # 192.168.40.5
+          "\x5c\x11" + # UDP port 4444
+          "\xb3\x15" + # TCP port 5555
+          "\x09" # peer type
+      peers = subject.decode_bootstrap_peers(data)
+      expect(peers.size).to eq(2)
+      peer1_id, peer1_ip, peer1_udp, peer1_tcp, peer1_type = peers.first
+      expect(peer1_ip).to eq('192.168.40.4')
+      expect(peer1_udp).to eq(54321)
+      expect(peer1_tcp).to eq(12345)
+      expect(peer1_type).to eq(8)
+      peer2_id, peer2_ip, peer2_udp, peer2_tcp, peer2_type = peers.last
+      expect(peer2_ip).to eq('192.168.40.5')
+      expect(peer2_udp).to eq(4444)
+      expect(peer2_tcp).to eq(5555)
+      expect(peer2_type).to eq(9)
+    end
+  end
+
+  describe '#decode_bootstrap_res' do
+    it 'should properly decode valid bootstrap responses' do
+      data = IO.read(File.join(File.dirname(__FILE__), 'kademlia_bootstrap_res.bin'))
+      peer_id, tcp, version, peers = subject.decode_bootstrap_res(data)
+      #expect(peer_id).to eq('XXXX')
+      expect(tcp).to eq(4662)
+      expect(version).to eq(8)
+      # don't bother checking every peer
+      expect(peers.size).to eq(20)
+    end
+  end
+end