ruby_smb 1.0.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 104c5f0cf4f597bf65427cf15ab08461943a38aa
-  data.tar.gz: e2f05f2857a898cd253afd829babecb715011c12
+  metadata.gz: 3fe1b1b7bdd2516bd388f86c020a9fa99b70faa0
+  data.tar.gz: aa11ed030f543c0d83b61929d10c35eea20a8455
 SHA512:
-  metadata.gz: 5070ad2e2008739b1b47407c618e0014bc98e7031d72d2cb94daf61c7d21754a8480ef37f8099f90fe31ef0ac95563943951d00ad4bcea110d465c80c6fcf0f8
-  data.tar.gz: eb91ae8bff05249dc9ec88c3fa9e18df4b8db979d9e7e9ac702c6f7af237b36c39d9d420dd0e95680e4004480dede90493fc6d58f942f45d08d3a812977a4066
+  metadata.gz: 92cc9708588a610104f8bacc8430fedd537f2ba283bb323b791ff45005a43417cf9570ce63f658b7a38c566570c2b651adb17b6750b3b117279552efaf138cab
+  data.tar.gz: 071db1651283d080b2adc728cd1f2225e051d52f86608f9f54dd6d79d39330127c3b5179d143ec9e5e155d132af1e128c4c9ca42744264caec8b249e0b0c86ec

data/.travis.yml

@@ -1,5 +1,8 @@
 language: ruby
 sudo: false
 rvm:
-  - '2.2'
+  - '2.3.8'
+  - '2.4.5'
+  - '2.5.3'
+  - '2.6.1'
   - 'jruby-9000'

data/README.md

@@ -4,11 +4,12 @@
 [![Code Climate](https://codeclimate.com/github/rapid7/ruby_smb.png)](https://codeclimate.com/github/rapid7/ruby_smb)
 [![Coverage Status](https://coveralls.io/repos/github/rapid7/ruby_smb/badge.svg?branch=master)](https://coveralls.io/github/rapid7/ruby_smb?branch=master)
 
-A native Ruby implementation of the SMB Protocol Family. It currently supports
+This is a native Ruby implementation of the SMB Protocol Family. It currently supports:
+
  1. [[MS-SMB]](https://msdn.microsoft.com/en-us/library/cc246231.aspx)
  1. [[MS-SMB2]](http://msdn.microsoft.com/en-us/library/cc246482.aspx)
 
-This library currently include both a client level, and packet level support. A user can parse and manipulate raw SMB packets, or use the simple client to perform SMB operations.
+The RubySMB library provides client-level and packet-level support for the protocol. A user can parse and manipulate raw SMB packets, or use the client to perform higher-level SMB operations.
 
 See the Wiki for more information on this project's long-term goals, style guide, and developer tips.
 
@@ -32,22 +33,17 @@ Or install it yourself as:
 
 ### Defining a packet
 
-All packets are implemented in a declarative style with BinData. Nested data
-structures are used where appropriate to give users an easy method of adjusting
-data.
+All packets are implemented in a declarative style with BinData. Nested data structures are used where appropriate to give users an easy method of manipulating individual fields inside of a packet.
 
 #### SMB1
+
 SMB1 Packets are made up of three basic components:
+
  1. **The SMB Header** - This is a standard SMB Header. All SMB1 packets use the same SMB header.
- 1. **The Parameter Block** - This is where function parameters are passed across the wire in the packet. Parameter Blocks will always
- have a 'Word Count' field that gives the size of the Parameter Block in words(2-bytes)
- 1. **The Data Block** - This is the data section of the packet. the Data Block will always have a 'byte count' field that gives the size of
- the Data block in bytes.
+ 1. **The Parameter Block** - This is where function parameters are passed across the wire in the packet. Parameter blocks will always have a 'Word Count' field that gives the size of the parameter block in words (2-bytes)
+ 1. **The Data Block** - This is the data section of the packet. The data block will always have a 'byte count' field that gives the size of the Data block in bytes.
 
-The SMB Header can always just be declared as a field in the BinData DSL for the packet class, because its structure never changes.
-For the ParameterBlock and DataBlocks, we always define subclasses for this particular packet. They inherit the 'Word Count' and
-'Byte Count' fields, along with the auto-calculation routines for those fields, from their ancestors. Any other fields are then
-defined in our subclass before we start the DSL declarations for the packet.
+The SMB Header can always just be declared as a field in the BinData DSL for the packet class, because its structure never changes. For the Parameter block and data blocks, we always define subclasses for this particular packet. They inherit the 'Word Count' and 'Byte Count' fields, along with the auto-calculation routines for those fields, from their ancestors. Any other fields are then defined in our subclass before we start the DSL declarations for the packet.
 
 Example:
 
@@ -90,8 +86,7 @@ end
 
 #### SMB2
 
-SMB2 Packets are far simpler than their older SMB1 counterparts. We still abstract out the SMB2 header since it is the same
-structure used for every packet. Beyond that, the SMB2 packet is relatively flat in comparison to SMB1.
+SMB2 Packets are far simpler than their older SMB1 counterparts. We still abstract out the SMB2 header since it is the same structure used for every packet. Beyond that, the SMB2 packet is relatively flat in comparison to SMB1.
 
 Example:
 ```ruby
@@ -127,8 +122,7 @@ end
 ### Using a Packet class
 
 #### Manually
-You can instantiate an instance of a particular packet class, and then reach into the data structure to set or read explicit
-values in a fairly straightforward manner.
+You can create an instance of any particular packet class, and then reach into the data structure to set or read explicit values in a fairly straightforward manner.
 
 Example:
 ```ruby
@@ -152,8 +146,7 @@ Example:
 2.3.3 :009 >
 ```
 
-You can also pass field/value pairs into the packet constructor as arguments, prefilling out certain fields
-if you wish.
+You can also pass field/value pairs into the packet constructor as arguments, defaulting individual fields as desired.
 
 Example:
 ```ruby
@@ -165,9 +158,7 @@ Example:
 
 #### Reading from a Binary Blob
 
-Sometimes you need to read a binary blob and apply one of the packet structures to it.
-For example, when you are reading a response packet off of the wire, you will need to read the raw response
-string into an actual packet class. This is done using the #read class method.
+Sometimes you need to read a binary data and apply one of the packet structures to it.  For example, when you are reading a response packet, you will need to read the raw response string into an actual packet class. This is done using the #read class method.
 
 ```ruby
 2.3.3 :014 > blob = "\xFFSMB+\x00\x00\x00\x00\x98\x01`\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00"
@@ -178,8 +169,7 @@ string into an actual packet class. This is done using the #read class method.
 ```
 
 #### Outputting to a Binary Blob
-Any structure or packet in rubySMB can also be output back into a binary blob using
-BinData's #to_binary_s method.
+Any structure or packet in RubySMB can also be converted back into a binary blob using BinData's #to_binary_s method.
 
 Example:
 ```ruby
@@ -190,38 +180,35 @@ Example:
 ```
 ### Using the Client
 
-Sitting on top of the packet layer in RubySMB is the RubySMB::Client. This is the level msot users will interact with.
-It provides fairly simple conveience methods for performing SMB actions. It handles the creation, sending and receiving of packets
-for the user, relying on reasonable defaults in many cases.
+Sitting on top of the packet layer in RubySMB is the RubySMB::Client class. This is the abstraction that most users of RubySMB will interact with. It provides simple conveience methods for performing SMB actions. It handles the creation, sending and receiving of packets for the user, providing reasonable defaults in many cases.
 
 #### Negotiation
 
-The RubySMB Client is capabale of multi-protocol negotiation. The user simply specifies whether SMB1 and/or SMB2 should be supported, and
-the client will negotiate the propper protocol and dialect behind the scenes.
+The RubySMB client is capable of multi-protocol negotiation. The user simply specifies whether SMB1 and/or SMB2 should be supported, and the client negotiates the protocol and dialect behind the scenes.
 
-In the below example, we tell the client that both SMb1 and SMB2 should be supported. The Client will then Negotiate with the
-server on which version should be used. The user does not have to ever worry about which version was negotiated.
-Example:
+In the following example, we tell the client that both SMB1 and SMB2 should be supported. The client will then negotiate with the server which version should be used.
+
+Negotiation Example:
 ```ruby
   sock = TCPSocket.new address, 445
   dispatcher = RubySMB::Dispatcher::Socket.new(sock)
 
-  client = RubySMB::Client.new(dispatcher, smb1: true, smb2: false, username: 'msfadmin', password: 'msfadmin')
+  client = RubySMB::Client.new(dispatcher, username: 'msfadmin', password: 'msfadmin')
   client.negotiate
 ```
 
 #### Authentication
 
-Authentication is achieved via the [ruby ntlm gem](https://rubygems.org/gems/rubyntlm). While the client
-will not currently attempt older basic authentication on its own, it will attempt an anonymous login, if no
-user credentials are supplied:
+RubySMB uses the [Ruby NTLM gem](https://rubygems.org/gems/rubyntlm) for authentication. While the client
+will not currently attempt older basic authentication on its own, it will attempt an anonymous login if no
+user credentials are supplied.
 
 Authenticated Example:
 ```ruby
   sock = TCPSocket.new address, 445
   dispatcher = RubySMB::Dispatcher::Socket.new(sock)
 
-  client = RubySMB::Client.new(dispatcher, smb1: true, smb2: false, username: 'msfadmin', password: 'msfadmin')
+  client = RubySMB::Client.new(dispatcher, username: 'msfadmin', password: 'msfadmin')
   client.negotiate
   client.authenticate
 ```
@@ -231,24 +218,23 @@ Anonymous Example:
       sock = TCPSocket.new address, 445
       dispatcher = RubySMB::Dispatcher::Socket.new(sock)
 
-      client = RubySMB::Client.new(dispatcher, smb1: true, smb2: false, username: '', password: '')
+      client = RubySMB::Client.new(dispatcher, username: '', password: '')
       client.negotiate
       client.authenticate
 ```
 
 #### Connecting to a Tree
 
-While there is one Client, that has branching code-paths for SMB1 and SMB2, once you connect to a
-Tree you will be given a protocol specific Tree object. This Tree object will be responsible for all file operations
-that are to be conducted on that Tree.
+While there is one RubySMB::Client object that supports both SMB1 and SMB2, once the library connects to an SMB tree, it returns a protocol-specific RubySMB::Tree object. This Tree object executes all subsequent file operations on the tree.
+
+In the below example we see a simple script to connect to a remote tree, and list all files in a given sub-directory.
 
-In the below example we see a simple script to connect to a remote Tree, and list all files in a given sub-directory.
 Example:
 ```ruby
       sock = TCPSocket.new address, 445
       dispatcher = RubySMB::Dispatcher::Socket.new(sock)
 
-      client = RubySMB::Client.new(dispatcher, smb1: true, smb2: false, username: 'msfadmin', password: 'msfadmin')
+      client = RubySMB::Client.new(dispatcher, username: 'msfadmin', password: 'msfadmin')
       client.negotiate
       client.authenticate
 
@@ -273,28 +259,30 @@ Example:
 
 
 ## Developer tips
-You'll want to have Wireshark and perhaps a tool like Impacket (which provides a small SMB client in one of its examples) installed to help with your work:
+
+It is useful to have Wireshark and a reference SMB client, such as Impacket's installed to help debug and compare output:
 
 ### Wireshark
+
+Configure Wireshark in Debian-based systems to be able to capture traffic without root user privileges:
+
 - `sudo apt-get install wireshark`
 - `sudo dpkg-reconfigure wireshark-common`
 - `sudo addgroup wireshark`
 - `sudo usermod -a -G wireshark <USERNAME>`
 
 ### Impacket
+
 - `sudo apt-get install python-setuptools`
 - `sudo easy_install pyasn1 pycrypto`
 - Download from GitHub (https://github.com/coresecurity/impacket)
 - `sudo python setup.py install`
 - `cd examples && python smbclient.py <USER>:<PASS>@<WINDOWS HOST IP>`
 
-
-
 ## License
 
 `ruby_smb` is released under a 3-clause BSD license. See [LICENSE.txt](LICENSE.txt) for full text.
 
-
 ## Contributing
 
 1. Fork it ( https://github.com/rapid7/ruby_smb/fork )

data/examples/enum_registry_key.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/ruby
+
+# This example script is used for testing Winreg registry key enumeration functionality
+# It will attempt to connect to a host and enumerate registry subkeys of a specified registry key.
+# Example usage: ruby enum_registry_key.rb 192.168.172.138 msfadmin msfadmin HKLM\\My\\Key
+# This will try to connect to \\192.168.172.138 with the msfadmin:msfadmin credentialas and enumerate HKLM\\My\\Key subkeys.
+
+require 'bundler/setup'
+require 'ruby_smb'
+
+address  = ARGV[0]
+username = ARGV[1]
+password = ARGV[2]
+registry_key = ARGV[3]
+
+sock = TCPSocket.new address, 445
+dispatcher = RubySMB::Dispatcher::Socket.new(sock, read_timeout: 60)
+
+client = RubySMB::Client.new(dispatcher, smb1: true, smb2: true, username: username, password: password)
+protocol = client.negotiate
+status = client.authenticate
+
+puts "#{protocol} : #{status}"
+
+enum_result = client.enum_registry_key(address, registry_key)
+puts enum_result
+
+client.disconnect!

data/examples/enum_registry_values.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/ruby
+
+# This example script is used for testing values enumeration of a specific Winreg registry.
+# It will attempt to connect to a host and enumerate values of a specified registry key.
+# Example usage: ruby enum_registry_values.rb 192.168.172.138 msfadmin msfadmin HKLM\\My\\Key
+# This will try to connect to \\192.168.172.138 with the msfadmin:msfadmin credentialas and enumerate HKLM\\My\\Key values.
+
+require 'bundler/setup'
+require 'ruby_smb'
+
+address  = ARGV[0]
+username = ARGV[1]
+password = ARGV[2]
+registry_key = ARGV[3]
+
+sock = TCPSocket.new address, 445
+dispatcher = RubySMB::Dispatcher::Socket.new(sock, read_timeout: 60)
+
+client = RubySMB::Client.new(dispatcher, smb1: true, smb2: true, username: username, password: password)
+protocol = client.negotiate
+status = client.authenticate
+
+puts "#{protocol} : #{status}"
+
+enum_result = client.enum_registry_values(address, registry_key)
+puts enum_result
+
+client.disconnect!
+
+

data/examples/pipes.rb

@@ -33,7 +33,8 @@ end
 
 client.authenticate
 client.tree_connect("\\\\#{address}\\IPC$")
-pipe = client.create_pipe(pipename, nil)
+client.create_pipe(pipename)
+pipe = client.last_file
 
 puts "Available:       #{pipe.peek_available}"
 puts "PipeState:       #{pipe.peek_state}" # 3 == OK

data/examples/read_registry_key_value.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/ruby
+
+# This example script is used for testing the Winreg registry key value read functionality.
+# It will attempt to connect to a host and reads the value of a specified registry key.
+# Example usage: ruby enum_registry_key.rb 192.168.172.138 msfadmin msfadmin HKLM\\My\\Key ValueName
+# This will try to connect to \\192.168.172.138 with the msfadmin:msfadmin credentialas and reads the ValueName data corresponding to the HKLM\\My\\Key registry key.
+
+require 'bundler/setup'
+require 'ruby_smb'
+
+address  = ARGV[0]
+username = ARGV[1]
+password = ARGV[2]
+registry_key = ARGV[3]
+value_name = ARGV[4]
+
+sock = TCPSocket.new address, 445
+dispatcher = RubySMB::Dispatcher::Socket.new(sock, read_timeout: 60)
+
+client = RubySMB::Client.new(dispatcher, smb1: true, smb2: true, username: username, password: password)
+protocol = client.negotiate
+status = client.authenticate
+
+puts "#{protocol}: #{status}"
+puts "Key:   #{registry_key}"
+puts "Value: #{value_name}"
+
+key_value = client.read_registry_key_value(address, registry_key, value_name)
+puts key_value
+
+client.disconnect!
+

data/lib/ruby_smb.rb

@@ -15,7 +15,6 @@ module RubySMB
   require 'ruby_smb/field'
   require 'ruby_smb/nbss'
   require 'ruby_smb/fscc'
-  require 'ruby_smb/dcerpc'
   require 'ruby_smb/generic_packet'
   require 'ruby_smb/dispatcher'
   require 'ruby_smb/version'

data/lib/ruby_smb/client.rb

@@ -8,6 +8,7 @@ module RubySMB
     require 'ruby_smb/client/tree_connect'
     require 'ruby_smb/client/echo'
     require 'ruby_smb/client/utils'
+    require 'ruby_smb/client/winreg'
 
     include RubySMB::Client::Negotiation
     include RubySMB::Client::Authentication
@@ -15,6 +16,7 @@ module RubySMB
     include RubySMB::Client::TreeConnect
     include RubySMB::Client::Echo
     include RubySMB::Client::Utils
+    include RubySMB::Client::Winreg
 
     # The Default SMB1 Dialect string used in an SMB1 Negotiate Request
     SMB1_DIALECT_SMB1_DEFAULT = 'NT LM 0.12'.freeze

data/lib/ruby_smb/client/winreg.rb

@@ -0,0 +1,46 @@
+module RubySMB
+  class Client
+    module Winreg
+
+      def connect_to_winreg(host)
+        share = "\\\\#{host}\\IPC$"
+        tree = @tree_connects.find {|tree| tree.share == share}
+        tree = tree_connect(share) unless tree
+        named_pipe = tree.open_file(filename: "winreg", write: true, read: true)
+        if block_given?
+          res = yield named_pipe
+          named_pipe.close
+          res
+        else
+          named_pipe
+        end
+      end
+
+      def has_registry_key?(host, key)
+        connect_to_winreg(host) do |named_pipe|
+          named_pipe.has_registry_key?(key)
+        end
+      end
+
+      def read_registry_key_value(host, key, value_name)
+        connect_to_winreg(host) do |named_pipe|
+          named_pipe.read_registry_key_value(key, value_name)
+        end
+      end
+
+      def enum_registry_key(host, key)
+        connect_to_winreg(host) do |named_pipe|
+          named_pipe.enum_registry_key(key)
+        end
+      end
+
+      def enum_registry_values(host, key)
+        connect_to_winreg(host) do |named_pipe|
+          named_pipe.enum_registry_values(key)
+        end
+      end
+
+    end
+  end
+end
+

data/lib/ruby_smb/dcerpc.rb

@@ -1,15 +1,53 @@
 module RubySMB
   module Dcerpc
+    MAX_XMIT_FRAG = 4280
+    MAX_RECV_FRAG = 4280
+
+    require 'windows_error/win32'
     require 'ruby_smb/dcerpc/error'
     require 'ruby_smb/dcerpc/uuid'
     require 'ruby_smb/dcerpc/ndr'
     require 'ruby_smb/dcerpc/ptypes'
     require 'ruby_smb/dcerpc/p_syntax_id_t'
+    require 'ruby_smb/dcerpc/rrp_unicode_string'
     require 'ruby_smb/dcerpc/pdu_header'
     require 'ruby_smb/dcerpc/srvsvc'
+    require 'ruby_smb/dcerpc/winreg'
     require 'ruby_smb/dcerpc/request'
     require 'ruby_smb/dcerpc/response'
     require 'ruby_smb/dcerpc/bind'
     require 'ruby_smb/dcerpc/bind_ack'
+
+
+    # Bind to the remote server interface endpoint.
+    #
+    # @param options [Hash] the options to pass to the Bind request packet. At least, :endpoint must but provided with an existing Dcerpc class
+    # @return [RubySMB::Dcerpc::BindAck] the BindAck response packet
+    # @raise [RubySMB::Dcerpc::Error::InvalidPacket] if an invalid packet is received
+    # @raise [RubySMB::Dcerpc::Error::BindError] if the response is not a BindAck packet or if the Bind result code is not ACCEPTANCE
+    def bind(options={})
+      bind_req = RubySMB::Dcerpc::Bind.new(options)
+      write(data: bind_req.to_binary_s)
+      @size = 1024
+      dcerpc_raw_response = read()
+      begin
+        dcerpc_response = RubySMB::Dcerpc::BindAck.read(dcerpc_raw_response)
+      rescue IOError
+        raise RubySMB::Dcerpc::Error::InvalidPacket, "Error reading the DCERPC response"
+      end
+      unless dcerpc_response.pdu_header.ptype == RubySMB::Dcerpc::PTypes::BIND_ACK
+        raise RubySMB::Dcerpc::Error::BindError, "Not a BindAck packet"
+      end
+
+      res_list = dcerpc_response.p_result_list
+      if res_list.n_results == 0 ||
+         res_list.p_results[0].result != RubySMB::Dcerpc::BindAck::ACCEPTANCE
+        raise RubySMB::Dcerpc::Error::BindError,
+          "Bind Failed (Result: #{res_list.p_results[0].result}, Reason: #{res_list.p_results[0].reason})"
+      end
+      @tree.client.max_buffer_size = dcerpc_response.max_xmit_frag
+      dcerpc_response
+    end
+
   end
 end