Nessus6 0.1.1 → 0.1.2

data/lib/Nessus6/group.rb

@@ -0,0 +1,115 @@
+require 'json'
+require 'Nessus6/errors/internal_server_error' # 500
+require 'Nessus6/errors/forbidden' # 403
+require 'Nessus6/errors/bad_request' # 400
+require 'Nessus6/errors/not_found' # 404
+require 'Nessus6/errors/unknown'
+
+module Nessus6
+  # The Groups class is for interacting with Nessus6 user groups. Groups are
+  # utilized to make sharing easier.
+  # https://localhost:8834/api#/resources/groups
+  class Group
+    include Nessus6::Verification
+
+    public
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Add a user to the group. This request requires administrator user
+    # permissions.
+    #
+    # @param group_id [String, Fixnum] The unique id of the group.
+    # @param user_id [String, Fixnum] The unique id of the user.
+    # @return [Hash]
+    def add_user(group_id, user_id)
+      response = @client.post("groups/#{group_id}/users/#{user_id}")
+      verify response,
+             forbidden: 'You do not have permission to add users to a group',
+             not_found: 'Group or user does not exist',
+             internal_server_error: 'Server failed to add the user to the group'
+    end
+
+    # Create a group. This request requires administrator user
+    # permissions.
+    #
+    # @param name [String, Fixnum] The name of the group.
+    # @return [Hash]
+    def create(name)
+      response = @client.post('groups', name: name)
+      verify response,
+             bad_request: 'Field is invalid',
+             forbidden: 'You do not have permission to create a group',
+             internal_server_error: 'Server failed to create the group'
+    end
+
+    # Delete a group. This request requires administrator user
+    # permissions.
+    #
+    # @param group_id [String, Fixnum] The unique id of the group.
+    # @return [Hash]
+    def delete(group_id)
+      response = @client.delete("groups/#{group_id}")
+      verify response,
+             bad_request: 'Group does not exist',
+             forbidden: 'You do not have permission to delete the group',
+             internal_server_error: 'Server failed to delete the group'
+    end
+
+    # Deletes a user from the group. This request requires administrator user
+    # permissions.
+    #
+    # @param group_id [String, Fixnum] The unique id of the group.
+    # @param user_id [String, Fixnum] The unique id of the user.
+    # @return [Hash]
+    def delete_user(group_id, user_id)
+      response = @client.delete("groups/#{group_id}/users/#{user_id}")
+      verify response,
+             forbidden: 'You do not have permission to delete users from a '\
+                        'group',
+             not_found: 'Group or user does not exist',
+             internal_server_error: 'Server failed to remove the user from '\
+                                    'the group'
+    end
+
+    # Edit a group. This request requires administrator user permissions.
+    #
+    # @param group_id [String, Fixnum] The unique id of the group.
+    # @param name [String] The name of the group.
+    # @return [Hash]
+    def edit(group_id, name)
+      response = @client.put("groups/#{group_id}", name: name)
+      verify response,
+             bad_request: 'Field is invalid',
+             forbidden: 'You do not have permission to edit a group',
+             not_found: 'Group does not exist',
+             internal_server_error: 'Server failed to edit / rename the group'
+    end
+
+    alias_method :rename, :edit
+
+    # Returns the group list. This request requires read-only user permissions.
+    #
+    # @return [Hash]
+    def list
+      response = @client.get('groups')
+      verify response,
+             forbidden: 'You do not have permission to view the groups list'
+    end
+
+    # Return the group user list. This request requires administrator user
+    # permissions.
+    #
+    # @param group_id [String, Fixnum] The unique id of the group.
+    # @return [Hash]
+    def list_users(group_id)
+      response = @client.get("groups/#{group_id}/users")
+      verify response,
+             forbidden: 'You do not have permission to view the groups users '\
+                        'list',
+             not_found: 'Group does not exist'
+    end
+  end
+end

data/lib/Nessus6/permission.rb

@@ -0,0 +1,46 @@
+require 'json'
+require 'Nessus6/errors/forbidden' # 403
+require 'Nessus6/errors/not_found' # 404
+require 'Nessus6/errors/unknown'
+
+module Nessus6
+  # The Permissions class is for interacting with Nessus6 user permissions.
+  # Permissions are used to provide access rights to a given object.
+  # https://localhost:8834/api#/resources/permissions
+  class Permission
+    include Nessus6::Verification
+
+    public
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Changes the permissions for an object.
+    #
+    # @param object_type [String] The type of object.
+    # @param object_id [String, Fixnum] The unique id of the object.
+    # @param permissions [String] An array of permission resources to apply
+    #   to the object.
+    # @return [Hash]
+    def change(object_type, object_id, permissions)
+      response = @client.put("permissions/#{object_type}/#{object_id}",
+                             body: permissions)
+      verify response,
+             forbidden: 'You do not have permission to edit the object',
+             not_found: 'Object does not exist'
+    end
+
+    # Returns the current object's permissions.
+    #
+    # @param object_type [String] The type of object.
+    # @param object_id [String, Fixnum] The unique id of the object.
+    # @return [Hash]
+    def list(object_type, object_id)
+      response = @client.get("permissions/#{object_type}/#{object_id}")
+      verify response,
+             forbidden: 'You do not have permission to view the object',
+             not_found: 'Object does not exist'
+    end
+  end
+end

data/lib/Nessus6/scan.rb

@@ -0,0 +1,135 @@
+require 'json'
+require 'Nessus6/errors/forbidden' # 403
+require 'Nessus6/errors/not_found' # 404
+require 'Nessus6/errors/conflict' # 409
+require 'Nessus6/errors/internal_server_error' # 500
+require 'Nessus6/errors/unknown'
+
+module Nessus6
+  # The Scans class is for interacting with Nessus6 scans.
+  # https://localhost:8834/api#/resources/scans
+  class Scan
+    include Nessus6::Verification
+
+    public
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Copies the given scan. Requires can configure scan permissions
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to export.
+    # @param query_params [Hash] Includes:
+    #   :folder_id [String, Fixnum] - The id of the destination folder.
+    #   :history [TrueClass, FalseClass, String] - If true, the history for
+    #     the scan will be copied
+    #   :name [String] - The name of the copied scan
+    # @return [Hash]
+    def copy(scan_id, query_params = nil)
+      if query_params.is_a? Hash
+        response = @client.post "scans/#{scan_id}/copy", query_params
+      else
+        response = @client.post "scans/#{scan_id}/copy"
+      end
+
+      verify response,
+             not_found: 'Scan does not exist.',
+             internal_server_error: 'An error occurred while copying.'
+    end
+
+    # Deletes a scan. NOTE: Scans in running, paused or stopping states can not
+    # be deleted. This request requires can configure scan permissions
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to delete.
+    # @return [Hash] The scan UUID or throws an error
+    def delete(scan_id)
+      response = @client.delete "scans/#{scan_id}"
+      verify response,
+             internal_server_error: 'Failed to delete the scan. This may be ' \
+                                    'because the scan is currently running'
+    end
+
+    # Deletes historical results from a scan. This request requires can
+    # configure scan permissions.
+    #
+    # @param scan_id [String, Fixnum] The id of the scan.
+    # @param query_params [Hash] Includes:
+    #   :history_id [String, Fixnum] - The id of the results to delete.
+    # @return [Hash] The scan UUID or throws an error
+    def delete_history(scan_id, query_params = nil)
+      response = @client.delete "scans/#{scan_id}"
+      verify response,
+             not_found: 'Results were not found.',
+             internal_server_error: 'Failed to delete the results.'
+    end
+
+    # Returns details for the given scan. This request requires can view
+    # scan permissions
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to retrieve
+    # @param history_id [String, Fixnum] The history_id of the historical data
+    #   that should be returned.
+    # @return [Hash] The scan details
+    def details(scan_id, history_id = nil)
+      if history_id.nil?
+        response = @client.get("scans/#{scan_id}")
+      else
+        response = @client.get("scans/#{scan_id}", history_id: history_id)
+      end
+      JSON.parse response.body
+    end
+
+    # Launches a scan.
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to launch.
+    # @param alt_targets [Array] If specified, these targets will be scanned
+    #   instead of the default. Value can be an array where each index is a
+    #   target, or an array with a single index of comma separated targets.
+    # @return [Hash] The scan UUID or throws an error
+    def launch(scan_id, alt_targets = nil)
+      if alt_targets.is_a? Array
+        response = @client.post "scans/#{scan_id}/launch",
+                                alt_targets: alt_targets
+      else
+        response = @client.post "scans/#{scan_id}/launch"
+      end
+
+      verify response,
+             forbidden: 'This scan is disabled.',
+             not_found: 'Scan does not exist.',
+             internal_server_error: 'Failed to launch scan. This is usually '\
+                                    'due to the scan already running.'
+    end
+
+    # Returns the scan list.
+    #
+    # @return [Hash] Returns the scan list.
+    def list
+      response = @client.get 'scans'
+      JSON.parse response.body
+    end
+
+    # Pauses a scan.
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to pause.
+    # @return [Hash] The scan UUID or throws an error
+    def pause(scan_id)
+      response = @client.post "scans/#{scan_id}/pause"
+      verify response,
+             forbidden: 'This scan is disabled.',
+             conflict: 'Scan is not active.'
+    end
+
+    # Stops a scan.
+    #
+    # @param scan_id [String, Fixnum] The id of the scan to stop.
+    # @return [Hash] The scan UUID or throws an error
+    def stop(scan_id)
+      response = @client.post "scans/#{scan_id}/stop"
+      verify response,
+             not_found: 'Scan does not exist.',
+             conflict: 'Scan is not active.'
+    end
+  end
+end

data/lib/Nessus6/session.rb

@@ -0,0 +1,106 @@
+require 'json'
+require 'Nessus6/errors/bad_request'
+require 'Nessus6/errors/forbidden'
+require 'Nessus6/errors/internal_server_error'
+require 'Nessus6/errors/unauthorized'
+require 'Nessus6/errors/unknown'
+
+module Nessus6
+  # The Session class is used to create a session with Nessus6. User sessions
+  # allow us to interact throughout our applications.
+  # https://localhost:8834/api#/resources/session
+  class Session
+    include Nessus6::Verification
+
+    public
+
+    attr_reader :token
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Creates a new session token for the given user.
+    #
+    # @param username [String] The username for the person who is attempting to
+    #   log in.
+    # @param password [String] The password for the person who is attempting to
+    #   log in.
+    # @return [String] The session token
+    def create(username, password)
+      response = @client.post('session',
+                          username: username, password: password)
+      verified = verify response,
+                        bad_request: 'Username format is not valid',
+                        unauthorized: 'Username or password is invalid',
+                        internal_server_error: 'Too many users are connected'
+      @token = verified['token']
+    end
+
+    # Logs the current user out and destroys the session
+    #
+    # @return [Hash]
+    def destroy
+      response = @client.delete('session')
+
+      case response.status_code
+      when 200
+        @token = ''
+        return true
+      when 401
+        fail 'No session exists'
+      else
+        fail UnknownError, 'An unknown error occurred. Please consult Nessus' \
+                           'for further details.'
+      end
+    end
+
+    # Changes settings for the current user.
+    #
+    # @param user [Hash] Representation of the user
+    #   :name [String] Full name of the user
+    #   :email [String] Email address for the user
+    # @return [Hash]
+    def edit(user)
+      if user[:name] && user[:email]
+        response = @client.put('session', name: user[:name],
+                                          email: user[:email])
+      elsif user[:name]
+        response = @client.put('session', name: user[:name])
+      elsif user[:email]
+        response = @client.put('session', email: user[:email])
+      else
+        fail "User's name or email was not provided in hash form."
+      end
+      verify response,
+             forbidden: 'You do not have permission to edit the session data',
+             internal_server_error: 'Server failed to edit the user'
+    end
+
+    # Returns the user session data.
+    #
+    # @return [Hash] The session resource
+    def get
+      verify @client.get('session'),
+             forbidden: 'You do not have permission to view the session data'
+    end
+
+    # Changes password for the current user
+    #
+    # @param new_password [String] New password for the user.
+    # @return [Hash] Returned if the password has been changed
+    def password(new_password)
+      response = @client.put('session/chpasswd', password: new_password)
+      verify response,
+             bad_request: 'Password is too short',
+             unauthorized: 'You do not have permission to change this password',
+             internal_server_error: 'Server failed to change the password'
+    end
+
+    def keys
+      response = @client.put('session/keys')
+      verify response,
+             unauthorized: 'You are not logged in / authenticated'
+    end
+  end
+end

data/lib/Nessus6/user.rb

@@ -0,0 +1,136 @@
+require 'json'
+require 'Nessus6/errors/bad_request'
+require 'Nessus6/errors/conflict'
+require 'Nessus6/errors/forbidden'
+require 'Nessus6/errors/internal_server_error'
+require 'Nessus6/errors/not_found'
+require 'Nessus6/errors/unknown'
+
+module Nessus6
+  # The Users class allows us to interact with Nessus 6 users.
+  # Users can utilize Nessus based on their given role.
+  # https://localhost:8834/api#/resources/users
+  class User
+    include Nessus6::Verification
+
+    public
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Creates a new user. This request requires administrator user permissions.
+    #
+    # @param credentials [Hash] Hash of user credentials
+    #   :username [String] The username of the user
+    #   :password [String] The password of the user
+    # @param user_perm [Hash] The role of the user
+    #   :permissions [String] The role of the user.
+    #   :type [String] The type of user
+    # @param user_info [Hash] Information about the user
+    #   :name [String] The real name of the user
+    #   :email [String] The email address of the user
+    # @return [Hash] The user object
+    def create(credentials, user_perm, user_info = {})
+      new_user = {}.tap do |user|
+        user[:username] = credentials[:username]
+        user[:password] = credentials[:password]
+        user[:permissions] = user_perm[:permissions]
+        user[:type] = user_perm[:type]
+        user[:name] = user_info[:name] if user_info.key?(:name)
+        user[:email] = user_info[:email] if user_info.key?(:email)
+      end
+
+      response = @client.post('users', new_user)
+
+      verify response,
+             bad_request: 'Field is invalid',
+             forbidden: 'You do not have permission to create this user',
+             conflict: 'User already exists'
+    end
+
+    # Deletes a user. This request requires administrator user permissions.
+    #
+    # @param user_id [String, Fixnum] The unique ID of the user
+    # @return [Hash]
+    def delete(user_id)
+      response = @client.delete("users/#{user_id}")
+      verify response,
+             forbidden: 'Not authorized to delete users',
+             not_found: 'You do not have permission to delete this user',
+             conflict: 'Cannot delete your own account',
+             internal_server_error: 'Failed to delete the user due to an '\
+                                    'interal server error'
+    end
+
+    # Edits an existing user. This request requires administrator user
+    # permissions
+    #
+    # @param user_id [String, Fixnum] The unique id of the user
+    # @param permissions [String] The role of the user.
+    # @param user_info [Hash] The user's information
+    #   :name [String] The real name of the user
+    #   :email [String] The email address of the user
+    # @return [Hash]
+    def edit(user_id, permissions, user_info = {})
+      edit_user = {}.tap do |user|
+        user[:permissions] = permissions
+        user[:name] = user_info[:name] if user_info.key?(:name)
+        user[:email] = user_info[:email] if user_info.key?(:email)
+      end
+      response = @client.post("users/#{user_id}", edit_user)
+      verify response,
+             bad_request: 'Field is invalid',
+             forbidden: 'You do not have permission to edit this user',
+             not_found: 'User does not exist',
+             conflict: 'Cannot edit your own permissions'
+    end
+
+    # Returns the details for the given user.
+    #
+    # @param user_id [String, Fixnum] The unique id of the user.
+    # @return [Hash]
+    def get(user_id)
+      response = @client.get("users/#{user_id}")
+      verify response,
+             not_found: 'User does not exist'
+    end
+
+    # Returns the user list.
+    #
+    # @return [Hash] The user list
+    def list
+      response = @client.get('users')
+      verif response,
+            forbidden: 'You do not have permission to view the list'
+    end
+
+    # Changes the password for the given user
+    #
+    # @param user_id [String, Fixnum] The unique id of the user
+    # @param new_password [String] New password for the user
+    # @return [Hash]
+    def password(user_id, new_password)
+      response = @client.post("users/#{user_id}/chpasswd",
+                              password: new_password)
+      verify response,
+             bad_request: 'Password is too short',
+             forbidden: 'You do not have permission to change the users '\
+                        'password',
+             not_found: 'User does not exist',
+             internal_server_error: 'Server failed to change the password'
+    end
+
+    # Generates the API Keys for the given user.
+    #
+    # @param user_id [String, Integer] The unqiue id of the user
+    # @return [Hash] The :accessKey and the :secretKey for the user
+    def keys(user_id)
+      response = @client.get("users/#{user_id}/keys")
+      verify response,
+             forbidden: 'You do not have permission to generate API keys',
+             not_found: 'User does not exist',
+             internal_server_error: 'Server failed to change the keys'
+    end
+  end
+end