tenable-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6020ebd94aaa44a36cf4eeebeca87d7ceaf6730f3ff15dbe377b3d332cf8a90e
+  data.tar.gz: 5debd6afde04c5f130fb3c1e867f68b0fbbdfbe160c2fffac20bb0ad4fa488dd
+SHA512:
+  metadata.gz: bc1dc472bbe24ee07fa0447d3c87a60e09451cad4f31714d667e5bba43c1d098e5b1d82006b01a431cfc2a8401e760a007a95507123358e54e6c7282cfaf9758
+  data.tar.gz: 3f0ce6c911b2a72ed66b9e805541e6e4ae4864b3948c1f9e89807c4b58b9005d3747192f8fdbbdd550765ea6d6b8f97b63cfdd8d6bdc4515a3d7853458d2ca80

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vudx00
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,164 @@
+# tenable-ruby-sdk
+
+> **Unofficial** — This project is not affiliated with, endorsed by, or sponsored by Tenable, Inc. "Tenable" is a registered trademark of Tenable, Inc.
+
+Ruby SDK for the [Tenable.io API](https://developer.tenable.com/reference/navigate). Covers vulnerability management, bulk exports, VM scans, and WAS v2 web application scanning.
+
+Requires Ruby >= 3.2. Uses [Faraday](https://github.com/lostisland/faraday) for HTTP.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'tenable-ruby-sdk'
+```
+
+Then `bundle install`.
+
+## Authentication
+
+Get your API keys from Tenable.io under **Settings > My Account > API Keys**.
+
+Pass them directly:
+
+```ruby
+client = Tenable::Client.new(
+  access_key: "your-access-key",
+  secret_key: "your-secret-key"
+)
+```
+
+Or set environment variables and omit them:
+
+```sh
+export TENABLE_ACCESS_KEY="your-access-key"
+export TENABLE_SECRET_KEY="your-secret-key"
+```
+
+```ruby
+client = Tenable::Client.new
+```
+
+## Usage
+
+### List Vulnerabilities
+
+```ruby
+data = client.vulnerabilities.list
+data["vulnerabilities"].each do |vuln|
+  puts "#{vuln['plugin_name']} (severity: #{vuln['severity']})"
+end
+```
+
+### Export Vulnerabilities
+
+For large datasets, use the export workflow:
+
+```ruby
+exports = client.exports
+
+# Start the export
+result = exports.export(num_assets: 50)
+uuid = result["export_uuid"]
+
+# Wait for it to finish (polls automatically, 5 min timeout by default)
+exports.wait_for_completion(uuid)
+
+# Iterate over all chunks
+exports.each(uuid) do |vuln|
+  puts vuln["plugin"]["name"]
+end
+```
+
+### VM Scans
+
+```ruby
+# List scans
+client.scans.list
+
+# Launch a scan
+client.scans.launch(scan_id)
+
+# Check status
+client.scans.status(scan_id)
+```
+
+### Web App Scans (WAS v2)
+
+```ruby
+was = client.web_app_scans
+
+# Create a scan config
+config = was.create_config(name: "My Scan", target: "https://example.com")
+config_id = config["config_id"]
+
+# Launch the scan
+scan = was.launch(config_id)
+scan_id = scan["scan_id"]
+
+# Wait for completion (polls until terminal status)
+was.wait_until_complete(config_id, scan_id)
+
+# Get findings
+was.findings(config_id)
+```
+
+## Configuration
+
+All options with their defaults:
+
+```ruby
+client = Tenable::Client.new(
+  access_key:   "...",                          # or TENABLE_ACCESS_KEY env var
+  secret_key:   "...",                          # or TENABLE_SECRET_KEY env var
+  base_url:     "https://cloud.tenable.com",    # must be HTTPS
+  timeout:      30,                             # request timeout (seconds)
+  open_timeout: 10,                             # connection timeout (seconds)
+  max_retries:  3,                              # retry attempts (0-10)
+  logger:       Logger.new($stdout)             # nil = silent (default)
+)
+```
+
+## Error Handling
+
+All errors inherit from `Tenable::Error`:
+
+```ruby
+begin
+  client.vulnerabilities.list
+rescue Tenable::AuthenticationError => e
+  # Bad or missing API keys (401)
+rescue Tenable::RateLimitError => e
+  # Rate limited and retries exhausted (429)
+  e.status_code  # => 429
+rescue Tenable::TimeoutError => e
+  # Request or export poll timed out
+rescue Tenable::ApiError => e
+  # Any other API error
+  e.status_code  # => Integer
+  e.body         # => String
+rescue Tenable::ConnectionError => e
+  # Network failure
+end
+```
+
+Rate limiting (429) and server errors (5xx) are retried automatically with exponential backoff before raising.
+
+## Thread Safety
+
+The client is frozen after initialization with eagerly instantiated resources. Safe to use across threads.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec        # run tests
+bundle exec rubocop      # lint
+bundle exec yard doc     # generate docs
+bundle audit check       # check for vulnerable dependencies
+```
+
+## License
+
+MIT

data/lib/tenable/client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Primary entry point for the Tenable.io API.
+  #
+  # @example Basic usage
+  #   client = Tenable::Client.new(access_key: "ak", secret_key: "sk")
+  #   client.vulnerabilities.list
+  class Client
+    # @return [Configuration] the client configuration
+    attr_reader :configuration
+
+    # @return [Resources::Vulnerabilities]
+    attr_reader :vulnerabilities
+
+    # @return [Resources::Exports]
+    attr_reader :exports
+
+    # @return [Resources::AssetExports]
+    attr_reader :asset_exports
+
+    # @return [Resources::Scans]
+    attr_reader :scans
+
+    # @return [Resources::WebAppScans]
+    attr_reader :web_app_scans
+
+    # Creates a new Tenable API client.
+    #
+    # @param options [Hash] configuration options passed to {Configuration#initialize}
+    # @option options [String] :access_key Tenable.io API access key
+    # @option options [String] :secret_key Tenable.io API secret key
+    # @option options [String] :base_url API base URL (default: https://cloud.tenable.com)
+    # @option options [Integer] :timeout request timeout in seconds (default: 30)
+    # @option options [Integer] :open_timeout connection open timeout in seconds (default: 10)
+    # @option options [Integer] :max_retries maximum retry attempts (default: 3)
+    # @option options [Logger] :logger optional logger instance
+    # @raise [ArgumentError] if required credentials are missing or options are invalid
+    #
+    # @example
+    #   client = Tenable::Client.new(
+    #     access_key: "your-access-key",
+    #     secret_key: "your-secret-key",
+    #     timeout: 60
+    #   )
+    def initialize(**)
+      @configuration = Configuration.new(**)
+      connection = Connection.new(@configuration)
+      @vulnerabilities = Resources::Vulnerabilities.new(connection)
+      @exports = Resources::Exports.new(connection)
+      @asset_exports = Resources::AssetExports.new(connection)
+      @scans = Resources::Scans.new(connection)
+      @web_app_scans = Resources::WebAppScans.new(connection)
+      freeze
+    end
+  end
+end

data/lib/tenable/configuration.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Holds and validates all configuration options for the Tenable client.
+  #
+  # Configuration values can be passed directly or read from environment
+  # variables (+TENABLE_ACCESS_KEY+, +TENABLE_SECRET_KEY+).
+  class Configuration
+    # @return [String] the API access key
+    attr_reader :access_key
+
+    # @return [String] the API secret key
+    attr_reader :secret_key
+
+    # @return [String] the API base URL
+    attr_reader :base_url
+
+    # @return [Integer] the request timeout in seconds
+    attr_reader :timeout
+
+    # @return [Integer] the connection open timeout in seconds
+    attr_reader :open_timeout
+
+    # @return [Integer] the maximum number of retry attempts
+    attr_reader :max_retries
+
+    # @return [Logger, nil] optional logger instance
+    attr_reader :logger
+
+    DEFAULTS = {
+      base_url: 'https://cloud.tenable.com',
+      timeout: 30,
+      open_timeout: 10,
+      max_retries: 3
+    }.freeze
+
+    # Creates a new Configuration instance.
+    #
+    # @param access_key [String, nil] API access key (falls back to +TENABLE_ACCESS_KEY+ env var)
+    # @param secret_key [String, nil] API secret key (falls back to +TENABLE_SECRET_KEY+ env var)
+    # @param base_url [String, nil] API base URL (default: https://cloud.tenable.com)
+    # @param timeout [Integer, nil] request timeout in seconds (default: 30)
+    # @param open_timeout [Integer, nil] connection open timeout in seconds (default: 10)
+    # @param max_retries [Integer, nil] max retry attempts, 0-10 (default: 3)
+    # @param logger [Logger, nil] optional logger for request/response logging
+    # @raise [ArgumentError] if credentials are missing, base_url is invalid, or numeric values are out of range
+    def initialize(access_key: nil, secret_key: nil, base_url: nil, timeout: nil, open_timeout: nil, max_retries: nil,
+                   logger: nil)
+      @access_key = access_key || ENV.fetch('TENABLE_ACCESS_KEY', nil)
+      @secret_key = secret_key || ENV.fetch('TENABLE_SECRET_KEY', nil)
+      @base_url = base_url || DEFAULTS[:base_url]
+      @timeout = timeout || DEFAULTS[:timeout]
+      @open_timeout = open_timeout || DEFAULTS[:open_timeout]
+      @max_retries = max_retries.nil? ? DEFAULTS[:max_retries] : max_retries
+      @logger = logger
+
+      validate!
+      freeze
+    end
+
+    private
+
+    def validate!
+      validate_credentials!
+      validate_base_url!
+      validate_timeouts!
+      validate_max_retries!
+    end
+
+    def validate_credentials!
+      raise ArgumentError, 'access_key is required (pass directly or set TENABLE_ACCESS_KEY)' if blank?(@access_key)
+      raise ArgumentError, 'secret_key is required (pass directly or set TENABLE_SECRET_KEY)' if blank?(@secret_key)
+    end
+
+    def validate_base_url!
+      uri = URI.parse(@base_url)
+      raise ArgumentError, "base_url must use HTTPS: #{@base_url}" unless uri.scheme == 'https'
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url is not a valid URL: #{@base_url}"
+    end
+
+    def validate_timeouts!
+      unless @timeout.is_a?(Integer) && @timeout.positive?
+        raise ArgumentError,
+              "timeout must be positive, got #{@timeout}"
+      end
+
+      return if @open_timeout.is_a?(Integer) && @open_timeout.positive?
+
+      raise ArgumentError, "open_timeout must be positive, got #{@open_timeout}"
+    end
+
+    def validate_max_retries!
+      return if @max_retries.is_a?(Integer) && @max_retries >= 0 && @max_retries <= 10
+
+      raise ArgumentError, "max_retries must be between 0 and 10, got #{@max_retries}"
+    end
+
+    def blank?(value)
+      value.nil? || (value.is_a?(String) && value.strip.empty?)
+    end
+  end
+end

data/lib/tenable/connection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Manages the Faraday HTTP connection with configured middleware.
+  #
+  # Automatically configures authentication, retry, and logging middleware
+  # based on the provided {Configuration}.
+  class Connection
+    # @return [Faraday::Connection] the underlying Faraday connection
+    attr_reader :faraday
+
+    # Creates a new connection from the given configuration.
+    #
+    # @param config [Configuration] a validated configuration instance
+    # @raise [ArgumentError] if the base_url does not use HTTPS
+    def initialize(config)
+      @config = config
+      @faraday = build_connection
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @config.base_url) do |f|
+        f.headers['Accept'] = 'application/json'
+        f.use Middleware::Authentication,
+              access_key: @config.access_key,
+              secret_key: @config.secret_key
+        f.use Middleware::Retry, max_retries: @config.max_retries
+        f.use Middleware::Logging, logger: @config.logger
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = @config.open_timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/tenable/error.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Tenable
+  # Base error class for all Tenable SDK errors.
+  class Error < StandardError; end
+
+  # Raised when API authentication fails (HTTP 401).
+  class AuthenticationError < Error
+    DEFAULT_MESSAGE = 'Authentication failed. Verify your access key and secret key are correct.'
+
+    def initialize(msg = DEFAULT_MESSAGE)
+      super
+    end
+  end
+
+  # Raised for non-success HTTP responses from the Tenable API.
+  class ApiError < Error
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status_code
+
+    # @return [String, nil] the response body
+    attr_reader :body
+
+    # @param msg [String, nil] custom error message
+    # @param status_code [Integer, nil] HTTP status code
+    # @param body [String, nil] response body
+    def initialize(msg = nil, status_code: nil, body: nil)
+      @status_code = status_code
+      @body = body
+      message = msg || "API request failed with status #{status_code}"
+      message = "#{message}: #{body}" if body
+      super(message)
+    end
+  end
+
+  # Raised when the API rate limit is exceeded and retries are exhausted (HTTP 429).
+  class RateLimitError < ApiError
+    def initialize(msg = 'Rate limit exceeded. Retries exhausted.', **kwargs)
+      super
+    end
+  end
+
+  # Raised when a network connection to the Tenable API cannot be established.
+  class ConnectionError < Error
+    def initialize(msg = 'Connection to Tenable API failed. Check your network and base_url configuration.')
+      super
+    end
+  end
+
+  # Raised when an API request exceeds the configured timeout.
+  class TimeoutError < Error
+    def initialize(msg = 'Request timed out. Consider increasing the timeout configuration.')
+      super
+    end
+  end
+
+  # Raised when the API response body cannot be parsed as JSON.
+  class ParseError < Error
+    def initialize(msg = 'Failed to parse API response. The response may be malformed.')
+      super
+    end
+  end
+end

data/lib/tenable/middleware/authentication.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Middleware
+    class Authentication < Faraday::Middleware
+      def initialize(app, access_key:, secret_key:)
+        super(app)
+        @access_key = access_key
+        @secret_key = secret_key
+      end
+
+      def on_request(env)
+        env.request_headers['X-ApiKeys'] = "accessKey=#{@access_key};secretKey=#{@secret_key};"
+      end
+
+      def inspect
+        "#<#{self.class.name} [REDACTED]>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/tenable/middleware/logging.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Middleware
+    class Logging < Faraday::Middleware
+      API_KEY_PATTERN = /accessKey=[^;]*;?\s*secretKey=[^;]*/
+
+      def initialize(app, logger: nil)
+        super(app)
+        @logger = logger
+      end
+
+      def call(env)
+        log_request(env) if @logger
+        @app.call(env).on_complete do |response_env|
+          log_response(response_env) if @logger
+        end
+      rescue StandardError => e
+        @logger&.error("Tenable request error: #{e.message}")
+        raise
+      end
+
+      private
+
+      def log_request(env)
+        headers = redact_headers(env.request_headers)
+        @logger.debug("Tenable request: #{env.method.upcase} #{env.url} headers=#{headers}")
+      end
+
+      def log_response(env)
+        @logger.debug("Tenable response: status=#{env.status}")
+      end
+
+      def redact_headers(headers)
+        headers.transform_values do |value|
+          value.is_a?(String) ? value.gsub(API_KEY_PATTERN, '[REDACTED]') : value
+        end
+      end
+    end
+  end
+end

data/lib/tenable/middleware/retry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Middleware
+    class Retry < Faraday::Middleware
+      DEFAULT_MAX_RETRIES = 3
+      RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+      BASE_DELAY = 1
+
+      def initialize(app, max_retries: DEFAULT_MAX_RETRIES)
+        super(app)
+        @max_retries = max_retries
+      end
+
+      def call(env)
+        attempt = 0
+        loop do
+          attempt += 1
+          response = @app.call(env.dup)
+
+          return response unless retryable?(response.status)
+
+          raise_if_exhausted(response, attempt) if attempt >= @max_retries
+
+          sleep(retry_delay(response, attempt))
+        end
+      rescue Faraday::Error
+        raise if attempt >= @max_retries
+
+        sleep(BASE_DELAY * (2**(attempt - 1)))
+        retry
+      end
+
+      private
+
+      def retryable?(status)
+        RETRYABLE_STATUS_CODES.include?(status)
+      end
+
+      def retry_delay(response, attempt)
+        retry_after = response.headers&.[]('Retry-After')
+        return retry_after.to_i if retry_after
+
+        BASE_DELAY * (2**(attempt - 1))
+      end
+
+      def raise_if_exhausted(response, attempts)
+        if response.status == 429
+          raise Tenable::RateLimitError.new(
+            "Rate limit exceeded after #{attempts} attempts",
+            status_code: response.status,
+            body: response.body
+          )
+        end
+
+        raise Tenable::ApiError.new(
+          "Request failed after #{attempts} attempts",
+          status_code: response.status,
+          body: response.body
+        )
+      end
+    end
+  end
+end

data/lib/tenable/models/asset.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents an asset (host/device) from the Tenable.io API.
+    Asset = Data.define(:uuid, :hostname, :ipv4, :operating_system, :fqdn, :netbios_name) do
+      # Builds an Asset from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [Asset]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          uuid: data[:uuid],
+          hostname: data[:hostname],
+          ipv4: data[:ipv4],
+          operating_system: data[:operating_system] || [],
+          fqdn: data[:fqdn] || [],
+          netbios_name: data[:netbios_name]
+        )
+      end
+    end
+  end
+end

data/lib/tenable/models/export.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents the status of a vulnerability export job.
+    Export = Data.define(:uuid, :status, :chunks_available, :chunks_failed, :chunks_cancelled) do
+      # Builds an Export from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [Export]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          uuid: data[:uuid],
+          status: data[:status],
+          chunks_available: data[:chunks_available] || [],
+          chunks_failed: data[:chunks_failed] || [],
+          chunks_cancelled: data[:chunks_cancelled] || []
+        )
+      end
+
+      # @return [Boolean] true if the export has completed successfully
+      def finished?
+        status == 'FINISHED'
+      end
+
+      # @return [Boolean] true if the export is still processing
+      def processing?
+        status == 'PROCESSING'
+      end
+
+      # @return [Boolean] true if the export encountered an error
+      def error?
+        status == 'ERROR'
+      end
+
+      # @return [Boolean] true if the export is queued
+      def queued?
+        status == 'QUEUED'
+      end
+    end
+  end
+end

data/lib/tenable/models/finding.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tenable
+  module Models
+    # Represents a web application scan finding.
+    Finding = Data.define(:finding_id, :severity, :url, :name, :description, :remediation, :plugin_id) do
+      # Builds a Finding from a raw API response hash.
+      #
+      # @param data [Hash] raw API response hash with string keys
+      # @return [Finding]
+      def self.from_api(data)
+        data = data.transform_keys(&:to_sym)
+        new(
+          finding_id: data[:finding_id],
+          severity: data[:severity],
+          url: data[:url],
+          name: data[:name],
+          description: data[:description],
+          remediation: data[:remediation],
+          plugin_id: data[:plugin_id]
+        )
+      end
+    end
+  end
+end