nexpose 0.2.8 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8303bf73cfbd73693c68670f4dd448eccc8c2a0
-  data.tar.gz: b28294ca9658ae322e759a851ad13fa35d2bf06e
+  metadata.gz: 096649e7275b4dd061fab3b7331e93f66fdec709
+  data.tar.gz: 483e8f15738e9b4297a702ee07c78b9f75381f6a
 SHA512:
-  metadata.gz: b58c671197ce229fb7518f2cfd7ee02940931bee4c9e5a832ae54737600331f2e831ea085b4ec2b9c5d90380e9f0ca37b3534dc0c9c6ee0802b3397c96ef549a
-  data.tar.gz: 7423eb92c736ef27cd5273bdc079dbf9806845663c98d7bd79197d79660ebab8187d80110b145ac70c385644caa33b88bbff5211e0f8ab4deda787d02e372c41
+  metadata.gz: 368763434ec2b93e957cbf596b36eeeddad7728170234dee6eaa72155e30f11d3826bc7503e22952005f2f10b6bc9cce0ad39769355cd1aeff59082d107db335
+  data.tar.gz: a02679981f17023624c99887fd2c9677678c6e1148a302c0aa7e0b1ce17c292bad83810c6a56da2e4614853fd009702a740f5d87fb41eb935a18359592a233ad

data/lib/nexpose.rb

@@ -3,7 +3,7 @@
 #
 =begin
 
-Copyright (C) 2009-2012, Rapid7 LLC
+Copyright (C) 2009-2013, Rapid7 LLC
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -54,25 +54,34 @@ require 'net/http'
 require 'uri'
 require 'rex/mime'
 require 'ipaddr'
+require 'json'
 require 'nexpose/error'
 require 'nexpose/util'
-require 'nexpose/user'
+require 'nexpose/alert'
+require 'nexpose/ajax'
 require 'nexpose/api_request'
+require 'nexpose/common'
+require 'nexpose/creds'
+require 'nexpose/data_table'
+require 'nexpose/device'
+require 'nexpose/engine'
+require 'nexpose/filter'
+require 'nexpose/group'
+require 'nexpose/dag'
 require 'nexpose/manage'
-require 'nexpose/misc'
+require 'nexpose/pool'
 require 'nexpose/report'
+require 'nexpose/report_template'
+require 'nexpose/role'
 require 'nexpose/scan'
-require 'nexpose/scan_engine'
+require 'nexpose/scan_template'
 require 'nexpose/silo'
 require 'nexpose/site'
 require 'nexpose/ticket'
+require 'nexpose/user'
 require 'nexpose/vuln'
-require 'nexpose/creds'
+require 'nexpose/vuln_exception'
 require 'nexpose/connection'
-require 'nexpose/role'
-require 'nexpose/common'
-require 'nexpose/group'
-require 'nexpose/alert'
 
 module Nexpose
 

data/lib/nexpose/ajax.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+
+module Nexpose
+
+  # Accessor to the Nexpose AJAX API.
+  # These core methods should allow direct access to underlying controllers
+  # in order to test functionality that is not currently exposed
+  # through the XML API.
+  #
+  module AJAX
+    module_function
+
+    # GET call to a Nexpose controller.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [String] content_type Content type to use when issuing the GET.
+    # @return [String|REXML::Document|Hash] The response from the call.
+    #
+    def get(nsc, uri, content_type = 'text/xml; charset=UTF-8')
+      get = Net::HTTP::Get.new(uri)
+      get.set_content_type(content_type)
+      _request(nsc, get)
+    end
+
+    # PUT call to a Nexpose controller.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [String|REXML::Document] payload XML document required by the call.
+    # @param [String] content_type Content type to use when issuing the PUT.
+    # @return [String] The response from the call.
+    #
+    def put(nsc, uri, payload = nil, content_type = 'text/xml; charset=UTF-8')
+      put = Net::HTTP::Put.new(uri)
+      put.set_content_type(content_type)
+      put.body = payload.to_s if payload
+      _request(nsc, put)
+    end
+
+    # POST call to a Nexpose controller.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [String|REXML::Document] payload XML document required by the call.
+    # @param [String] content_type Content type to use when issuing the POST.
+    # @return [String|REXML::Document|Hash] The response from the call.
+    #
+    def post(nsc, uri, payload = nil, content_type = 'text/xml')
+      post = Net::HTTP::Post.new(uri)
+      post.set_content_type(content_type)
+      post.body = payload.to_s if payload
+      _request(nsc, post)
+    end
+
+    # POST call to a Nexpose controller that uses a form-post model.
+    # This is here to support legacy use of POST in old controllers.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [Hash] parameters Hash of attributes that need to be sent
+    #    to the controller.
+    # @param [String] content_type Content type to use when issuing the POST.
+    # @return [Hash] The parsed JSON response from the call.
+    #
+    def form_post(nsc, uri, parameters, content_type = 'application/x-www-form-urlencoded; charset=UTF-8')
+      post = Net::HTTP::Post.new(uri)
+      post.set_content_type(content_type)
+      post.set_form_data(parameters)
+      _request(nsc, post)
+    end
+
+    # DELETE call to a Nexpose controller.
+    #
+    # @param [Connection] nsc API connection to a Nexpose console.
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [String] content_type Content type to use when issuing the DELETE.
+    def delete(nsc, uri, content_type = 'text/xml')
+      delete = Net::HTTP::Delete.new(uri)
+      delete.set_content_type(content_type)
+      _request(nsc, delete)
+    end
+
+    # Append the query parameters to given URI.
+    #
+    # @param [String] uri Controller address relative to https://host:port
+    # @param [Hash] parameters Hash of attributes that need to be sent
+    #    to the controller.
+    # @return [Hash] The parametrized URI.
+
+    def parametrize_uri(uri, parameters)
+      uri = uri.concat(('?').concat(parameters.map { |k, v| "#{k}=#{CGI.escape(v[0].to_s)}" }.join('&'))) if parameters
+    end
+
+    ###
+    # Internal helper methods
+
+    # Use the Nexpose::Connection to establish a correct HTTPS object.
+    def _https(nsc)
+      http = Net::HTTP.new(nsc.host, nsc.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      http
+    end
+
+    # Attach necessary header fields.
+    def _headers(nsc, request)
+      request.add_field('nexposeCCSessionID', nsc.session_id)
+      request.add_field('Cookie', "nexposeCCSessionID=#{nsc.session_id}")
+    end
+
+    def _request(nsc, request)
+      http = _https(nsc)
+      _headers(nsc, request)
+
+      # Return response body if request is successful. Brittle.
+      response = http.request(request)
+      case response
+      when Net::HTTPOK
+        response.body
+      else
+        req_type = request.class.name.split('::').last
+        raise Nexpose::APIError.new(response, "#{req_type} request to #{request.path} failed. #{request.body}")
+      end
+    end
+  end
+end

data/lib/nexpose/alert.rb

@@ -7,21 +7,16 @@ module Nexpose
 
     # Name for this alert.
     attr_accessor :name
-
     # Whether or not this alert is currently active.
     attr_accessor :enabled
-
     # Send at most this many alerts per scan.
     attr_accessor :max_alerts
-
     # Send alerts based upon scan status.
     attr_accessor :scan_filter
-
     # Send alerts based upon vulnerability finding status.
     attr_accessor :vuln_filter
-
     # Alert type and its configuration. One of SMTPAlert, SyslogAlert, SNMPAlert
-    attr_accessor :alert
+    attr_accessor :type
 
     def initialize(name, enabled = 1, max_alerts = -1)
       @name, @enabled, @max_alerts = name, enabled, max_alerts
@@ -29,13 +24,13 @@ module Nexpose
 
     def to_xml
       xml = '<Alert'
-      xml << %Q( name="#{@name}")
-      xml << %Q( enabled="#{@enabled}")
-      xml << %Q( maxAlerts="#{@max_alerts}")
+      xml << %( name="#{@name}")
+      xml << %( enabled="#{@enabled}")
+      xml << %( maxAlerts="#{@max_alerts}")
       xml << '>'
       xml << scan_filter.to_xml
       xml << vuln_filter.to_xml
-      xml << alert.to_xml
+      xml << type.to_xml
       xml << '</Alert>'
     end
 
@@ -43,7 +38,7 @@ module Nexpose
     #
     # @param [REXML::Document] rexml XML document to parse.
     # @return [Alert] Alert object represented by the XML.
-    # 
+    #
     def self.parse(rexml)
       name = rexml.attributes['name']
       rexml.elements.each("//Alert[@name='#{name}']") do |xml|
@@ -53,11 +48,11 @@ module Nexpose
         alert.scan_filter = ScanFilter.parse(REXML::XPath.first(xml, "//Alert[@name='#{name}']/scanFilter"))
         alert.vuln_filter = VulnFilter.parse(REXML::XPath.first(xml, "//Alert[@name='#{name}']/vulnFilter"))
         if (type = REXML::XPath.first(xml, "//Alert[@name='#{name}']/smtpAlert"))
-          alert.alert = SMTPAlert.parse(type)
+          alert.type = SMTPAlert.parse(type)
         elsif (type = REXML::XPath.first(xml, "//Alert[@name='#{name}']/syslogAlert"))
-          alert.alert = SyslogAlert.parse(type)
+          alert.type = SyslogAlert.parse(type)
         elsif (type = REXML::XPath.first(xml, "//Alert[@name='#{name}']/snmpAlert"))
-          alert.alert = SNMPAlert.parse(type)
+          alert.type = SNMPAlert.parse(type)
         end
         return alert
       end
@@ -78,11 +73,11 @@ module Nexpose
 
     def to_xml
       xml = '<scanFilter'
-      xml << %Q( scanStart="#{@start}")
-      xml << %Q( scanStop="#{@stop}")
-      xml << %Q( scanFailed="#{@fail}")
-      xml << %Q( scanResumed="#{@resume}")
-      xml << %Q( scanPaused="#{@pause}")
+      xml << %( scanStart="#{@start}")
+      xml << %( scanStop="#{@stop}")
+      xml << %( scanFailed="#{@fail}")
+      xml << %( scanResumed="#{@resume}")
+      xml << %( scanPaused="#{@pause}")
       xml << '/>'
     end
 
@@ -99,6 +94,7 @@ module Nexpose
   # Set values to 1 to enable and 0 to disable.
   #
   class VulnFilter
+
     # Only alert on vulnerability findings with a severity level greater than this level.
     # Range is 0 to 10.
     # Values in the UI correspond as follows:
@@ -116,10 +112,10 @@ module Nexpose
 
     def to_xml
       xml = '<vulnFilter'
-      xml << %Q( severityThreshold="#{@severity}")
-      xml << %Q( confirmed="#{@confirmed}")
-      xml << %Q( unconfirmed="#{@unconfirmed}")
-      xml << %Q( potential="#{@potential}")
+      xml << %( severityThreshold="#{@severity}")
+      xml << %( confirmed="#{@confirmed}")
+      xml << %( unconfirmed="#{@unconfirmed}")
+      xml << %( potential="#{@potential}")
       xml << '/>'
     end
 
@@ -151,7 +147,7 @@ module Nexpose
 
     def to_xml
       xml = '<syslogAlert'
-      xml << %Q( server="#{replace_entities(server)}">)
+      xml << %( server="#{replace_entities(server)}">)
       xml << '</syslogAlert>'
     end
   end
@@ -180,8 +176,8 @@ module Nexpose
 
     def to_xml
       xml = '<snmpAlert'
-      xml << %Q( community="#{replace_entities(community)}")
-      xml << %Q( server="#{replace_entities(server)}">)
+      xml << %( community="#{replace_entities(community)}")
+      xml << %( server="#{replace_entities(server)}">)
       xml << '</snmpAlert>'
     end
   end
@@ -191,15 +187,12 @@ module Nexpose
   #
   class SMTPAlert
 
-    # The email address of the sender
+    # The e-mail address of the sender.
     attr_accessor :sender
-
-    # The server to sent this alert
+    # The server to sent this alert.
     attr_accessor :server
-
-    # Limit the text for mobile devices
+    # Limit the text for mobile devices.
     attr_accessor :limit_text
-
     # Array of strings with the e-mail addresses of the intended recipients.
     attr_accessor :recipients
 
@@ -210,7 +203,7 @@ module Nexpose
       @recipients = []
     end
 
-    # Adds a new Recipient to the recipients array
+    # Adds a new recipient to the alert.
     def add_recipient(recipient)
       @recipients << recipient
     end
@@ -219,9 +212,9 @@ module Nexpose
 
     def to_xml
       xml = '<smtpAlert'
-      xml << %Q( sender="#{replace_entities(sender)}")
-      xml << %Q( server="#{replace_entities(server)}")
-      xml << %Q( limitText="#{limit_text}">)
+      xml << %( sender="#{replace_entities(sender)}")
+      xml << %( server="#{replace_entities(server)}")
+      xml << %( limitText="#{limit_text}">)
       recipients.each do |recpt|
         xml << "<recipient>#{replace_entities(recpt)}</recipient>"
       end

data/lib/nexpose/common.rb

@@ -27,6 +27,7 @@ module Nexpose
   # the application will send reports via e-mail to access-list members and
   # non-members.
   class Email
+
     # Send as file attachment or zipped file to individuals who are not members
     # of the report access list. One of: file|zip
     attr_accessor :send_as
@@ -55,17 +56,17 @@ module Nexpose
 
     def to_xml
       xml = '<Email'
-      xml << %Q{ toAllAuthorized='#{@toAllAuthorized ? 1 : 0}'}
-      xml << %Q{ sendToOwnerAs='#{@send_to_owner_as}'} if @send_to_owner_as
-      xml << %Q{ sendToAclAs='#{@send_to_acl_as}'} if @send_to_acl_as
-      xml << %Q{ sendAs='#{@send_as}'} if @send_as
+      xml << %( toAllAuthorized='#{@toAllAuthorized ? 1 : 0}')
+      xml << %( sendToOwnerAs='#{@send_to_owner_as}') if @send_to_owner_as
+      xml << %( sendToAclAs='#{@send_to_acl_as}') if @send_to_acl_as
+      xml << %( sendAs='#{@send_as}') if @send_as
       xml << '>'
-      xml << %Q{<Sender>#{@sender}</Sender>} if @sender
-      xml << %Q{<SmtpRelayServer>#{@smtp_relay_server}</SmtpRelayServer>} if @smtp_relay_server
+      xml << %(<Sender>#{@sender}</Sender>) if @sender
+      xml << %(<SmtpRelayServer>#{@smtp_relay_server}</SmtpRelayServer>) if @smtp_relay_server
       if @recipients
         xml << '<Recipients>'
         @recipients.each do |recipient|
-          xml << %Q{<Recipient>#{recipient}</Recipient>}
+          xml << %(<Recipient>#{recipient}</Recipient>)
         end
         xml << '</Recipients>'
       end
@@ -121,11 +122,11 @@ module Nexpose
     end
 
     def to_xml
-      xml = %Q{<Schedule enabled='#{@enabled ? 1 : 0}' type='#{@type}' interval='#{@interval}' start='#{@start}'}
-      xml << %Q{ maxDuration='#@max_duration'} if @max_duration
-      xml << %Q{ notValidAfter='#@not_valid_after'} if @not_valid_after
-      xml << %Q{ incremental='#{@incremental ? 1 : 0}'} if @incremental
-      xml << %Q{ repeaterType='#@repeater_type'} if @repeater_type
+      xml = %(<Schedule enabled='#{@enabled ? 1 : 0}' type='#{@type}' interval='#{@interval}' start='#{@start}')
+      xml << %( maxDuration='#{@max_duration}') if @max_duration
+      xml << %( notValidAfter='#{@not_valid_after}') if @not_valid_after
+      xml << %( incremental='#{@incremental ? 1 : 0}') if @incremental
+      xml << %( repeaterType='#{@repeater_type}') if @repeater_type
       xml << '/>'
     end
 

data/lib/nexpose/connection.rb

@@ -4,9 +4,12 @@ module Nexpose
   # Object that represents a connection to a Nexpose Security Console.
   #
   # === Examples
-  #   # Create a new Nexpose Connection on the default port
+  #   # Create a new Nexpose::Connection on the default port
   #   nsc = Connection.new('10.1.40.10', 'nxadmin', 'password')
   #
+  #   # Create a new Nexpose::Connection from a URI or "URI" String
+  #   nsc = Connection.from_uri('https://10.1.40.10:3780', 'nxadmin', 'password')
+  #
   #   # Login to NSC and Establish a Session ID
   #   nsc.login
   #
@@ -17,7 +20,7 @@ module Nexpose
   #       puts 'Login Failure'
   #   end
   #
-  #   # //Logout
+  #   # Logout
   #   logout_success = nsc.logout
   #
   class Connection
@@ -42,7 +45,13 @@ module Nexpose
     # The last XML response received by this object, useful for debugging.
     attr_reader :response_xml
 
-    # Constructor for Connection
+    # A constructor to load a Connection object from a URI
+    def self.from_uri(uri, user, pass, silo_id = nil)
+      uri = URI.parse(uri)
+      new(uri.host, user, pass, uri.port, silo_id)
+    end
+
+    # A constructor for Connection
     def initialize(ip, user, pass, port = 3780, silo_id = nil)
       @host = ip
       @port = port
@@ -57,25 +66,21 @@ module Nexpose
     def login
       begin
         login_hash = {'sync-id' => 0, 'password' => @password, 'user-id' => @username}
-        unless @silo_id.nil?
-          login_hash['silo-id'] = @silo_id
-        end
+        login_hash['silo-id'] = @silo_id if @silo_id
         r = execute(make_xml('LoginRequest', login_hash))
+        if r.success
+          @session_id = r.sid
+          true
+        end
       rescue APIError
         raise AuthenticationFailed.new(r)
       end
-      if (r.success)
-        @session_id = r.sid
-        true
-      end
     end
 
     # Logout of the current connection
     def logout
       r = execute(make_xml('LogoutRequest', {'sync-id' => 0}))
-      if (r.success)
-        return true
-      end
+      return true if r.success
       raise APIError.new(r, 'Logout failed')
     end