tenable-ruby-sdk 0.1.0

data/lib/tenable/models/scan.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents a Tenable.io scan.
+    Scan = Data.define(:id, :uuid, :name, :status, :folder_id, :type, :creation_date, :last_modification_date) do
+      # Builds a Scan from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [Scan]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          id: data[:id],
+          uuid: data[:uuid],
+          name: data[:name],
+          status: data[:status],
+          folder_id: data[:folder_id],
+          type: data[:type],
+          creation_date: data[:creation_date],
+          last_modification_date: data[:last_modification_date]
+        )
+      end
+    end
+  end
+end

data/lib/tenable/models/vulnerability.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents a vulnerability finding from the Tenable.io API.
+    Vulnerability = Data.define(
+      :plugin_id, :plugin_name, :severity, :severity_id, :state,
+      :asset, :output, :first_found, :last_found, :last_fixed,
+      :vpr_score, :cvss_base_score, :cve
+    ) do
+      # Builds a Vulnerability from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [Vulnerability]
+      def self.from_api(data) # rubocop:disable Metrics/MethodLength
+        data = data.transform_keys(&:to_sym)
+        new(
+          plugin_id: data[:plugin_id],
+          plugin_name: data[:plugin_name],
+          severity: data[:severity],
+          severity_id: data[:severity_id],
+          state: data[:state],
+          asset: data[:asset] ? Asset.from_api(data[:asset]) : nil,
+          output: data[:output],
+          first_found: data[:first_found],
+          last_found: data[:last_found],
+          last_fixed: data[:last_fixed],
+          vpr_score: data[:vpr_score],
+          cvss_base_score: data[:cvss_base_score],
+          cve: data[:cve] || []
+        )
+      end
+    end
+  end
+end

data/lib/tenable/models/web_app_scan.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents a web application scan instance.
+    WebAppScan = Data.define(:scan_id, :config_id, :status, :started_at, :completed_at, :findings_count) do
+      # Builds a WebAppScan from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [WebAppScan]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          scan_id: data[:scan_id],
+          config_id: data[:config_id],
+          status: data[:status],
+          started_at: data[:started_at],
+          completed_at: data[:completed_at],
+          findings_count: data[:findings_count] || 0
+        )
+      end
+    end
+  end
+end

data/lib/tenable/models/web_app_scan_config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents a web application scan configuration.
+    WebAppScanConfig = Data.define(:config_id, :name, :target, :status, :tracking_id) do
+      # Builds a WebAppScanConfig from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [WebAppScanConfig]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          config_id: data[:config_id],
+          name: data[:name],
+          target: data[:target],
+          status: data[:status],
+          tracking_id: data[:tracking_id]
+        )
+      end
+    end
+  end
+end

data/lib/tenable/pagination.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Provides lazy, offset-based pagination over API list endpoints.
+  #
+  # Fetches pages on demand and yields individual items via {#each},
+  # keeping memory usage constant regardless of total result count.
+  # Includes Enumerable for standard collection methods.
+  class Pagination
+    include Enumerable
+
+    # @return [Integer] maximum items per page
+    MAX_PAGE_SIZE = 200
+
+    # Creates a new paginator.
+    #
+    # @param limit [Integer] items per page (capped at {MAX_PAGE_SIZE})
+    # @yield [offset, limit] block that fetches a page of results
+    # @yieldparam offset [Integer] the current offset
+    # @yieldparam limit [Integer] the page size
+    # @yieldreturn [Hash] a hash containing +"items"+ and +"total"+ keys
+    def initialize(limit: MAX_PAGE_SIZE, &fetcher)
+      @limit = [limit, MAX_PAGE_SIZE].min
+      @fetcher = fetcher
+    end
+
+    # Iterates over all paginated items.
+    #
+    # @yield [item] yields each item
+    # @return [Enumerator] if no block is given
+    #
+    # @example Iterate over all results
+    #   paginator = Tenable::Pagination.new { |offset, limit| fetch_page(offset, limit) }
+    #   paginator.each { |item| process(item) }
+    #
+    # @example Use Enumerable methods
+    #   paginator.first(10)
+    #   paginator.select { |item| item['severity'] > 2 }
+    def each(&block)
+      return enum_for(:each) unless block
+
+      offset = 0
+      loop do
+        page = @fetcher.call(offset, @limit)
+        items = extract_items(page)
+        total = extract_total(page)
+
+        items.each(&block)
+
+        offset += @limit
+        break if offset >= total || items.empty?
+      end
+    end
+
+    # Returns a lazy enumerator over all paginated items.
+    #
+    # @return [Enumerator::Lazy]
+    def lazy
+      each.lazy
+    end
+
+    private
+
+    def extract_items(page)
+      page[:items] || page['items'] || []
+    end
+
+    def extract_total(page)
+      page[:total] || page['total'] || 0
+    end
+  end
+end

data/lib/tenable/pollable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Shared polling behavior for resources that need to wait on async operations.
+  #
+  # Uses monotonic clock to avoid issues with system clock changes.
+  module Pollable
+    # Polls a block until it returns a truthy value or the timeout expires.
+    #
+    # @param timeout [Integer] maximum seconds to wait
+    # @param poll_interval [Integer] seconds between polls
+    # @param label [String] descriptive label for timeout error messages
+    # @yield block that returns a truthy value when the operation is complete
+    # @yieldreturn [Object, nil] truthy to stop polling, nil/false to continue
+    # @return [Object] the truthy value returned by the block
+    # @raise [Tenable::TimeoutError] if the timeout expires before the block returns truthy
+    def poll_until(timeout:, poll_interval:, label:)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise Tenable::TimeoutError, "#{label} timed out after #{timeout}s"
+        end
+
+        result = yield
+        return result if result
+
+        sleep(poll_interval)
+      end
+    end
+  end
+end

data/lib/tenable/resources/asset_exports.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Resources
+    # Provides access to the Tenable.io asset export endpoints.
+    #
+    # Exports allow bulk retrieval of asset data in chunks.
+    #
+    # @example Full export workflow
+    #   asset_exports = client.asset_exports
+    #   result = asset_exports.export(chunk_size: 100)
+    #   asset_exports.wait_for_completion(result["export_uuid"])
+    #   asset_exports.each(result["export_uuid"]) { |asset| process(asset) }
+    class AssetExports < Base
+      # @return [Integer] default seconds between status polls
+      DEFAULT_POLL_INTERVAL = 2
+
+      # @return [Integer] default timeout in seconds for waiting on export completion
+      DEFAULT_TIMEOUT = 300
+
+      # Initiates a new asset export.
+      #
+      # @param body [Hash] export request parameters (e.g., +chunk_size+, +filters+)
+      # @return [Hash] response containing the export UUID
+      def export(body = {})
+        post('/assets/export', body)
+      end
+
+      # Retrieves the status of an asset export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @return [Hash] status data including +"status"+ and +"chunks_available"+
+      def status(export_uuid)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        get("/assets/export/#{export_uuid}/status")
+      end
+
+      # Downloads a single chunk of asset export data.
+      #
+      # @param export_uuid [String] the export UUID
+      # @param chunk_id [Integer] the chunk identifier
+      # @return [Array<Hash>] array of asset records
+      def download_chunk(export_uuid, chunk_id)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        validate_path_segment!(chunk_id, name: 'chunk_id')
+        get("/assets/export/#{export_uuid}/chunks/#{chunk_id}")
+      end
+
+      # Cancels an in-progress asset export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @return [Hash] cancellation response
+      def cancel(export_uuid)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        post("/assets/export/#{export_uuid}/cancel")
+      end
+
+      # Iterates over all available chunks for a completed export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @yield [record] yields each asset record
+      # @yieldparam record [Hash] a single asset record
+      # @return [void]
+      def each(export_uuid, &block)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        return enum_for(:each, export_uuid) unless block
+
+        status_data = status(export_uuid)
+        chunks = status_data['chunks_available'] || []
+        chunks.each do |chunk_id|
+          records = download_chunk(export_uuid, chunk_id)
+          records.each(&block)
+        end
+      end
+
+      # Polls until the export reaches FINISHED or ERROR status.
+      #
+      # @param export_uuid [String] the export UUID
+      # @param timeout [Integer] maximum seconds to wait (default: 300)
+      # @param poll_interval [Integer] seconds between status checks (default: 2)
+      # @return [Hash] the final status data when export is FINISHED
+      # @raise [Tenable::TimeoutError] if the export does not finish within the timeout
+      # @raise [Tenable::ApiError] if the export status is ERROR
+      def wait_for_completion(export_uuid, timeout: DEFAULT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        poll_until(timeout: timeout, poll_interval: poll_interval, label: "Asset export #{export_uuid}") do
+          status_data = status(export_uuid)
+          raise Tenable::ApiError, "Asset export #{export_uuid} failed" if status_data['status'] == 'ERROR'
+
+          status_data if status_data['status'] == 'FINISHED'
+        end
+      end
+    end
+  end
+end

data/lib/tenable/resources/base.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Resources
+    # Base class for all API resource classes. Provides HTTP helpers
+    # and response handling with automatic error mapping.
+    class Base
+      include Pollable
+
+      # @param connection [Connection] an initialized API connection
+      def initialize(connection)
+        @connection = connection
+      end
+
+      private
+
+      # Performs a GET request.
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash] query parameters
+      # @return [Hash, Array, nil] parsed JSON response
+      # @raise [AuthenticationError] on 401 responses
+      # @raise [RateLimitError] on 429 responses
+      # @raise [ApiError] on other non-2xx responses
+      # @raise [ParseError] if the response is not valid JSON
+      def get(path, params = {})
+        response = @connection.faraday.get(path, params)
+        handle_response(response)
+      end
+
+      # Performs a POST request with a JSON body.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash, nil] request body (serialized to JSON)
+      # @return [Hash, Array, nil] parsed JSON response
+      # @raise [AuthenticationError] on 401 responses
+      # @raise [RateLimitError] on 429 responses
+      # @raise [ApiError] on other non-2xx responses
+      # @raise [ParseError] if the response is not valid JSON
+      def post(path, body = nil)
+        response = @connection.faraday.post(path) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.body = JSON.generate(body) if body
+        end
+        handle_response(response)
+      end
+
+      # Performs a PUT request with a JSON body.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash, nil] request body (serialized to JSON)
+      # @return [Hash, Array, nil] parsed JSON response
+      def put(path, body = nil)
+        response = @connection.faraday.put(path) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.body = JSON.generate(body) if body
+        end
+        handle_response(response)
+      end
+
+      # Performs a PATCH request with a JSON body.
+      #
+      # @param path [String] the API endpoint path
+      # @param body [Hash, nil] request body (serialized to JSON)
+      # @return [Hash, Array, nil] parsed JSON response
+      def patch(path, body = nil)
+        response = @connection.faraday.patch(path) do |req|
+          req.headers['Content-Type'] = 'application/json'
+          req.body = JSON.generate(body) if body
+        end
+        handle_response(response)
+      end
+
+      # Performs a DELETE request.
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash] query parameters
+      # @return [Hash, Array, nil] parsed JSON response
+      def delete(path, params = {})
+        response = @connection.faraday.delete(path, params)
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        raise_for_status(response)
+        parse_body(response)
+      end
+
+      def parse_body(response)
+        return nil if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise ParseError, "Failed to parse response: #{response.body[0..100]}"
+      end
+
+      # Performs a GET request and returns the raw response body without JSON parsing.
+      # Useful for binary downloads (e.g., PDF, Nessus files).
+      #
+      # @param path [String] the API endpoint path
+      # @param params [Hash] query parameters
+      # @return [String] raw response body
+      # @raise [AuthenticationError] on 401 responses
+      # @raise [RateLimitError] on 429 responses
+      # @raise [ApiError] on other non-2xx responses
+      def get_raw(path, params = {})
+        response = @connection.faraday.get(path, params)
+        raise_for_status(response)
+        response.body
+      end
+
+      # Validates that a value is safe to interpolate into a URL path segment.
+      # Rejects path traversal attempts (/, ..) and non-printable characters.
+      #
+      # @param value [String, Integer] the path segment to validate
+      # @param name [String] parameter name for error messages
+      # @raise [ArgumentError] if the value contains unsafe characters
+      def validate_path_segment!(value, name: 'id')
+        str = value.to_s
+        return unless str.empty? || str.include?('/') || str.include?('..') || str.match?(/[^[:print:]]/)
+
+        raise ArgumentError, "Invalid #{name}: contains unsafe characters"
+      end
+
+      def raise_for_status(response)
+        case response.status
+        when 200..299 then nil
+        when 401      then raise AuthenticationError
+        when 429      then raise RateLimitError.new(status_code: response.status, body: response.body)
+        else               raise ApiError.new(status_code: response.status, body: response.body)
+        end
+      end
+    end
+  end
+end

data/lib/tenable/resources/exports.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Resources
+    # Provides access to the Tenable.io vulnerability export endpoints.
+    #
+    # Exports allow bulk retrieval of vulnerability data in chunks.
+    #
+    # @example Full export workflow
+    #   exports = client.exports
+    #   result = exports.export(num_assets: 50)
+    #   exports.wait_for_completion(result["export_uuid"])
+    #   exports.each(result["export_uuid"]) { |vuln| process(vuln) }
+    class Exports < Base
+      # @return [Integer] default seconds between status polls
+      DEFAULT_POLL_INTERVAL = 2
+
+      # @return [Integer] default timeout in seconds for waiting on export completion
+      DEFAULT_TIMEOUT = 300
+
+      # Initiates a new vulnerability export.
+      #
+      # @param body [Hash] export request parameters (e.g., +num_assets+, +filters+)
+      # @return [Hash] response containing the export UUID
+      # @raise [ApiError] on non-2xx responses
+      #
+      # @example
+      #   client.exports.export(num_assets: 50)
+      def export(body = {})
+        post('/vulns/export', body)
+      end
+
+      # Retrieves the status of an export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @return [Hash] status data including +"status"+ and +"chunks_available"+
+      def status(export_uuid)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        get("/vulns/export/#{export_uuid}/status")
+      end
+
+      # Downloads a single chunk of export data.
+      #
+      # @param export_uuid [String] the export UUID
+      # @param chunk_id [Integer] the chunk identifier
+      # @return [Array<Hash>] array of vulnerability records
+      def download_chunk(export_uuid, chunk_id)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        validate_path_segment!(chunk_id, name: 'chunk_id')
+        get("/vulns/export/#{export_uuid}/chunks/#{chunk_id}")
+      end
+
+      # Cancels an in-progress vulnerability export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @return [Hash] cancellation response
+      def cancel(export_uuid)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        post("/vulns/export/#{export_uuid}/cancel")
+      end
+
+      # Iterates over all available chunks for a completed export.
+      #
+      # @param export_uuid [String] the export UUID
+      # @yield [record] yields each vulnerability record
+      # @yieldparam record [Hash] a single vulnerability record
+      # @return [void]
+      #
+      # @example
+      #   client.exports.each(uuid) do |vuln|
+      #     puts vuln["plugin_name"]
+      #   end
+      def each(export_uuid, &block)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        return enum_for(:each, export_uuid) unless block
+
+        status_data = status(export_uuid)
+        chunks = status_data['chunks_available'] || []
+        chunks.each do |chunk_id|
+          records = download_chunk(export_uuid, chunk_id)
+          records.each(&block)
+        end
+      end
+
+      # Polls until the export reaches FINISHED or ERROR status.
+      #
+      # @param export_uuid [String] the export UUID
+      # @param timeout [Integer] maximum seconds to wait (default: 300)
+      # @param poll_interval [Integer] seconds between status checks (default: 2)
+      # @return [Hash] the final status data when export is FINISHED
+      # @raise [Tenable::TimeoutError] if the export does not finish within the timeout
+      # @raise [Tenable::ApiError] if the export status is ERROR
+      def wait_for_completion(export_uuid, timeout: DEFAULT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL)
+        validate_path_segment!(export_uuid, name: 'export_uuid')
+        poll_until(timeout: timeout, poll_interval: poll_interval, label: "Export #{export_uuid}") do
+          status_data = status(export_uuid)
+          raise Tenable::ApiError, "Export #{export_uuid} failed" if status_data['status'] == 'ERROR'
+
+          status_data if status_data['status'] == 'FINISHED'
+        end
+      end
+    end
+  end
+end