emasser 3.10.0 → 3.22.0

data/emasser.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary = 'Provide an automated capability for invoving eMASS API endpoints'
   spec.description = 'The emasser can be used as a gem or used from the command line (CL) to access eMASS endpoints via their API.'
   spec.homepage = 'https://saf.mitre.org'
-  spec.required_ruby_version = Gem::Requirement.new('~> 2.5')
+  spec.required_ruby_version = Gem::Requirement.new('~> 3.2')
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -24,21 +24,27 @@ Gem::Specification.new do |spec|
   # References: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry
   spec.metadata = { "github_repo" => "ssh://github.com/mitre/emasser" }
 
+  # ---- Run Time Dependencies
   spec.add_runtime_dependency 'activesupport', '>= 6.1.4', '< 7.1.0'
-  spec.add_runtime_dependency 'colorize', '~> 0.8.1'
-  spec.add_runtime_dependency 'dotenv', '~> 2.7.6'
+  spec.add_runtime_dependency 'colorize', '~> 1.1.0'
+  spec.add_runtime_dependency 'dotenv', '~> 3.1.2'
   spec.add_runtime_dependency 'rubyzip', '~> 2.3.2'
-  spec.add_runtime_dependency 'thor', '~> 1.1.0'
-  spec.add_runtime_dependency 'emass_client', '~> 3.10'
+  spec.add_runtime_dependency 'thor', '~> 1.3.0'
+  spec.add_runtime_dependency 'emass_client', '~> 3.20'
 
-  spec.add_development_dependency 'bundler', '~> 2.3'
-  spec.add_development_dependency 'bundler-audit', '~> 0.7'
+  # ---- Development Dependencies
+  spec.add_development_dependency 'bundler', '~> 2.5'
+  spec.add_development_dependency 'bundler-audit', '~> 0.9'
+  # byebug - does not work with ruby 3.3.3
   spec.add_development_dependency 'byebug', '~> 11.1.3'
-  spec.add_development_dependency 'rspec', '~> 3.10.0'
-  spec.add_development_dependency 'yaml', '~> 0.2.0'
-  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.13.0'
+  spec.add_development_dependency 'yaml', '~> 0.3.0'
+  spec.add_development_dependency 'rake', '~> 13.2.1'  
   spec.add_development_dependency 'rubocop', '~> 1.7'
-  spec.add_development_dependency 'rubocop-minitest', '~> 0.10'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.11'
-  spec.add_development_dependency 'rubocop-rake', '~> 0.5'
+ #  spec.add_development_dependency 'rubocop', '~> 1.64'
+  spec.add_development_dependency 'rubocop-minitest', '~> 0.35'  
+  spec.add_development_dependency 'rubocop-performance', '~> 1.21'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
+  # solargraph - does not work with ruby 3.3.3
+  spec.add_development_dependency 'solargraph', '~> 0.50'
 end

data/lib/emasser/configuration.rb

@@ -2,48 +2,149 @@
 
 module Emasser
   require 'emasser/errors'
+  require 'fileutils'
 
   class Configuration
-    # rubocop: disable Style/RaiseArgs
+    # rubocop: disable Style/GuardClause, Lint/NonAtomicFileOperation
+    # rubocop: disable Style/RescueStandardError, Lint/DuplicateBranch, Style/RedundantReturn
+    # rubocop: disable Style/RaiseArgs, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.raise_unless_present(env)
-      ENV.fetch(env) { raise Emasser::ConfigurationMissingError.new(env) }
+      env_value = ENV.fetch(env) { raise Emasser::ConfigurationMissingError.new(env) }
+      if env_value.empty?
+        raise Emasser::ConfigurationEmptyValueError.new(env)
+      end
+
+      return env_value
+    rescue Emasser::ConfigurationEmptyValueError => e
+      unless (ARGV[0].to_s.include? 'post') && (ARGV[1].to_s.include? 'register') && (env.include? 'EMASSER_API_KEY')
+        puts "\n", e.message.red
+        show = Configuration.new
+        show.emasser_env_msg
+        exit
+      end
     rescue Emasser::ConfigurationMissingError => e
-      if (ARGV[0].to_s.include? '-v') || (ARGV[0].to_s.include? '-V')
-        puts "emasser version: #{Emasser::VERSION}".green
-      else
+      unless (ARGV[0].to_s.include? 'post') && (ARGV[1].to_s.include? 'register') && (env.include? 'EMASSER_API_KEY')
         puts "\n", e.message.red
-        puts 'Create a .env file containing required variables, place it in the root directory where the emasser command is executed'.yellow
-        puts 'Required environment variables are:'.yellow
-        puts '  export EMASSER_API_KEY=<API key>'.green
-        puts '  export EMASSER_USER_UID=<unique identifier of the eMASS user EMASSER_API_KEY belongs to>'.green
-        puts '  export EMASSER_HOST_URL=<FQDN of the eMASS server>'.green
-        puts '  export EMASSER_KEY_FILE_PATH=<path to your emass key in PEM format>'.green
-        puts '  export EMASSER_CERT_FILE_PATH=<path to your emass certficate in PEM format>'.green
-        puts '  export EMASSER_KEY_FILE_PASSWORD=<password for the key given in EMASSER_KEY_FILE_PATH>'.green, "\n"
-        puts 'See emasser environment variables requirements in emasser CLI Features for more information (https://mitre.github.io/emasser/docs/features.html).', "\n"
+        show = Configuration.new
+        show.emasser_env_msg
+        exit
       end
-      exit
     end
-    # rubocop: enable Style/RaiseArgs
-
-    # rubocop: disable Style/TernaryParentheses, Style/IfWithBooleanLiteralBranches
-    EmassClient.configure do |config|
-      # Required env variables
-      config.api_key['api-key'] = raise_unless_present('EMASSER_API_KEY')
-      config.api_key['user-uid'] = raise_unless_present('EMASSER_USER_UID')
-      config.scheme = 'https'
-      config.base_path = '/'
-      config.server_index = nil
-      config.host = raise_unless_present('EMASSER_HOST_URL')
-      config.key_file = raise_unless_present('EMASSER_KEY_FILE_PATH')
-      config.cert_file = raise_unless_present('EMASSER_CERT_FILE_PATH')
-      config.key_password = raise_unless_present('EMASSER_KEY_FILE_PASSWORD')
-      # Optional env variables
-      config.client_side_validation = (ENV.fetch('EMASSER_CLIENT_SIDE_VALIDATION', 'true').eql? 'true') ? true : false
-      config.verify_ssl = (ENV.fetch('EMASSER_VERIFY_SSL', 'true').eql? 'true') ? true : false
-      config.verify_ssl_host = (ENV.fetch('EMASSER_VERIFY_SSL_HOST', 'true').eql? 'true') ? true : false
-      config.debugging = (ENV.fetch('EMASSER_DEBUGGING', 'false') == 'false') ? false : true
+
+    def self.check_folder_exists(env)
+      folder_path = ENV.fetch(env) # raises error if EMASSER_DOWNLOAD_DIR is missing
+      if folder_path.empty?
+        # Create a default downloads folder
+        raise CreateDefaultDownloadDirectory
+      else
+        # Create the folder if does not exist
+        unless Dir.exist?(folder_path)
+          FileUtils.mkdir_p('eMASSerDownloads')
+        end
+        return folder_path
+      end
+    rescue # CreateDefaultDownloadDirectory
+      # Create the default folder if does not exist
+      unless Dir.exist?('eMASSerDownloads')
+        FileUtils.mkdir_p('eMASSerDownloads')
+      end
+      return 'eMASSerDownloads'
+    end
+    # rubocop: enable Style/GuardClause, Lint/NonAtomicFileOperation
+    # rubocop: enable Style/RescueStandardError, Lint/DuplicateBranch, Style/RedundantReturn
+    # rubocop: enable Style/RaiseArgs, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def emasser_env_msg
+      puts 'Create (or update) the configuration (.env) file and place it in the root directory where the emasser command is executed'.yellow
+      puts 'Required environment variables:'.yellow
+      puts '  export EMASSER_API_KEY=<API key>'.green
+      puts '  export EMASSER_HOST_URL=<FQDN of the eMASS server>'.green
+      puts '  export EMASSER_KEY_FILE_PATH=<path to your eMASS key in PEM format>'.green
+      puts '  export EMASSER_CERT_FILE_PATH=<path to your eMASS certficate in PEM format>'.green
+      puts '  export EMASSER_KEY_FILE_PASSWORD=<password for the key given in EMASSER_KEY_FILE_PATH>'.green
+      puts 'Note: '.yellow + 'EMASSER_API_KEY is acquired by invoking the "emasser post register cert" API command'.cyan, "\n"
+      puts 'Actionable (POST,PUT,DELETE) variable required by some eMASS instances:'.yellow
+      puts '  export EMASSER_USER_UID=<unique identifier of the eMASS user EMASSER_API_KEY belongs to>'.green
+      puts "\n"
+      puts 'See eMASSer environment variables requirements in eMASSer CLI Features for more information (https://mitre.github.io/emasser/docs/features.html).'.yellow
+    end
+
+    def emasser_pki_help
+      puts 'eMASSer PKI Certificate Requirements:'.yellow
+      puts 'eMASSer uses a client (signed certificate) and key (private key to the certificate) certificate for authenticating to eMASS.'.cyan
+      puts 'Both files are pem (Privacy-Enhanced Mail) text-based containers using base-64 encoding. The key file requires a passphrase.'.cyan
+      puts "\n"
+      puts 'The following variables must be provided on the .env (configuration) file:'.yellow
+      puts '  EMASSER_HOST_URL          - The eMASS host URL'.cyan
+      puts '  EMASSER_CERT_FILE_PATH    - The client certificate (.pem) file (full path is required)'.cyan
+      puts '  EMASSER_KEY_FILE_PATH     - The private key for the certificate (.pem) file (full path is required)'.cyan
+      puts '  EMASSER_KEY_FILE_PASSWORD - The key file passphrase value if the key file password has been set'.cyan
+      puts 'IMPORTANT: If using a self signed certificate in the certificate chain the optional "EMASSER_VERIFY_SSL" variable must be set to false.'.red
+    end
+
+    if (ARGV[0].to_s.downcase.include? '-v') || (ARGV[0].to_s.downcase.include? '--V')
+      puts "emasser version: #{Emasser::VERSION}".green
+      exit
+    elsif ARGV[0].to_s.downcase.include? 'hello'
+      user_name = ENV.fetch('USERNAME', 'rookie')
+      puts "Hello #{user_name} - enjoy using eMASSer version #{Emasser::VERSION}!".cyan
+      exit
+    elsif ARGV[0].to_s.downcase.include? 'auth'
+      puts 'eMASS Authentication/Authorization Requirements:'.yellow
+      puts 'Every call to the eMASS API (via eMASSer) requires the use of a client certificate and an API key.'.cyan
+      puts 'A PKI-valid/trusted client certificate must be obtained from the owning eMASS instances that eMASSer is connecting to.'.cyan
+      puts 'An API key is also required. To obtain the API key, after configuring the PKI certificate, than'.cyan
+      puts 'invoke the following API command to retrieve the API key: "emasser post register cert")'.cyan
+      puts "\n"
+      puts 'eMASS Authentication Errors:'.red
+      puts 'If the API receives an untrusted certificate, a 403 forbidden response code will be returned.'.cyan
+      puts 'If an invalid api-key or combination of client certificate and api-key (from the registered account) is received, a 401 unauthorized response code will be returned.'.cyan
+      puts "\n"
+      show = Configuration.new
+      show.emasser_pki_help
+      exit
+    elsif (ARGV[0].to_s.downcase.include? 'help') || (ARGV[0].to_s.include? '-')
+      puts 'eMASSer Help'.yellow
+      puts 'eMASSer makes use of an environment configuration (.env) file for required and optional variables.'.cyan
+      puts 'The configuration file containing required variables must be located in the root directory where the eMASSer command is executed.'.cyan
+      puts "\n"
+      show = Configuration.new
+      show.emasser_pki_help
+      puts "\n"
+      puts 'See eMASSer environment variables requirements in eMASSer CLI Features for more information (https://mitre.github.io/emasser/docs/features.html).'.yellow
+      puts 'For eMASS Authentication Requirements invoke the eMASSer API command with the [auth]entication parameter (emasser auth)'.green
+      exit
+    elsif ARGV.empty?
+      puts 'eMASSer commands:'.yellow
+      puts '  emasser [get, put, post, delet] or [-h, --h, -v, -V, --version, --Version] or [help, Authentication, Authorization] '.yellow
+      exit
+    else
+      # rubocop: disable Style/TernaryParentheses, Style/IfWithBooleanLiteralBranches, Style/RedundantCondition
+      EmassClient.configure do |config|
+        # -----------------------------------------------------------------------
+        # Required env variables
+        config.scheme = 'https'
+        config.base_path = '/'
+        config.server_index = nil
+        config.api_key['api-key'] = raise_unless_present('EMASSER_API_KEY')
+        config.host = raise_unless_present('EMASSER_HOST_URL')
+        config.key_file = raise_unless_present('EMASSER_KEY_FILE_PATH')
+        config.cert_file = raise_unless_present('EMASSER_CERT_FILE_PATH')
+        config.key_password = raise_unless_present('EMASSER_KEY_FILE_PASSWORD')
+
+        # Some eMASS instances may not require this variable, others
+        # may required for actionable (POST,PUT,DELETE) requests
+        config.api_key['user-uid'] = ENV.fetch('EMASSER_USER_UID', '')
+
+        # -----------------------------------------------------------------------
+        # Optional env variables
+        config.client_side_validation = (ENV.fetch('EMASSER_CLIENT_SIDE_VALIDATION', 'true').eql? 'true') ? true : false
+        config.verify_ssl = (ENV.fetch('EMASSER_VERIFY_SSL', 'true').eql? 'true') ? true : false
+        config.verify_ssl_host = (ENV.fetch('EMASSER_VERIFY_SSL_HOST', 'true').eql? 'true') ? true : false
+        config.debugging = (ENV.fetch('EMASSER_DEBUGGING', 'false') == 'false') ? false : true
+        config.temp_folder_path = check_folder_exists('EMASSER_DOWNLOAD_DIR')
+      end
+      # rubocop: enable Style/TernaryParentheses, Style/IfWithBooleanLiteralBranches, Style/RedundantCondition
     end
-    # rubocop: enable Style/TernaryParentheses, Style/IfWithBooleanLiteralBranches
   end
 end

data/lib/emasser/constants.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Emasser
+  GET_REGISTER_RETURN_TYPE = {
+    debug_return_type: 'Object'
+  }.freeze
+
   GET_SYSTEM_ID_QUERY_PARAMS = {
     include_package: false,
     include_ditpr_metrics: false,
@@ -19,8 +23,4 @@ module Emasser
   GET_WORKFLOWINSTANCES_RETURN_TYPE = {
     debug_return_type: 'Object'
   }.freeze
-
-  DEL_MILESTONES_RETURN_TYPE = {
-    debug_return_type: 'Object'
-  }.freeze
 end

data/lib/emasser/delete.rb

@@ -51,11 +51,11 @@ module Emasser
     long_desc Help.text(:poam_del_mapper)
 
     # Required parameters/fields
-    option :systemId, type: :numeric, required: true, desc: 'A numeric value representing the system identification'
-    option :poamId,   type: :numeric, required: true, desc: 'A numeric value representing the poam identification'
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :poamId, aliases: '-p', type: :numeric, required: true, desc: 'A numeric value representing the poam identification'
 
     def remove
-      body = EmassClient::PoamGet.new
+      body = EmassClient::PoamRequestDeleteBodyInner.new
       body.poam_id = options[:poamId]
       body_array = Array.new(1, body)
 
@@ -80,26 +80,24 @@ module Emasser
     long_desc Help.text(:milestone_del_mapper)
 
     # Required parameters/fields
-    option :systemId,    type: :numeric, required: true,
+    option :systemId, aliases: '-s', type: :numeric, required: true,
                          desc: 'A numeric value representing the system identification'
-    option :poamId,      type: :numeric, required: true,
+    option :poamId, aliases: '-p', type: :numeric, required: true,
                          desc: 'A numeric value representing the poam identification'
-    option :milestoneId, type: :numeric, required: true,
+    option :milestoneId, aliases: '-m', type: :numeric, required: true,
                          desc: 'A numeric value representing the milestone identification'
 
     def remove
-      body = EmassClient::MilestonesGet.new
+      body = EmassClient::MilestonesRequestDeleteBodyInner.new
       body.milestone_id = options[:milestoneId]
       body_array = Array.new(1, body)
 
-      # Getting an empty return when utilizing the default return type - using 'Object' as return type
-      opts = Emasser::DEL_MILESTONES_RETURN_TYPE
-
-      result = EmassClient::MilestonesApi.new.delete_milestone(options[:systemId], options[:poamId], body_array, opts)
+      result = EmassClient::MilestonesApi.new.delete_milestone(options[:systemId], options[:poamId], body_array)
+      # The server returns an empty object upon successfully deleting a milestone.
       puts to_output_hash(result).green
     rescue EmassClient::ApiError => e
       puts 'Exception when calling MilestonesApi->delete_milestone'.red
-      puts to_output_hash(e).yellow
+      puts to_output_hash(e)
     end
   end
 
@@ -113,11 +111,11 @@ module Emasser
     end
 
     desc 'remove', 'Delete one or many artifacts in a system'
-    long_desc Help.text(:artifact_del_mapper)
+    long_desc Help.text(:artifacts_del_mapper)
 
     # Required parameters/fields
-    option :systemId, type: :numeric, required: true, desc: 'A numeric value representing the system identification'
-    option :files, type: :array, required: true, desc: 'Artifact file(s) to remove from the given system'
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :files, aliases: '-f', type: :array, required: true, desc: 'Artifact file(s) to remove from the given system'
 
     def remove
       body_array = []
@@ -135,6 +133,126 @@ module Emasser
     end
   end
 
+  # Remove one or many hardware assets in a system
+  #
+  # Endpoint:
+  #    /api/systems/{systemId}/hw-baseline
+  class Hardware < SubCommandBase
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'remove', 'Delete one or many hardware assets in a system'
+
+    # Required parameters/fields
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :hardwareIds, aliases: '-w', type: :array, required: true, desc: 'GUID identifying the specific hardware asset'
+
+    def remove
+      body_array = []
+      options[:hardwareIds].each do |hardware|
+        obj = {}
+        obj[:hardwareId] = hardware
+        body_array << obj
+      end
+
+      result = EmassClient::HardwareBaselineApi.new.delete_hw_baseline_assets(options[:systemId], body_array)
+      puts to_output_hash(result).green
+    rescue EmassClient::ApiError => e
+      puts 'Exception when calling HardwareBaselineApi->delete_hw_baseline_assets'.red
+      puts to_output_hash(e)
+    end
+  end
+
+  # Remove one or many software assets in a system
+  #
+  # Endpoint:
+  #    /api/systems/{systemId}/sw-baseline
+  class Software < SubCommandBase
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'remove', 'Delete one or many software assets in a system'
+
+    # Required parameters/fields
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :softwareIds, aliases: '-w', type: :array, required: true, desc: 'GUID identifying the specific software asset'
+
+    def remove
+      body_array = []
+      options[:softwareIds].each do |software|
+        obj = {}
+        obj[:softwareId] = software
+        body_array << obj
+      end
+
+      result = EmassClient::SoftwareBaselineApi.new.delete_sw_baseline_assets(options[:systemId], body_array)
+      puts to_output_hash(result).green
+    rescue EmassClient::ApiError => e
+      puts 'Exception when calling SoftwareBaselineApi->delete_sw_baseline_assets'.red
+      puts to_output_hash(e)
+    end
+  end
+
+  # The Cloud Resource Results endpoint provides the ability to remove
+  # cloud resources and their scan results in the assets module for a system.
+  #
+  # Endpoint:
+  #  /api/systems/{systemId}/cloud-resource-results
+  class CloudResource < SubCommandBase
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'remove', 'Delete one or many Cloud Resources and their scan results in the assets module for a system'
+
+    # Required parameters/fields
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :resourceId, aliases: '-r', type: :string, required: true, desc: 'Unique identifier/resource namespace for policy compliance result'
+
+    def remove
+      body = EmassClient::CloudResourcesDeleteBodyInner.new
+      body.resource_id = options[:resourceId]
+      body_array = Array.new(1, body)
+
+      result = EmassClient::CloudResourceResultsApi.new.delete_cloud_resources(options[:systemId], body_array)
+      puts to_output_hash(result).green
+    rescue EmassClient::ApiError => e
+      puts 'Exception when calling CloudResourceResultsApi->delete_cloud_resources'.red
+      puts to_output_hash(e)
+    end
+  end
+
+  # The Container Scan Results endpoint provides the ability to remove
+  # containers and their scan results in the assets module for a system.
+  #
+  # Endpoint:
+  #  /api/systems/{systemId}/container-scan-results
+  class Container < SubCommandBase
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'remove', 'Delete one or many containers scan results in the assets module for a system'
+
+    # Required parameters/fields
+    option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
+    option :containerId, aliases: '-c', type: :string, required: true, desc: 'Unique identifier of the container'
+
+    def remove
+      body = EmassClient::ContainerResourcesDeleteBodyInner.new
+      body.container_id = options[:containerId]
+      body_array = Array.new(1, body)
+
+      result = EmassClient::ContainerScanResultsApi.new.delete_container_sans(options[:systemId], body_array)
+      puts to_output_hash(result).green
+    rescue EmassClient::ApiError => e
+      puts 'Exception when calling ContainerScanResultsApi->delete_container_sans'.red
+      puts to_output_hash(e)
+    end
+  end
+
   class Delete < SubCommandBase
     desc 'poams', 'Delete Plan of Action and Milestones (POA&M) items for a system'
     subcommand 'poams', Poams
@@ -144,5 +262,17 @@ module Emasser
 
     desc 'artifacts', 'Delete system Artifacts'
     subcommand 'artifacts', Artifacts
+
+    desc 'hardware', 'Delete one or many hardware assets to a system'
+    subcommand 'hardware', Hardware
+
+    desc 'software', 'Delete one or many software assets to a system'
+    subcommand 'software', Software
+
+    desc 'cloud_resource', 'Delete cloud resource and their scan results'
+    subcommand 'cloud_resource', CloudResource
+
+    desc 'container', 'Delete container and their scan results'
+    subcommand 'container', Container
   end
 end

data/lib/emasser/errors.rb

@@ -11,4 +11,13 @@ module Emasser
       super("#{message} #{@config}")
     end
   end
+
+  class ConfigurationEmptyValueError < Error
+    attr_reader :config
+
+    def initialize(config = 'an option', message = 'Environment variable cannot be an empty:')
+      @config = config
+      super("#{message} #{@config}")
+    end
+  end
 end