nessus_client 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dda4cc05fbcee8eac14f8469f106944fa356ec74ecb31e3623c13338ec175f9
-  data.tar.gz: db9270a96eb7866357754b65e1d3e17c0c67d9fdc98e5d507104a44fee49ef31
+  metadata.gz: 34cd232810e228f40b9badc3c3c38cd8ca0a4481baf376df4ff37f9f308af34b
+  data.tar.gz: 2c9fd0c05537ecf3aad03fb9c4e5f2abf7fde7eb3f1f805edcde53a3a025efe3
 SHA512:
-  metadata.gz: d8c172bec3e3039644a3352dfa279e3799153351936b3d4b9ac86d90e87a31d9d151480e34ef7eb742258b77fdeb28066224216c07ae5a2cf31c9fb5771f8e8b
-  data.tar.gz: 74dff229a778e97680bde8f690c845e84767b3da1847459577a377d2cfea2febc35f53c8fd1aac1befce5138c450cc7092c3b71d5f35cd840edd516dd4012461
+  metadata.gz: 29d460bc57991e7c9d162c77fd7efb247f6a6e68da82867dce865272497ba9b4a95d4214f73518498374cc680b64a4f69c78047d16ebbe85684c8b009066cccc
+  data.tar.gz: 6d4ce3058ec4c3cf6cf78a5b0041f0f02ce5adb1e02f6f3a3202a5ef5147197d0521d12673cac4976c05d2a97b0d468b8cf784e90fbd7f8414afd7ed100eeee3

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+
+## Contributing
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/README.md

@@ -1,14 +1,18 @@
-NessusApi
+NessusClient
 =========
-**Ruby wrapper for Nessus API**
 
-  * [Source Code]
-  * [API documentation]
-  * [Changelog]
-  * [Rubygem]
+Usable, fast, simple Ruby gem for Tenable Nessus Pro v6.x and v7.x
 
+NessusClient was designed to be simple, fast and performant through communication with Nessus over REST interface.
+
+[![Gem Version](https://badge.fury.io/rb/nessus_client.svg)](https://badge.fury.io/rb/nessus_client) [![codecov](https://codecov.io/gh/heyder/nessus_api/branch/master/graph/badge.svg)](https://codecov.io/gh/heyder/nessus_api) [![Inline docs](http://inch-ci.org/github/heyder/nessus_client.svg?branch=master)](http://inch-ci.org/github/heyder/nessus_client)
+
+**Ruby gem for Nessus API**
+
+  * [Source Code](https://github.com/heyder/nessus_client)
+  * [API documentation](https://rubydoc.info/github/heyder/nessus_client/master)
+  * [Rubygem](https://rubygems.org/gems/nessus_client)
 
-Ruby wrapper for Nessus API (all verions)
 
 ## Contact
 
@@ -22,8 +26,57 @@ with some common problems to check out before creating an issue.
 Getting started
 ---------------
 
+```ruby
+require 'nessus_client'
+
+nc = NessusClient.new(
+  {
+    :uri=>'https://localhost:8834', 
+    :username=>'user',
+    :password=> 'password'
+  }
+)
+scan_uuid = nc.launch_by_name('scan_name',['192.168.10.0/28'])
+
+while true do
+ scan_status = Oj.load( nc.scan_details( scan_uuid ) )["info"]["status"] 
+  if scan_status == "done"
+    export_id = nc.export_request( scan_uuid )
+    while true do
+      export_status = Oj.load( nc.export_status( export_id ) )["status"]
+      if export_status == "ready"
+        open("scan_report", "wb") do |file|
+          file.write(nc.export_download( scan_uuid ))
+        end
+        break  
+      end
+    end
+ end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nessus_client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nessus_client
+
+## Requirements
 
+Requirements are Exon for HTTP(S) and Oj parsing:
 
+```ruby
+require 'excon'
+require 'oj'
+```
 
 ## Code of Conduct
 

data/lib/modules/exports.rb

@@ -1,15 +1,37 @@
 # require_relative '../nessus_client/request'
 
 module NessusClient::Exports
- # export scans
+
+  # Reques a export of vulnerabilities scan.
+  # @param [String] scan_id The export uuid string.
+  # @param [String] format The export format.This
+  #   can be `nessus` or `nessus_db`.
+  # @return [JSON]  
   def export_request( scan_id, format )
     params = {:format => format }
-    self.request.post("/scans/#{scan_id}/export", params)
+    self.request.post( "/scans/#{scan_id}/export", params )
   end
+
+  # Check the status of a export request
+  # @param [String] export_id The export uuid string.
+  # @return [JSON] 
+  # @example Checking the status of a export.
+  #   export_status = nc.export_status( "73376c41-1508-46b7-8587-483d159cd956" )
+  #   return true if export_status["status"] == "ready"
   def export_status( export_id )
-    self.request.get("/tokens/#{export_id}/status")
+    self.request.get( "/tokens/#{export_id}/status" )
   end
+
+  # Download a vulnerabities scan output.
+  # @param [String] export_id The export uuid string.
+  # @return (see #format)
+  # @example Download a ready export.
+  #   export = nc.export_download("73376c41-1508-46b7-8587-483d159cd956")
+  #   open("scan_report", "wb") do |file|
+  #     file.write( export )
+  #   end
   def export_download( export_id )
-    self.request.get("/tokens/#{export_id}/download")
+    self.request.get( "/tokens/#{export_id}/download" )
   end
+
 end

data/lib/modules/folders.rb

@@ -1,10 +1,14 @@
 # require_relative '../nessus_client/request'
 
 module NessusClient::Folders
-# folders
+  # Get the list of folders from the endpoint.
+  # @return [JSON]
   def list_folders
     self.request.get("/folders")
   end
+  # Create a folder into the endpoint.
+  # @param [String] folder_name The name of the folder the will be created.
+  # @return [Json]
   def create_folder( folder_name )
     params = {:name => folder_name }.to_json
     self.request.post("/folders", params)

data/lib/modules/policies.rb

@@ -1,6 +1,8 @@
 # require_relative '../nessus_client/request'
 
 module NessusClient::Policies
+  # List the scan polices from the endpoint.
+  # @return [JSON]
   def policies
     self.request.get( "/policies" )
   end

data/lib/modules/scans.rb

@@ -1,26 +1,41 @@
 
 module NessusClient::Scans
 
+  # List scans from the endpoint.
+  # @param [String] folder_id (nil) The name of a alredy created scan.
+  # @return [JSON]
   def list_scans( folder_id=nil )
     query = folder_id.nil? ? nil : { "folder_id" => folder_id }
     self.request.get( "/scans", nil, query )
   end
   alias_method :scans, :list_scans 
 
+  # See details of a scan.
+  # @param [String] scan_id The `uuid` of a scan.
+  # @param [String] history_id (nil) The `history_id` of a scan.
+  # @return [JSON]
   def scan_details( scan_id, history_id=nil )
     query = history_id.nil? ? nil : { "history_id" => history_id }
     self.request.get( "/scans/#{scan_id}", nil, query )
   end
 
+  # Lauch a scan by its name
+  # @param [String] scan_name The name of a alredy created scan.
+  # @param [Array<String>] targets Comma separeted new target to be scanned.
+  # @return [JSON]
   def launch_by_name( scan_name, targets=[] )
     scan_id = get_scan_by_name( scan_name )
     params = { :alt_targets => targets } unless targets.empty?
     self.request.post( "/scans/#{scan_id}/launch", params )
   end
 
-  def get_scan_by_name( folder_id=nil, name )
+  # Get a scan by its name
+  # @param [String] folder_id The id of the folder to look into.
+  # @param [String] scan_name The name of the scan to look for.
+  # @return [String, nil] The uuid of the scan.
+  def get_scan_by_name( folder_id=nil, scan_name )
     Oj.load(list_scans( folder_id ))["scans"].each do |scan|
-      return scan['id'] if scan['name'] == name
+      return scan['id'] if scan['name'] == scan_name
     end
   end
   

data/lib/modules/session.rb

@@ -0,0 +1,56 @@
+require 'oj'
+# require_relative 'request'
+# require_relative 'exception'
+
+# Abstract base class for NessusClient Session. 
+# @since 0.1.0
+# @attr_reader [String] token Autentication session token.
+# @attr_reader [String] api_token Autentication API token.
+module NessusClient::Session
+
+  attr_reader :token, :api_token
+
+  @token = @api_token  = nil
+
+  # Autenticate into Nessus endpoint.
+  # @param [String] username
+  # @param [String] password
+  # @raise [NessusClient::Error] Unable to authenticate.
+  # @todo Validate response token format
+  def set_session( username, password )
+    
+    payload = {
+      username: username,
+      password: password,
+    }
+
+    response = self.request.post( '/session', payload )
+    response = Oj.load(response) if response.length > 0
+
+    raise NessusClient::Error.new( "Unable to authenticate. The response did not include a session token." ) unless response['token']
+    
+    @token = response['token']
+  
+  end
+  alias_method :session_create, :set_session
+
+  # Set the API Token from legacy Nessus version
+  # @raise [NessusClient::Error] Unable to get API Token.
+  def set_api_token
+    response = self.request.get( "/nessus6.js" )
+    response.match( %r{return"(\w{8}-(?:\w{4}-){3}\w{12})"\}} )
+    
+    raise NessusClient::Error.new( "Unable to get API Token. Some features won't work." ) unless $1#.nil?
+    
+    @api_token = $1 
+    
+  end
+
+  # Destroy the current session from Nessus endpoint
+  def destroy
+    self.request.delete( '/session', nil )
+    @token = nil
+  end
+  alias_method :logout , :destroy
+
+end

data/lib/nessus_client.rb

@@ -1,4 +1,3 @@
-# require 'pry'
 require_relative 'nessus_client/version'
 require_relative 'nessus_client/exception'
 
@@ -8,32 +7,43 @@ class NessusClient
 
   attr_reader :request, :session
   
+  include NessusClient::Session
   include NessusClient::Scans
   include NessusClient::Exports
   include NessusClient::Folders
   include NessusClient::Policies
 
   autoload :Request, "nessus_client/request"
-  autoload :Session, "nessus_client/session"
+  # autoload :Session, "nessus_client/session"
 
-  def initialize( params={uri: nil, username: nil, password: nil, :ssl_verify_peer => false} )
+  # @param [Hash] params the options to create a NessusClient with.
+  # @option params [String] :uri ('https://localhost:8834/') Nessus endpoint to connect with
+  # @option params [String] :username Username (nil) to use in the connection
+  # @option params [String] :password Password (nil) to use in the connection
+  # @option params [String] :ssl_verify_peer (false) should check whether valid SSL certificate
+  def initialize( params = {} )
     @has_session = false
+    default_params = { 
+      uri: 'https://localhost:8834/', 
+      username: nil, 
+      password: nil, 
+      ssl_verify_peer: false
+    }
+    params = default_params.merge( params )
     req_params = params.select {|key, value| [:uri, :ssl_verify_peer].include?(key) } 
-    # session_params = params.select {|key, value| [:username, :password].include?(key) } 
 
     @request = NessusClient::Request.new( req_params )
-    @session = NessusClient::Session.create( params.fetch(:username), params.fetch(:password) )
+    self.set_session( params.fetch(:username), params.fetch(:password) )
     
-    if @session.token
+    if self.token
       begin
         @has_session = true
-        # NessusClient::Request.headers.update( 'X-Cookie' => 'token=' + api_session.token )
-        @request.headers.update( 'X-Cookie' => 'token=' + @session.token )
-        @session.set_api_token
+        @request.headers.update( 'X-Cookie' => 'token=' + self.token )
+        self.set_api_token
       rescue NessusClient::Error => err
         puts err.message
       else
-        request.headers.update( 'X-API-Token' => @session.api_token )
+        request.headers.update( 'X-API-Token' => self.api_token )
       ensure
         return
       end
@@ -42,10 +52,14 @@ class NessusClient
 
   end
 
+  # Gets NessusClient::Session authentication status.
+  # @return [Boolean]
   def has_session?
     @has_session
   end
 
+  # Gets the server status.
+  # @return [Json] Returns the server status (loading, ready, corrupt-db, feed-expired, eval-expired, locked, register, register-locked, download-failed, feed-error).
   def status
     self.request.get( "/server/status" )
   end

data/lib/nessus_client/exception.rb

@@ -1,4 +1,5 @@
 class NessusClient
+  # Abstract Error class for NessusClient.
   class Error < ::StandardError
     def initialize(msg="message")
       super

data/lib/nessus_client/request.rb

@@ -1,15 +1,14 @@
 require 'excon'
 require 'json'
-# require 'pry'
+
 class NessusClient
 
-  # Excon.defaults[:ssl_verify_peer] = false
-  # This class should be used to in all requests classes
-  
+  # Abstract base class for NessusClient. Provides some helper methods for
   class Request
-    # attr_accessor :headers
+
     attr_reader   :url, :headers
 
+    # Default HTTP header to be used on the requests.
     DEFAULT_HEADERS = {
       "User-Agent" => "Mozilla/5.0 (Linux x86_64)",
       "Content-Type" => "application/json"
@@ -20,27 +19,39 @@ class NessusClient
       @@ssl_verify_peer = params.fetch(:ssl_verify_peer)
       @url = @@url = NessusClient::Request.uri_parse( params.fetch(:uri) )
       @headers = params.fetch( :headers ).merge( DEFAULT_HEADERS )
-    end 
+    end
 
-    # def self.headers
-    #   @@headers
-    # end
+    # @raise [NotImplementedError] Use update from Hash insted.
     def headers=(value)
       raise NotImplementedError.new("Use update from Hash insted.")
     end
- 
+
+    # Perform a HTTP GET to the endpoint.
+    # @param [String] path The URI path to perform the request.
+    # @param [String] payload The HTTP body to send.
+    # @param [String] query The URI query to send.
     def get( path=nil, payload=nil, query=nil )
       http_request( :get, path, payload, query )
     end
 
+    # Perform a HTTP POST to the endpoint.
+    # @param [String] path The URI path to perform the request.
+    # @param [String] payload The HTTP body to send.
+    # @param [String] query The URI query to send.
     def post( path=nil, payload=nil, query=nil )
       http_request( :post, path, payload, query )
     end
 
+    # Perform a HTTP DELETE to the endpoint.
+    # @param [String] path The URI path to perform the request.
+    # @param [String] payload The HTTP body to send.
+    # @param [String] query The URI query to send.
     def delete( path=nil, payload=nil, query=nil )
       http_request( :delete, path, payload, query )
     end
-
+    # Parse a receiveid URI
+    # @param [String] uri A valid URI.
+    # @return [String] A string uri.
     def self.uri_parse( uri )
       url = URI.parse( uri )
       raise URI::InvalidURIError unless url.scheme
@@ -49,8 +60,13 @@ class NessusClient
 
     private
 
+    # @private HTTP request abstraction to be used.
+    # @param [Symbol] method A HTTP method to be used could be `:get`, `:post` or `:delete`.
+    # @param [String] path The URI path to perform the request.
+    # @param [String] payload The HTTP body to send.
+    # @param [String] query The URI query to send.
     def http_request( method=:get, path, payload, query )
-      # binding.pry
+      
       connection = Excon.new( @@url )
       
       body = payload ? payload.to_json : ''
@@ -61,8 +77,6 @@ class NessusClient
         query: query,
         headers: @headers,
         ssl_verify_peer: @@ssl_verify_peer,
-        #idempotent: true,
-        #proxy: "http://127.0.0.1:8080",
         expects: [200, 201]
       }
       response = connection.request( options )

data/lib/nessus_client/version.rb

@@ -1,3 +1,4 @@
 class NessusClient
-  VERSION = '0.1.0'
+  # The current version of the libary.
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nessus_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Heyder
@@ -108,7 +108,42 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.17.0
-description: Ruby wrapper for Nessus API (all verions)
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.14
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.14
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.20
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.20
+description: NessusClient was designed to be simple, fast and performant through communication
+  with Nessus over REST interface.
 email: eu@heyderandrade.org
 executables: []
 extensions: []
@@ -122,15 +157,16 @@ files:
 - lib/modules/folders.rb
 - lib/modules/policies.rb
 - lib/modules/scans.rb
+- lib/modules/session.rb
 - lib/nessus_client.rb
 - lib/nessus_client/exception.rb
 - lib/nessus_client/request.rb
-- lib/nessus_client/session.rb
 - lib/nessus_client/version.rb
-homepage: https://rubygemspec.org/gems/nessus_client
+homepage: https://github.com/heyder/nessus_client
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://rubydoc.info/github/heyder/nessus_client/
   source_code_uri: https://github.com/heyder/nessus_client
 post_install_message: 
 rdoc_options: []
@@ -150,5 +186,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Ruby wrapper for Nessus API
+summary: Usable, fast, simple Ruby gem for Tenable Nessus Pro v6.x and v7.x
 test_files: []

data/lib/nessus_client/session.rb

@@ -1,56 +0,0 @@
-require 'oj'
-require_relative 'request'
-require_relative 'exception'
-
-class NessusClient
-
-  # This class should be used to get an access token
-  # for use with the main client class.
-  class Session
-    attr_reader :token, :api_token
-
-    @token = @api_token  = nil
-
-    # @param [String] username
-    # @param [String] password
-    def self.create( username, password )
-      
-      payload = {
-        username: username,
-        password: password,
-      }
-
-      response = NessusClient::Request.post( '/session', payload )
-      response = Oj.load(response) if response.length > 0
-
-      if response['token']
-         return self.new( response['token'] )
-      else
-        raise NessusClient::Error.new "#{__method__}::Response did not include a session token."
-      end
-
-    end
-
-    def initialize( token )      
-      @token = token
-    end
-
-    def set_api_token
-      response = NessusClient::Request.get( "/nessus6.js" )
-      response.match( %r{return"(\w{8}-(?:\w{4}-){3}\w{12})"\}} )
-      
-      raise NessusClient::Error.new( "Unable to get API Token. Some features won't work." ) unless $1#.nil?
-      
-      @api_token = $1 
-      
-    end
-
-    def destroy
-      NessusClient::Request.delete( '/session', nil )
-      @token = nil
-    end
-    alias_method :logout , :destroy
-
-  end
-
-end