emasser 3.12.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.12'
+  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,

data/lib/emasser/delete.rb

@@ -125,7 +125,7 @@ module Emasser
         body_array << obj
       end
 
-      result = EmassClient::ArtifactsApi.new.delete_artifact(body_array, options[:systemId])
+      result = EmassClient::ArtifactsApi.new.delete_artifact(options[:systemId], body_array)
       puts to_output_hash(result).green
     rescue EmassClient::ApiError => e
       puts 'Exception when calling ArtifactsApi->delete_artifact'.red
@@ -133,11 +133,73 @@ 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 - Remove one or many cloud resources in a system
+  #  /api/systems/{systemId}/cloud-resource-results
   class CloudResource < SubCommandBase
     def self.exit_on_failure?
       true
@@ -147,7 +209,7 @@ module Emasser
 
     # Required parameters/fields
     option :systemId, aliases: '-s', type: :numeric, required: true, desc: 'A numeric value representing the system identification'
-    option :resourceId, aliases: '-c', type: :string, required: true, desc: 'Unique identifier/resource namespace for policy compliance result'
+    option :resourceId, aliases: '-r', type: :string, required: true, desc: 'Unique identifier/resource namespace for policy compliance result'
 
     def remove
       body = EmassClient::CloudResourcesDeleteBodyInner.new
@@ -157,7 +219,7 @@ module Emasser
       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 MilestonesApi->delete_cloud_resources'.red
+      puts 'Exception when calling CloudResourceResultsApi->delete_cloud_resources'.red
       puts to_output_hash(e)
     end
   end
@@ -166,7 +228,7 @@ module Emasser
   # containers and their scan results in the assets module for a system.
   #
   # Endpoint:
-  #  /api/systems/{systemId}/container-scan-results - Remove one or many containers in a system
+  #  /api/systems/{systemId}/container-scan-results
   class Container < SubCommandBase
     def self.exit_on_failure?
       true
@@ -180,13 +242,13 @@ module Emasser
 
     def remove
       body = EmassClient::ContainerResourcesDeleteBodyInner.new
-      body.containerId = options[:containerId]
+      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 MilestonesApi->delete_cloud_resources'.red
+      puts 'Exception when calling ContainerScanResultsApi->delete_container_sans'.red
       puts to_output_hash(e)
     end
   end
@@ -201,6 +263,12 @@ 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
 

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