deepsecurity 0.0.19 → 0.0.20

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## CHANGELOG (notable new features or fixes)
 
+### 0.0.20
+
+* `dsc` command refactoring
+* SOAP Interface refactoring
+* Extracted savon TypeMapping functionality/DSL into seperate classes
+* Added `--detail_level` flag for `host_detail` command
+* Added `-time_format` flag to specifiy time format
+
+### 0.0.19
+
+* Updated documentation
+* Streamlined search API (e.g. `find(id)` vs. `find_by_id(id)`
+* host_group hint accessor for hosts/host_details
+
+
 ### 0.0.18
 
 * Added automatic build of Windows Installer

data/Gemfile

@@ -1,4 +1,9 @@
 source 'https://rubygems.org'
 
+# group :development do
+#  gem 'unroller' ,:git => 'git://github.com/falsetto/unroller.git'
+# end
+
+
 # Specify your gem's dependencies in deepsecurity.gemspec
 gemspec

data/bin/dsc

@@ -27,69 +27,12 @@ program_desc 'DeepSecurity command line client'
 
 version Dsc::VERSION
 
-desc "Enable client debug output. (One of #{Dsc::Command.valid_debug_levels_string})"
-arg_name 'debug'
-flag [:d, :debug]
+Dsc::Command.define_global_flags(self)
+Dsc::Command.define_misc_commands(self)
 
-desc 'Deep Security Manager Host'
-arg_name 'hostname'
-flag [:m, :manager]
+Dsc::HostDetailCommand.define_commands(self)
+Dsc::AntiMalwareEventCommand.define_commands(self)
 
-desc 'Webservice Port'
-arg_name 'port'
-default_value '4119'
-flag [:port]
-
-desc 'Tenat Name'
-arg_name 'tenat'
-default_value ''
-flag [:t, :tenant]
-
-desc 'Username'
-arg_name 'username'
-default_value 'MasterAdmin'
-flag [:u, :username]
-
-desc 'Password'
-arg_name 'password'
-flag [:p, :password]
-
-desc 'Output filename'
-default_value '--'
-flag [:o, :outfile]
-
-desc 'Show progressbar'
-default_value false
-switch [:P]
-
-command_class = Dsc::HostDetailCommand
-desc "Access #{command_class.transport_class_string}s"
-command command_class.command_symbol do |c|
-  command_class.define_list_command(c)
-  command_class.define_schema_command(c)
-end
-
-command_class = Dsc::AntiMalwareEventCommand
-desc "Access #{command_class.transport_class_string}s"
-command command_class.command_symbol do |c|
-  command_class.define_list_command(c)
-  command_class.define_schema_command(c)
-end
-
-desc 'Display API Version'
-command :api_version do |c|
-  c.action do |global_options, options, args|
-    Dsc::Command.new(global_options).print_api_version(options, args)
-  end
-end
-
-desc 'Display Manager time'
-command :manager_time do |c|
-
-  c.action do |global_options, options, args|
-    Dsc::Command.new(global_options).print_manager_time(options, args)
-  end
-end
 
 pre do |global, command, options, args|
   # Pre logic here

data/deepsecurity.gemspec

@@ -17,14 +17,19 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "savon"
   gem.add_dependency "ruby-cache"
-
   gem.add_dependency "gli"
   gem.add_dependency 'progressbar'
   gem.add_dependency "json"
 
+  gem.add_development_dependency 'rake'
   gem.add_development_dependency 'yard'
   gem.add_development_dependency 'redcarpet'
-  gem.add_development_dependency 'github-markup'
+  # gem.add_development_dependency 'github-markup'
+
+#  gem.add_development_dependency 'facets' # , '2.8.4'
+#  gem.add_development_dependency 'ruby-termios' # you're gonna need this gem too, for some reason
+#  gem.add_development_dependency 'unroller'
+
 
 end
 

data/dsc.md

@@ -61,16 +61,6 @@ The `host_detail list` command dislays a list of host details.
     SYNOPSIS
         dsc [global options] host_detail list [command options]
 
-    COMMAND OPTIONS
-        --fields=arg - A comma separated list of fields to display. (Available fields: anti_malware_classic_pattern_version, anti_malware_engine_version, anti_malware_intelli_trap_exception_version, anti_malware_intelli_trap_version,
-                       anti_malware_smart_scan_pattern_version, anti_malware_spyware_pattern_version, cloud_object_image_id, cloud_object_instance_id, cloud_object_internal_unique_id, cloud_object_security_group_ids, cloud_object_type,
-                       component_klasses, component_names, component_types, component_versions, description, display_name, external, external_id, host_group_id, host_group_name, host_interfaces, host_light, host_type, id,
-                       last_anit_malware_scheduled_scan, last_anti_malware_event, last_anti_malware_manual_scan, last_dpi_event, last_firewall_event, last_integrity_monitoring_event, last_ip_used, last_log_inspection_event,
-                       last_web_reputation_event, light, locked, name, overall_anti_malware_status, overall_dpi_status, overall_firewall_status, overall_integrity_monitoring_status, overall_last_recommendation_scan,
-                       overall_last_successful_communication, overall_last_successful_update, overall_last_update_required, overall_log_inspection_status, overall_status, overall_version, overall_web_reputation_status, platform,
-                       security_profile_id, security_profile_name, virtual_name, virtual_uuid) (default:
-                       name,display_name,anti_malware_classic_pattern_version,anti_malware_engine_version,anti_malware_intelli_trap_exception_version,anti_malware_intelli_trap_version,anti_malware_smart_scan_pattern_version,anti_malware_spyware_pattern_version,overall_last_successful_communication,platform,host_type,host_group_id)
-
 If you don't specify an explicit list of fields, the following fields are used by default:
 
 * name
@@ -96,12 +86,6 @@ The `anti_malware_event list`command displays a list of AntiMalware events.
     SYNOPSIS
         dsc [global options] anti_malware_event list [command options]
 
-    COMMAND OPTIONS
-        --fields=arg      - A comma separated list of fields to display. (Available fields: anti_malware_config_id, anti_malware_event_id, end_time, error_code, host, host_id, infected_file_path, infection_source, log_date, malware_name,
-                            malware_type, protocol, quarantine_record_id, scan_action1, scan_action2, scan_result_action1, scan_result_action2, scan_type, spyware_items, start_time, summary_scan_result, tags) (default:
-                            host.name,host.display_name,log_date,start_time,end_time,scan_action1,scan_action2,summary_scan_result,scan_result_action1,scan_result_action2,malware_name,malware_type,infected_file_path,infection_source)
-        --time_filter=arg - A filter specifying the time interval to query (One of last_hour, last_24_hours, last_7_days, last_day) (default: last_day)
-
 If you don't specify an explicit list of fields, the following fields are used by default:
 
 * host.name
@@ -126,13 +110,13 @@ Please note that if you don't specify a time filter all events of the previous d
 
 ### FIELDS
 
-The `--fields` option takes a list of comma-separated values of fields to display. You can check available fields usind the `schema` subcommand.
+The `--fields` flag takes a list of comma-separated values of fields to display. You can check available fields usind the `schema` subcommand.
 You can also get further output by separating method calls with a dot `.`. E.g.: If the field itself is called `host_name` you can also
 specify `host_name.size` which would call the `size()` method returning the length of the String.
 
 ### TIME FILTER
 
-The `--time_filter` option allows you to specify the time to be queried. One of
+The `--time_filter` flag allows you to specify the time to be queried. One of
 
 * last_hour
 * last_24_hours
@@ -142,6 +126,24 @@ The `--time_filter` option allows you to specify the time to be queried. One of
 Please note the difference between `last_24_hours` and `last_day`. `last_24_hours` returns events from the current time yesterday to now.
 `last_day` returns events from yesterday 00:00:00UTC to 23:59:59UTC.
 
+### DETAIL LEVEL
+
+The `--detail_level` flag allows you to specify the ammount of data queried for some commands. Possible options are
+
+* low
+* medium
+* high
+
+Please note that this is especially interesting if you are querying lots of objects as this reduces the ammount of data
+queried from the database as well as the network traffic.
+
+Please also note that if certain fields are empty it might be worth using higher query levels if you need that data.
+
+### TIME FORMAT
+
+The `--time_format` allows you to specify a `strftime()` compatible string to use for outputting date/time. Please check
+http://www.ruby-doc.org/core-2.0/Time.html#method-i-strftime for possible parameters.
+
 # TIPS & TRICKS
 
 ## DEFINE ROLE/USER FOR SOAP ACCESS

data/lib/deepsecurity.rb

@@ -1,8 +1,6 @@
 # @author Udo Schneider <Udo.Schneider@homeaddress.de>
 
-# require "time"
-# require "cache"
-# require "active_support/core_ext"
+require "logger"
 
 require "json"
 
@@ -10,12 +8,13 @@ require "savon_helper"
 
 require "deepsecurity/version"
 
-require "deepsecurity/ds_object"
 require "deepsecurity/enums"
 
 require "deepsecurity/exceptions/authentication_failed_exception"
 require "deepsecurity/exceptions/authentication_required_exception"
 
+require "deepsecurity/soap_interface"
+
 require "deepsecurity/manager"
 require "deepsecurity/screenscraping"
 
@@ -43,16 +42,16 @@ require "deepsecurity/transport_objects/private/vulnerability"
 
 module DeepSecurity
 
-  def self.logger
-    if @logger.nil?
-      @logger ||= Logger.new(STDOUT)
-      @logger.level = Logger::INFO
-    end
-    @logger
-  end
-
   def self.dsm
     Manager.current
   end
 
+  LOG_MAPPING = {
+      :debug => Logger::DEBUG,
+      :info => Logger::INFO,
+      :warn => Logger::WARN,
+      :error => Logger::ERROR,
+      :fatal => Logger::FATAL
+  }
+
 end

data/lib/deepsecurity/manager.rb

@@ -1,136 +1,82 @@
 # @author Udo Schneider <Udo.Schneider@homeaddress.de>
 
-require "savon"
-require "cache"
-# require "httpi"
-require "logger"
-# require "yaml"
-
 module DeepSecurity
 
-  LOG_MAPPING = {
-      :debug => Logger::DEBUG,
-      :info => Logger::INFO,
-      :warn => Logger::WARN,
-      :error => Logger::ERROR,
-      :fatal => Logger::FATAL
-  }
-
-  # This class  represents the DeepSecurity Manager. It's the entry point for all further actions
-  class Manager <DSObject
+  # This class represents the DeepSecurity Manager. It's the entry point for all further actions
+  class Manager < SavonHelper::CachingObject
 
-    @@current = nil
-
-    def self.current
-      @@current
-    end
+    # @!group High-Level SOAP Wrapper
 
-    def reset
-      @@current = nil
+    # Set connection parameters
+    # @param hostname [String] host to connect to
+    # @param port [Integer] port to connect to
+    # @param log_level [LOG_MAPPING] Log Level
+    def self.server(hostname, port=4119, log_level=nil, logger = nil)
+      default_logger = Logger.new(STDOUT)
+      default_logger.level = LOG_MAPPING[log_level] || Logger::INFO
+      self.new(DeepSecurity::SOAPInterface.new(hostname, port, logger || default_logger, log_level))
     end
 
-    # Obtain a new wrapper around the DeepSecurity Manager SOAP API.
-    def initialize(hostname, port=4119, log_level)
-      @hostname = hostname
-      @port = port
-      super()
-      @client = Savon.client(:wsdl => "https://#{hostname}:#{port}/webservice/Manager?WSDL",
-                             :convert_request_keys_to => :none, # or one of [:lower_camelcase, :upcase, :none]
-                             :ssl_verify_mode => :none,
-                             :logger => logger,
-                             :log_level => log_level,
-                             :log => (!log_level.nil?))
+    # @param interface [DeepSecurity::SOAPInterface] The initialized interface to direct further calls to.
+    def initialize(interface)
+      @interface = interface
+      @interface.manager = self
     end
 
-    # @!group Request Helper
-
-    # Send an authenticated WebUI Request to the Server for URL +url and return the response body
-    def send_authenticated_http_get(path)
-      logger.debug { "#{self.class}\##{__method__}(#{path.inspect})" }
-      url = "https://#{@hostname}:#{@port}#{path}"
-      request = HTTPI::Request.new(url)
-      request.auth.ssl.verify_mode = :none
-      request.headers = {
-          "Cookie" => "sID=#{@sID}"
-      }
-      request.gzip
-      response = HTTPI.get request
-      response.body
-    end
 
-    # Send an authenticated WebUI Request to the Server for URL +url and return the response body
-    def send_authenticated_http_post(path, body)
-      logger.debug { "#{self.class}\##{__method__}(#{path.inspect})" }
-      url = "https://#{@hostname}:#{@port}#{path}"
-      request = HTTPI::Request.new(url)
-      request.auth.ssl.verify_mode = :none
-      request.headers = {
-          "Cookie" => "sID=#{@sID}",
-          "Content-Type" => "application/x-www-form-urlencoded"
-      }
-      request.gzip
-      request.body = body
-      response = HTTPI.post request
-      response.body
+    # Authenticates a user within the given tenant, and returns a session ID for use when calling other methods of Manager.
+    # When no longer required, the session should be terminated by calling disconnect.
+    # @param tenant [String]
+    # @param username [String]
+    # @param password [String]
+    # @return [Manager] The current manager
+    def connect(tenant, username, password)
+      @sID = (tenant.blank? ? interface.authenticate(username, password) : interface.authenticateTenant(tenant, username, password)).to_s
+      self
+    rescue Savon::SOAPFault => error
+      fault = error.to_hash[:fault]
+      message = fault[:faultstring].to_s
+      message = fault[:detail][:exception_name].to_s if message.blank?
+      raise AuthenticationFailedException.new("(#{message})")
     end
 
-    # @!endgroup
-
-    # @!group Caching
-
-    def cache
-      @cache ||= Cache.new(nil, nil, 10000, 5*60)
+    # Ends an authenticated user session. The Web Service client should end the authentication session in all exit cases.
+    # @return [void]
+    def disconnect
+      interface.endSession() if authenticated?
     end
 
-    # @!endgroup
-
-    public
-
-    # @!group High-Level SOAP Wrapper
-
     # Retrieves the Manager Web Service API version. Not the same as the Manager version.
     # @return [Integer] The Web Service API version.
     def api_version
-      dsm.getApiVersion()
+      interface.getApiVersion().to_i
     end
 
     # Retrieve the Manager Web Service API version. Not the same as the Manager version.
     # @return [Time] Manager time as a language localized object.
     def manager_time
-      dsm.getManagerTime()
+      Time.parse(interface.getManagerTime())
     end
 
-    # Set connection parameters
-    # @param [String] hostname host to connect to
-    # @param [Integer] port port to connect to
-    # @param [LOG_MAPPING] log_level Log Level
-    def self.server(hostname, port=4119, log_level=nil)
-      dsm = self.new(hostname, port, log_level)
-      dsm.logger.level = LOG_MAPPING[log_level] unless log_level.nil?
-      @@current = dsm
+    # @!endgroup
+
+    # Check if the session has been authenticated.
+    def authenticated?
+      !@sID.nil?
     end
 
-    # Authenticates a user within the given tenant, and returns a session ID for use when calling other methods of Manager. When no longer required, the session should be terminated by calling endSession.
-    # @param [String] tenant
-    # @param [String] username
-    # @param [String] password
-    # @return [Manager] The current manager
-    def connect(tenant, username, password)
-      @sID = tenant.blank? ? authenticate(username, password) : authenticate_tenant(tenant, username, password)
-      dsm
-    rescue Savon::SOAPFault => error
-      raise AuthenticationFailedException.new(error.to_hash[:fault][:faultstring].to_s)
+    def sID
+      raise DeepSecurity::AuthenticationRequiredException unless authenticated?
+      @sID
     end
 
-    # Ends an authenticated user session. The Web Service client should end the authentication session in all exit cases.
-    # @return [void]
-    def disconnect
-      dsm.end_session() if authenticated?
-      dsm.reset
-      nil
+    def interface
+      @interface
     end
 
-    # @!endgroup
+  end
+
+  class SOAPInterface
 
     # @!group Low-Level SOAP Wrapper
 
@@ -144,7 +90,7 @@ module DeepSecurity
     # RETURNS
     #   The Web Service API version.
     def getApiVersion
-      send_soap(:get_api_version).to_i
+      send_soap(:get_api_version)
     end
 
     # Retrieve the Manager Web Service API version. Not the same as the Manager version.
@@ -157,7 +103,7 @@ module DeepSecurity
     # RETURNS
     #   Manager time as a language localized object. For example, a Java client would return a Calendar object, and a C# client would return a DataTime object.
     def getManagerTime
-      Time.parse(send_soap(:get_manager_time))
+      send_soap(:get_manager_time)
     end
 
     # Authenticates a user for and returns a session ID for use when calling other Web Service methods.
@@ -172,7 +118,7 @@ module DeepSecurity
     # RETURNS
     #   Authenticated user session ID.
     def authenticate(username, password)
-      send_soap(:authenticate, {:username => username, :password => password}).to_s
+      send_soap(:authenticate, {:username => username, :password => password})
     end
 
     # Authenticates a user within the given tenant, and returns a session ID for use when calling other methods of Manager. When no longer required, the session should be terminated by calling endSession.
@@ -187,8 +133,8 @@ module DeepSecurity
     #
     # RETURNS
     #   Authenticated user session ID.
-    def authenticate_tenant(tenantName, username, password)
-      send_soap(:authenticate_tenant, {:tenantName => tenantName, :username => username, :password => password}).to_s
+    def authenticateTenant(tenantName, username, password)
+      send_soap(:authenticate_tenant, {:tenantName => tenantName, :username => username, :password => password})
     end
 
     # Ends an authenticated user session. The Web Service client should end the authentication session in all exit cases.
@@ -199,25 +145,12 @@ module DeepSecurity
     # PARAMETERS
     #   sID Authentication session identifier ID.
     # RETURNS
-    def end_session(sID = dsm.sID)
+    def endSession(sID = manager.sID)
       send_soap(:end_session, :sID => sID)
     end
 
     # @!endgroup
 
-    # Check if the session has been authenticated.
-    def authenticated?
-      !@sID.nil?
-    end
-
-    def sID
-      raise DeepSecurity::AuthenticationRequiredException unless authenticated?
-      @sID
-    end
-
-    def client
-      @client
-    end
-
   end
+
 end