firescan 0.07

data/lib/firebind/simple_protocol.rb

@@ -0,0 +1,59 @@
+# Firebind -- Path Scan Client Software
+# Copyright (C) 2013 Firebind Inc. All rights reserved.
+# Authors - Jay Houghton
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+require_relative 'tcp_transport'
+require_relative 'udp_transport'
+require_relative 'tools'
+
+module Firebind
+
+  # Simplest of all echo protocols. This simply sends and receives an 8-byte payload representing the
+  # ID number of the scan that was assigned during the Scan API call.
+  class SimpleProtocol
+
+    include Tools
+
+    # @param [Object] transport
+    def initialize(guid,echo_host,transport,timeout,state=NIL)
+      @guid = guid
+      @echo_host = echo_host
+      @state = state
+      case transport
+        when :TCP
+          @transport = Firebind::TcpTransport.new @echo_host,timeout
+        when :UDP
+          @transport = Firebind::UdpTransport.new @echo_host,timeout
+        else
+          @transport = Firebind::TcpTransport.new @echo_host,timeout
+      end
+    end
+
+    def echo(port)
+      payload = big_endian @guid
+      begin
+        @transport.connect port  # connect
+      end
+
+      begin
+        @transport.send payload  # send
+        @transport.receive       # receive
+      ensure
+        @transport.close         # close
+      end
+    end
+
+  end
+end

data/lib/firebind/tcp_transport.rb

@@ -0,0 +1,184 @@
+# Firebind -- Path Scan Client Software
+# Copyright (C) 2013 Firebind Inc. All rights reserved.
+# Authors - Jay Houghton
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+require_relative 'transport'
+require_relative 'tools'
+require_relative 'scan_error'
+
+module Firebind
+
+  # Send and receive echo using TCP transport.
+  class TcpTransport < Transport
+    include Tools
+    def initialize (echo_server,timeout)
+      super(echo_server,timeout)
+    end
+
+    # establish connection to echo server on port
+    def connect(port)
+      @port = port
+      connect_start = Time.now
+      #host_addr = Socket.getaddrinfo(@echo_server,nil)  # probably should get 0,3 from this guy for IPv6
+
+      begin
+        #noinspection RubyArgCount
+        @socket = Socket.new(:INET, :STREAM)
+        @remote_addr = Socket.pack_sockaddr_in(@port, @echo_server)
+      rescue
+        raise Firebind::ScanError.new :HANDSHAKE_CONNECTION_INITIATION_FAILURE
+      end
+
+      begin
+        @socket.connect_nonblock @remote_addr
+      rescue Errno::EINPROGRESS
+        # still doing handshake, wait @timeout until its ready to connect_nonblock again
+        debug("connection still inprogress select for #{@timeout}ms")
+
+        # interest ops: reading,writing,error,timeout
+        readables,writables,errors = IO.select([@socket], [@socket], [@socket], @timeout_seconds)
+        debug "readables=#{readables} writables=#{writables} errors=#{errors}"
+
+        readable = readables != NIL && readables.length > 0
+        writable = writables != NIL && writables.length > 0
+        error = errors != NIL && errors.length > 0
+
+        if error
+          raise Firebind::ScanError.new(:HANDSHAKE_CONNECTION_REFUSED)
+        end
+
+        if readable || writable
+          retry
+        else
+          debug "connection timeout after #{@timeout}ms"
+          raise Firebind::ScanError.new :HANDSHAKE_CONNECTION_TIME_OUT
+        end
+
+        # A time check may be required in the future (if we select for less than timeout)
+        # if Time.now - connect_start > @timeout_seconds
+        #  raise Firebind::ScanError.new :HANDSHAKE_CONNECTION_TIME_OUT
+
+      rescue Errno::EISCONN # this is a linux code... todo: figure the platform codes for continuation
+        debug 'connection success'
+      rescue Errno::ECONNREFUSED => e
+        raise Firebind::ScanError.new(:HANDSHAKE_CONNECTION_REFUSED, e)
+      rescue
+        #collect all the ways a connection can fail... some of the conditions are:
+        #  1) No route to host - connect(2)
+        raise Firebind::ScanError.new(:HANDSHAKE_CONNECTION_REFUSED, $!)
+      end
+    end
+
+    # Send data to the echo server
+    #
+    # @param [Array[]] payload - array of bytes
+    def send(payload)
+      @payload = payload
+      size = payload.length
+      count = 0
+      send_start = Time.now
+
+      payload.each do |byte|
+        begin
+          count += @socket.write_nonblock [byte].pack('C')
+          debug "wrote #{count} bytes to #{@echo_server}:#{@port}"
+        rescue IO::WaitWritable, Errno::EINTR
+          if count == size
+            # we've written our payload, we're done
+            debug "completed #{count} byte payload to #{@echo_server}:#{@port}"
+          elsif Time.now - send_start > @timeout_seconds
+            # we've timed out of sending
+            raise Firebind::ScanError.new :FAILURE_ON_PAYLOAD_SEND
+          else
+            # try to write some more ?  http://ruby-doc.org/core-1.9.3/IO.html#method-i-write_nonblock
+            retry
+          end
+
+        rescue
+          #collect all the ways a send can fail...
+          raise Firebind::ScanError.new(:FAILURE_ON_PAYLOAD_SEND, $!)
+        end
+
+      end
+    end
+
+    # Receive echo response from server.
+    #
+    #
+    # PAYLOAD_REFUSED_ON_RECV
+    # PAYLOAD_ERROR_ON_RECV
+    # PAYLOAD_TIMED_OUT_ON_RECV
+    #
+    # @return [Object]
+    def receive
+      size = @payload.length
+      count = 0
+      receive_start = Time.now
+      receive_buffer = ''
+
+      while Time.now - receive_start <= @timeout_seconds && count < size
+        begin
+          read_result = @socket.read_nonblock(1024)
+          count += read_result.length  # because appending to receive_buffer won't count recv bytes via .length
+          # add read_result to our buffer
+          receive_buffer << read_result
+          debug "read buffer is #{count}"
+        rescue IO::WaitReadable
+          if count == size
+            # we're done - read all we had expected to receive
+            debug "completed full read of #{count} bytes"
+            break
+          elsif Time.now - receive_start > @timeout_seconds
+            # timeout on receive
+            raise Firebind::ScanError.new(:PAYLOAD_TIMED_OUT_ON_RECV)
+          else
+            # keep going
+            IO.select([@socket],nil,nil,@timeout_seconds)
+            retry
+          end
+        rescue EOFError => e
+          # connection was forcefully dropped or sent a final FIN ACK closing sequence
+          if count != size
+            raise Firebind::ScanError.new(:PAYLOAD_ERROR_ON_RECV,e)
+          end
+
+        rescue
+          #collect all the ways a receive can fail... todo:
+          if $debug
+            puts 'Caught unhandled socket error:'
+            p $1
+            puts $@
+          end
+          raise Firebind::ScanError.new(:PAYLOAD_REFUSED_ON_RECV,$!)
+        end
+      end
+
+      # we still could have timed out here, check rx buffer size first
+      if count < size
+        raise Firebind::ScanError.new(:PAYLOAD_TIMED_OUT_ON_RECV)
+      end
+
+      # now compare what we received with what we sent
+      received_array = receive_buffer.unpack('C*')
+      if received_array != @payload
+        debug "rx buffer #{received_array.to_s} is NOT equal to expected #{@payload.to_s}"
+        raise Firebind::ScanError.new(:PAYLOAD_MISMATCH_ON_RECV)
+      else
+        debug "rx buffer #{received_array.to_s} is equal to payload #{@payload.to_s}"
+      end
+
+    end
+  end
+end

data/lib/firebind/tools.rb

@@ -0,0 +1,107 @@
+# Firebind -- Path Scan Client Software
+# Copyright (C) 2013 Firebind Inc. All rights reserved.
+# Authors - Jay Houghton
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+# Utility module for translating socket and result codes.
+module Tools
+
+  $debug = false
+  $verbose = false
+
+  def big_endian(a_number)
+    bytes = []
+    7.downto(0) do |i|
+      bytes[i] = 0xFF & a_number
+      a_number = a_number >> 8
+    end
+    bytes
+  end
+
+  # @@SOCKET_CODES = { :CONNECTION_REFUSED => }
+
+  #
+  # Result Codes as defined in reference documents
+  # http://www.firebind.com/support/reference/socket_mapping.html
+  #
+  $handshake_connection_refused = 12152
+  $handshake_connection_timeout = 12151
+  #noinspection RubyGlobalVariableNamingConvention
+  $handshake_connection_initiation_failure = 12150
+  $payload_refused_on_recv = 12156
+  $payload_timed_out_on_recv = 12155
+  $payload_error_on_recv = 12158
+  $payload_mismatch_on_recv = 12157
+  $failure_on_payload_send = 12154
+  #noinspection RubyGlobalVariableNamingConvention
+  $handshake_connection_completion_failure = 12153
+  $success = 12110
+  $skipped = 12020
+  $scan_failure = 12111
+  $client_network_failure = 12112
+  $command_server_unavailable = 7
+
+  $result_codes = {HANDSHAKE_CONNECTION_REFUSED: $handshake_connection_refused,
+                  HANDSHAKE_CONNECTION_TIME_OUT: $handshake_connection_timeout,
+                  HANDSHAKE_CONNECTION_INITIATION_FAILURE: $handshake_connection_initiation_failure,
+                  PAYLOAD_REFUSED_ON_RECV: $payload_refused_on_recv,
+                  PAYLOAD_TIMED_OUT_ON_RECV: $payload_timed_out_on_recv,
+                  PAYLOAD_ERROR_ON_RECV: $payload_error_on_recv,
+                  PAYLOAD_MISMATCH_ON_RECV: $payload_mismatch_on_recv,
+                  FAILURE_ON_PAYLOAD_SEND: $failure_on_payload_send,
+                  HANDSHAKE_CONNECTION_COMPLETION_FAILURE: $handshake_connection_completion_failure,
+                  SUCCESS: $success,
+                  SKIPPED: $skipped,
+                  TEST_FAILURE: $scan_failure,
+                  CLIENT_NETWORK_FAILURE: $client_network_failure
+  }
+
+  # todo: finish reverse result code / symbol mapping
+
+  #result_code_rev = { $handshake_connection_refused => :HANDSHAKE_CONNECTION_REFUSED }
+
+  $result_code_messages = { $handshake_connection_refused => 'Handshake Connection Refused',
+                            $handshake_connection_timeout => 'Handshake Connection Timeout',
+                            $handshake_connection_initiation_failure => 'Handshake Connection Initiation Failure',
+                            $payload_refused_on_recv => 'Payload Refused On Receive',
+                            $payload_timed_out_on_recv => 'Payload Timed Out On Receive',
+                            $payload_error_on_recv => 'Payload Error On Receive',
+                            $payload_mismatch_on_recv => 'Payload Mismatch On Receive',
+                            $failure_on_payload_send => 'Failure On Payload Send',
+                            $handshake_connection_completion_failure => 'Handshake Connection Completion Failure',
+                            $success => 'Open',
+                            $skipped => 'Skipped',
+                            $scan_failure => 'Scan Failure',
+                            $client_network_failure => 'Client Network Failure'
+  }
+
+  # server status codes
+  $authentication_failure = 20401
+  $request_invalid = 20400
+  $server_bind_error = 2017
+  $client_scan_completed = 12021
+
+  def verbose(msg)
+    puts "Firescan - #{msg}" if $verbose
+  end
+
+  def debug(msg)
+    puts "DEBUG #{self.class.to_s} - #{msg}"  if $debug
+  end
+
+  def out(msg)
+    puts msg
+  end
+
+end

data/lib/firebind/transport.rb

@@ -0,0 +1,44 @@
+# Firebind -- Path Scan Client Software
+# Copyright (C) 2013 Firebind Inc. All rights reserved.
+# Authors - Jay Houghton
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+require_relative 'tools'
+require 'socket'
+
+module Firebind
+
+
+  class Transport
+
+    include Tools
+
+    def initialize (echo_server, timeout)
+      @echo_server = echo_server
+      @timeout = timeout
+      @timeout_seconds = timeout.to_f/1000
+    end
+
+
+    def close
+      begin
+        #noinspection RubyResolve
+        @socket.close
+      rescue
+        debug "error closing socket #{$!}"
+      end
+    end
+
+  end
+end

data/lib/firebind/udp_transport.rb

@@ -0,0 +1,174 @@
+# Firebind -- Path Scan Client Software
+# Copyright (C) 2013 Firebind Inc. All rights reserved.
+# Authors - Jay Houghton
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+require_relative 'transport'
+require_relative 'tools'
+require_relative 'scan_error'
+
+module Firebind
+
+  # Send and receive echo using UDP transport.
+  class UdpTransport < Transport
+    include Tools
+    def initialize (echo_server,timeout)
+      super(echo_server,timeout)
+    end
+
+    def connect(port)
+      @port = port
+      begin
+        @socket = Socket.new(:INET,:DGRAM)
+        @remote_addr = Socket.pack_sockaddr_in(@port, @echo_server)
+        @socket.connect_nonblock @remote_addr
+      rescue
+        raise Firebind::ScanError.new :FAILURE_ON_PAYLOAD_SEND
+      end
+    end
+
+    # Send data to the echo server, we'll send multiple copies of the same data. So long as the echo server
+    # receives one of these we should expect an echo response.
+    #
+    # @param [Array[]] payload - array of bytes
+    def send(payload,num_payloads = 10)
+      @payload = payload
+      size = payload.length
+      count = 0
+      send_start = Time.now
+
+      # send the payload this many times
+      payloads_sent = 0
+
+      debug "sending buffer #{payload.to_s}"
+      #payload.each do |byte|
+      while count < size && Time.now - send_start < @timeout_seconds
+        begin
+
+          # chomp up the payload depending upon where we left off
+          send_buffer = payload[count,size-count]
+
+          count += @socket.write_nonblock send_buffer.pack('C*')
+          debug "wrote #{count} bytes to #{@echo_server}:#{@port}"
+
+          if payloads_sent < num_payloads and count == size
+            # reset counters to send another payload
+            debug "sending datagram number #{payloads_sent}"
+            count = 0
+            payloads_sent += 1
+          end
+
+        rescue IO::WaitWritable, Errno::EINTR
+
+          if count == size
+            # we've written our payload, we're done
+            debug "completed #{count} byte payload to #{@echo_server}:#{@port}"
+          elsif Time.now - send_start > @timeout_seconds
+            # we've timed out of sending
+            raise Firebind::ScanError.new :FAILURE_ON_PAYLOAD_SEND
+          else
+            # try to write some more ?  http://ruby-doc.org/core-1.9.3/IO.html#method-i-write_nonblock
+            retry
+          end
+
+        rescue
+          #collect all the ways a send can fail...
+          raise Firebind::ScanError.new(:FAILURE_ON_PAYLOAD_SEND, $!)
+        end
+
+      end
+    end
+
+    #
+    # Receive echo response from server. Partway through the timeout we'll call send() again to send
+    # more datagrams as a last ditch effort to get data across.
+    #
+    # PAYLOAD_REFUSED_ON_RECV
+    # PAYLOAD_ERROR_ON_RECV
+    # PAYLOAD_TIMED_OUT_ON_RECV
+    #
+    def receive
+      size = @payload.length
+      count = 0
+      receive_start = Time.now
+      receive_buffer = ''
+      halfway = @timeout_seconds/2
+
+      while Time.now - receive_start <= @timeout_seconds && count < size
+
+        begin
+          read_result = @socket.read_nonblock(1024)
+          count += read_result.length  # because appending to receive_buffer won't count recv bytes via .length
+          # add read_result to our buffer
+          receive_buffer << read_result
+          debug "read buffer is #{count}"
+        rescue IO::WaitReadable
+          if count == size
+            # we're done - read all we had expected to receive
+            debug "completed full read of #{count} bytes"
+            break
+          elsif Time.now - receive_start > @timeout_seconds
+            # timeout on receive
+            raise Firebind::ScanError.new(:PAYLOAD_TIMED_OUT_ON_RECV)
+          else
+            # send some more datagrams?
+            if Time.now - receive_start > halfway
+              begin
+                debug "halfway through timeout sending more datagrams on port #{@port}"
+                send(@payload,5)
+              rescue
+                debug "mid-receive cycle resend resulted in #{$!} ignoring"
+              end
+            end
+
+            # keep going
+            IO.select([@socket],nil,nil,halfway)
+            retry
+          end
+        rescue EOFError => e
+          # connection was forcefully dropped or sent a final FIN ACK closing sequence
+          if count != size
+            raise Firebind::ScanError.new(:PAYLOAD_ERROR_ON_RECV,e)
+          end
+
+        rescue
+          #collect all the ways a receive can fail... todo:
+          if $debug
+            puts 'Caught unhandled socket error:'
+            p $1
+            puts $@
+          end
+          raise Firebind::ScanError.new(:PAYLOAD_REFUSED_ON_RECV,$!)
+        end
+
+      end
+
+      # we still could have timed out here, check rx buffer size first
+      if count < size
+        raise Firebind::ScanError.new(:PAYLOAD_TIMED_OUT_ON_RECV)
+      end
+
+      # now compare what we received with what we sent
+      received_array = receive_buffer.unpack('C*')
+      if received_array != @payload
+        debug "rx buffer #{received_array.to_s} is NOT equal to expected #{@payload.to_s}"
+        raise Firebind::ScanError.new(:PAYLOAD_MISMATCH_ON_RECV)
+      else
+        debug "rx buffer #{received_array.to_s} is equal to payload #{@payload.to_s}"
+      end
+
+    end
+
+  end
+end