nexpose_scan_manager 0.0.1 → 0.0.2

data/doc/user-guide.txt

@@ -0,0 +1,39 @@
+Usage:
+
+The Scan Manager can be used to:
+
+A. MONITOR A SCAN
+
+# Create a NeXpose API Connection
+nexpose_connection = NeXpose::Connection.new host, username, password, port
+
+# Initialize the scan manager
+# Poll NeXpose every 5 seconds for the scan status
+poll_time = 5
+scan_manager = ScanManager.new nexpose_connection, false, poll__time
+
+# Add your observing class to the scan manager that defines an update method
+# scan_data contains the scan ID, status, and message if any
+class ScanObserver
+    def update scan_data, notifier
+       <do whatever with scan_data>
+    end
+end
+
+scan_observer = ScanObserver.new
+scan_manager.add_observer scan_observer
+
+
+B. START A RESTRICTIVE SCAN
+
+# Define the condition
+
+conditional_scan =
+    {
+        :site_id   => <site ID>,
+        :max_scans => 5,   # Only start scan if there are less than 5 scans running
+        :devices   => <array of devices>, # IPs
+        :listeners => listeners # Can be null or an observer as defined in A
+    }
+
+scan_manager.add_conditional_device_scan conditional_scan

data/lib/scan_manager.rb

@@ -4,14 +4,15 @@ require 'thread'
 require 'observer'
 require 'nexpose'
 
-#------------------------------------------------------------------------------------------------------
-# Used to start site device scans where a user is able to specify the maximum amount of scans that
-# should be running at a time.  This class does not guarantee that there will be no more than the
-# maximum amount of scans specified will be running BUT scans will not be started from this class
-# until the current amount of scans running is less than or equal to the maximum.
-#
-# This class is also used to
-#------------------------------------------------------------------------------------------------------
+=begin rdoc
+ Used to start site device scans where a user is able to specify the maximum amount of scans that
+ should be running at a time.  This class does not guarantee that there will be no more than the
+ maximum amount of scans specified will be running BUT scans will not be started from this class
+ until the current amount of scans running is less than or equal to the maximum.
+
+ This class can also be used to monitor the state of a running scan.
+=end
+
 class ScanManager
   include Observable
 
@@ -106,14 +107,14 @@ class ScanManager
 
   public
 
-    #------------------------------------------------------------------------------------------------------
+    #
     # The poller thread used within this class is initialized here.
     #
     # nexpose_conn: The NeXpose API object
     # poler_exit_on_completion: 'true', if the poller thread should exit when
     # when there is nothing left to process.
     # period: The frequency at which the poller thread executes
-    #------------------------------------------------------------------------------------------------------
+    #
     def initialize nexpose_conn, poler_exit_on_completion, period
       @nexpose_conn = nexpose_conn
       @period = period
@@ -126,30 +127,29 @@ class ScanManager
       start_poller
     end
 
-    #------------------------------------------------------------------------------------------------------
+    #
     # Adds a scan to be observed
     # scan_id: The ID of the scan to be observed.
-    #------------------------------------------------------------------------------------------------------
+    #
     def add_scan_observed scan_id
       puts "Obeserving scan #{scan_id}"
       @scans_observed << scan_id
     end
 
-    #------------------------------------------------------------------------------------------------------
+    #
     # Removes a currently observed scan
     # scan_id: The ID of the scan to be removed.
-    #------------------------------------------------------------------------------------------------------
+    #
     def remover_scan_observed scan_id
       @scans_observed.delete scan_id 
     end
 
-    #------------------------------------------------------------------------------------------------------
+    #
     # Starts device site scans based on a particular condition, for now this is if the max amount of scans
     # specified is greater than the amount of currently running scans.
     #
     # conditional_scan: A hash of informations used to start scanning
     # ie : @[0] -> :site_id => 1 :devices => [192.168.1.1] :max_scans => 5 :listeners => [listerner_objects]
-  #-------------------------------------------------------------------------------------------------------
   def add_cond_scan conditional_scan
     if conditional_scan.nil?
       raise ArgumentError 'Condtional scan arguement is null'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexpose_scan_manager
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nexpose
-  requirement: &27094380 !ruby/object:Gem::Requirement
+  requirement: &27133608 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: 0.0.3
   type: :runtime
   prerelease: false
-  version_requirements: *27094380
+  version_requirements: *27133608
 - !ruby/object:Gem::Dependency
   name: eventmachine-eventmachine
-  requirement: &27093600 !ruby/object:Gem::Requirement
+  requirement: &27132696 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,14 +33,16 @@ dependencies:
         version: 0.12.9
   type: :runtime
   prerelease: false
-  version_requirements: *27093600
-description: 
+  version_requirements: *27132696
+description: ! "\tUsed for to start a managed scan and monitor their activity\n"
 email: christopher_lee@rapid7.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- doc/user-guide.txt
 files:
 - lib/scan_manager.rb
+- doc/user-guide.txt
 has_rdoc: true
 homepage: 
 licenses: []