secure-keys 1.1.7 → 1.2.0

data/lib/core/console/arguments/fetchable.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Core
+    module Console
+      module Argument
+        # Shared fetch/set behaviour for argument handler classes.
+        # Include this module inside +class << self+ so the methods become
+        # class-level accessors that check the handler's own +arguments+ hash
+        # before falling back to environment variables.
+        #
+        # The including class must expose +arguments+ as a class-level reader
+        # (via +attr_reader :arguments+ inside +class << self+).
+        module Fetchable
+          # Fetch an argument value, falling back to SECURE_KEYS_<KEY>,
+          # then the bare <KEY> environment variable, then +default+.
+          #
+          # @param key [Symbol, Array<Symbol>] The argument key (or nested key path)
+          # @param default [Object] The value to return when nothing is found
+          # @return [Object] The resolved value
+          def fetch(key:, default: nil)
+            keys = Array(key).map(&:to_sym)
+            joined_keys = keys.join('_').upcase
+            arguments.dig(*keys) || ENV["SECURE_KEYS_#{joined_keys}"] || ENV[joined_keys] || default
+          end
+
+          # Update a single argument value
+          # @param key [Symbol] The argument key to update
+          # @param value [Object] The new value
+          # @return [void]
+          def set(key:, value:)
+            arguments[key.to_sym] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/core/console/arguments/handler.rb

@@ -1,9 +1,13 @@
+require_relative 'fetchable'
+
 module SecureKeys
   module Core
     module Console
       module Argument
         class Handler
           class << self
+            include Fetchable
+
             attr_reader :arguments
           end
 
@@ -16,31 +20,11 @@ module SecureKeys
             verbose: false,
           }
 
-          # Fetch the argument value by key
-          # from CLI arguments or environment variables
-          #
-          # @param key [Array|Symbol] the argument key
-          # @param default [String] the default value
-          #
-          # @return [String] the argument value
-          def self.fetch(key:, default: nil)
-            keys = Array(key).map(&:to_sym)
-            joined_keys = keys.join('_').upcase
-            @arguments.dig(*keys) || ENV["SECURE_KEYS_#{joined_keys}"] || ENV[joined_keys] || default
-          end
-
-          # Set the value of the key
-          # @param key [Symbol] the key to be updated
-          # @param value [String] the value to be updated
-          def self.set(key:, value:)
-            @arguments[key.to_sym] = value
-          end
-
-          # Append the argument value by key
+          # Append a hash value into a nested key, initialising it when absent
           # @param key [Symbol] the argument key
-          # @param value [String] the argument value
+          # @param value [Hash] the hash to merge in
           def self.deep_merge(key:, value:)
-            @arguments[key.to_sym] ||= {} # Initialize the key if it doesn't exist
+            @arguments[key.to_sym] ||= {}
             @arguments[key.to_sym].merge!(value)
           end
         end

data/lib/core/console/arguments/parser.rb

@@ -15,6 +15,11 @@ module SecureKeys
             super('Usage: secure-keys [--options]')
             separator('')
 
+            # Route known subcommands before processing flags.
+            # Like --help and --version, subcommand handlers exit internally,
+            # so the generator is never reached.
+            route_subcommand!
+
             # Configure the argument parser
             configure!
             order!(into: Handler.arguments)
@@ -23,6 +28,27 @@ module SecureKeys
 
           private
 
+          # Known positional subcommands mapped to their handler lambdas.
+          # Each lambda is expected to handle its own output and exit.
+          SUBCOMMANDS = {
+            'validate' => lambda {
+              require_relative '../../../validation/console/arguments/parser'
+              Validation::Console::Argument::Parser.new.execute
+            },
+          }.freeze
+
+          # Detect a known positional subcommand as the first ARGV token and delegate
+          # to its handler. Like --help and --version, the handler exits internally so
+          # the generator is never reached.
+          # @return [void]
+          def route_subcommand!
+            token = ARGV.first
+            return unless SUBCOMMANDS.key?(token)
+
+            ARGV.shift
+            SUBCOMMANDS[token].call
+          end
+
           # Configure the argument parser
           def configure!
             on('-h', '--help', 'Use the provided commands to select the params') do

data/lib/core/environment/ci.rb

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+require_relative '../console/logger'
+
 module SecureKeys
   module Core
     module Environment
@@ -8,9 +10,20 @@ module SecureKeys
         # @param key [String] the key of the environment variable to fetch
         # @return [String] the value of the environment variable
         def fetch(key:)
-          ENV.fetch(key)
+          normalized_key = key.to_s.tr('-', '_').upcase
+
+          ENV[key.to_s] ||
+            ENV[normalized_key] ||
+            ENV["SECURE_KEYS_#{normalized_key}"] ||
+            inline_identifier_value(key)
         rescue StandardError
-          puts "❌ Error fetching the key: #{key} from ENV variables"
+          Core::Console::Logger.error(message: "Error fetching the key '#{key}' from ENV variables")
+        end
+
+        private
+
+        def inline_identifier_value(key)
+          key if key.to_s.include?(SecureKeys::Globals.key_delimiter)
         end
       end
     end

data/lib/core/generator.rb

@@ -45,10 +45,10 @@ module SecureKeys
           generate_swift_package
           write_keys
           xcframework.generate
+          post_actions
         end
 
         xcframework.configure_xcframework_to_xcodeproj
-        post_actions if Globals.generate_xcframework?
       end
 
       private

data/lib/services/environment.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Services
+    module Environment
+      module_function
+
+      # Fetches the value of an environment variable with support for SecureKeys prefix
+      # @param key [Symbol] The environment variable key to fetch
+      # @param default [Object] The default value to return if the environment variable is not set
+      # @return [Object, nil] The value of the environment variable or the default value
+      def fetch(key:, default: nil)
+        formatted_key = key.to_s.upcase
+        ENV[formatted_key] || ENV["SECURE_KEYS_#{formatted_key}"] || default
+      end
+
+      # Fetches the integer value of an environment variable with support for SecureKeys prefix
+      # @param key [Symbol] The environment variable key to fetch
+      # @param default [Object] The default value to return if the environment variable is not set or cannot be converted to an integer
+      # @return [Integer, nil] The integer value of the environment variable or the default value
+      def integer(key:, default: nil)
+        value = fetch(key:, default:)
+        Integer(value)
+      rescue ArgumentError, TypeError
+        # Returns default if it's nil or integer, otherwise, force return nil
+        default.is_a?(Integer) || default.nil? ? default : nil
+      end
+
+      def decimal(key:, default: nil)
+        value = fetch(key:, default:)
+        Float(value)
+      rescue ArgumentError, TypeError
+        # Returns default if it's nil or float, otherwise, force return nil
+        default.is_a?(Float) || default.nil? ? default : nil
+      end
+    end
+  end
+end

data/lib/validation/actions/scan.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require_relative '../console/arguments/scan/handler'
+require_relative '../../core/console/logger'
+require_relative '../scanner'
+
+module SecureKeys
+  module Validation
+    module Actions
+      # Executes the `validate scan` action: runs the scanner, prints a formatted
+      # report to the console, optionally saves a JSON report, and exits with an
+      # appropriate code (0 = clean, 1 = findings present).
+      class Scan
+        # Run the scan, print the report, and exit
+        # @return [void]
+        def run
+          result = execute_scan
+          print_result(result:)
+          save_report(result:) if Console::Argument::Scan::Handler.fetch(key: :output)
+          exit(result.clean? ? 0 : 1)
+        end
+
+        private
+
+        # Build optional scanner overrides from CLI arguments via Handler.fetch
+        # @return [Hash] A sparse options hash (only keys explicitly provided by the user)
+        def scanner_options
+          options = {}
+
+          if (extensions = Console::Argument::Scan::Handler.fetch(key: :extensions))
+            options[:extensions] = extensions.split(',').map(&:strip)
+          end
+
+          if (excludes = Console::Argument::Scan::Handler.fetch(key: :excludes))
+            options[:excludes] = excludes.split(',').map(&:strip)
+          end
+
+          options
+        end
+
+        # Run the appropriate scan based on the --staged flag
+        # @return [ScanResult] The result of the scan
+        def execute_scan
+          scanner = Scanner.new(options: scanner_options)
+
+          if Console::Argument::Scan::Handler.fetch(key: :staged, default: false)
+            Core::Console::Logger.important(message: 'Scanning staged git changes...')
+            scanner.scan_git_diff(staged_only: true)
+          else
+            path = Console::Argument::Scan::Handler.fetch(key: :path, default: '.')
+            Core::Console::Logger.important(message: "Scanning directory: #{path}")
+            scanner.scan_directory(path:)
+          end
+        end
+
+        # Print a formatted scan report to the console
+        # @param result [ScanResult] The scan result to display
+        # @return [void]
+        def print_result(result:)
+          separator = '-' * 70
+
+          Core::Console::Logger.message(message: separator)
+          Core::Console::Logger.message(message: "\tFiles scanned:  #{result.files_count}")
+          Core::Console::Logger.message(message: "\tFindings:       #{result.findings.length}")
+          Core::Console::Logger.message(message: separator)
+
+          if result.clean?
+            Core::Console::Logger.success(message: "\t✅ No secrets found")
+          else
+            print_severity_summary(result:)
+            Core::Console::Logger.message(message: separator)
+            print_findings(result:)
+          end
+
+          Core::Console::Logger.message(message: separator)
+        end
+
+        # Print a per-severity count breakdown
+        # @param result [ScanResult] The scan result
+        # @return [void]
+        def print_severity_summary(result:)
+          counts = {
+            critical: result.by_severity(severity: :critical).length,
+            high: result.by_severity(severity: :high).length,
+            medium: result.by_severity(severity: :medium).length,
+            low: result.by_severity(severity: :low).length,
+          }
+
+          Core::Console::Logger.error(message: "\t🔴 Critical:  #{counts[:critical]}") if counts[:critical].positive?
+          Core::Console::Logger.warning(message: "\t🟠 High:      #{counts[:high]}")     if counts[:high].positive?
+          Core::Console::Logger.warning(message: "\t🟡 Medium:    #{counts[:medium]}")   if counts[:medium].positive?
+          Core::Console::Logger.message(message: "\t🔵 Low:       #{counts[:low]}")      if counts[:low].positive?
+        end
+
+        # Print each finding grouped by severity level
+        # @param result [ScanResult] The scan result
+        # @return [void]
+        def print_findings(result:)
+          %i[critical high medium low].each do |severity|
+            findings = result.by_severity(severity:)
+            next if findings.empty?
+
+            Core::Console::Logger.message(message: "\t#{severity.to_s.upcase} (#{findings.length}):")
+
+            findings.each do |finding|
+              Core::Console::Logger.message(message: "\t\t#{finding}")
+              Core::Console::Logger.message(message: "\t\t└ #{finding.full_line}")
+            end
+
+            Core::Console::Logger.message(message: '')
+          end
+        end
+
+        # Save the scan result as a pretty-printed JSON report
+        # @param result [ScanResult] The scan result to serialise
+        # @return [void]
+        def save_report(result:)
+          output = Console::Argument::Scan::Handler.fetch(key: :output)
+          File.write(output, JSON.pretty_generate(result.to_h))
+          Core::Console::Logger.success(message: "Report saved to: #{output}")
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/parser.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require_relative '../../../core/console/logger'
+require_relative 'scan/handler'
+require_relative 'scan/parser'
+require_relative '../../actions/scan'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        # Routes the `validate` subcommand to the appropriate sub-parser and action.
+        # The constructor reads the subcommand token from ARGV; +execute+ then
+        # delegates to the matching sub-parser and runs the action.
+        class Parser < OptionParser
+          # Initialize the validate argument parser and capture the subcommand token
+          def initialize
+            super('Usage: secure-keys validate [subcommand] [--options]')
+            separator('')
+            configure!
+            @subcommand = ARGV.shift
+          end
+
+          # Dispatch to the correct sub-parser and action based on the subcommand
+          # @return [void]
+          def execute
+            case @subcommand
+            when 'scan'
+              Scan::Parser.new
+              Actions::Scan.new.run
+            when nil, '--help', '-h'
+              puts self
+              exit(0)
+            else
+              Core::Console::Logger.error(message: "Unknown validate subcommand: '#{@subcommand}'")
+              puts self
+              exit(1)
+            end
+          end
+
+          private
+
+          # Configure the validate-level help text and available subcommands
+          # @return [void]
+          def configure!
+            on('-h', '--help', 'Show help for the validate command') do
+              puts self
+              exit(0)
+            end
+            separator('')
+            separator('Subcommands:')
+            separator("\tscan [path]   Scan a directory or staged git changes for exposed secrets")
+            separator('')
+            separator('Examples:')
+            separator("\tsecure-keys validate scan")
+            separator("\tsecure-keys validate scan ./src")
+            separator("\tsecure-keys validate scan --staged")
+            separator("\tsecure-keys validate scan --output report.json")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/scan/handler.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+require_relative '../../../../core/console/arguments/fetchable'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        module Scan
+          # Stores and provides access to the resolved CLI arguments for the scan subcommand
+          class Handler
+            class << self
+              include Core::Console::Argument::Fetchable
+
+              attr_reader :arguments
+            end
+
+            # Default argument values for the scan subcommand
+            @arguments = {
+              path: '.',
+              staged: false,
+              output: nil,
+              extensions: nil,
+              excludes: nil,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validation/console/arguments/scan/parser.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require_relative 'handler'
+require_relative '../../../../core/console/arguments/handler'
+
+module SecureKeys
+  module Validation
+    module Console
+      module Argument
+        module Scan
+          # Parses CLI options for the `secure-keys validate scan` subcommand.
+          # Uses +parse!+ so options and positional arguments may appear in any order;
+          # after parsing, any remaining ARGV token is treated as the scan path.
+          class Parser < OptionParser
+            # Initialize the scan parser, process ARGV, and store results in Handler
+            def initialize
+              super('Usage: secure-keys validate scan [path] [--options]')
+              separator('')
+              configure!
+              parse!(into: Handler.arguments)
+              Handler.set(key: :path, value: ARGV.shift) unless ARGV.empty?
+            end
+
+            private
+
+            # Define all accepted options for the scan subcommand
+            # @return [void]
+            def configure!
+              on('-h', '--help', 'Show help for the scan subcommand') do
+                puts self
+                exit(0)
+              end
+              on('--staged', 'Scan staged git changes instead of a directory (default: false)') do
+                Handler.set(key: :staged, value: true)
+              end
+              on(
+                '-o', '--output FILE',
+                String,
+                'Save the scan report as JSON to FILE'
+              )
+              on(
+                '--extensions EXTENSIONS',
+                String,
+                'Comma-separated file extensions to scan (e.g. .rb,.swift)'
+              )
+              on(
+                '--excludes EXCLUDES',
+                String,
+                'Comma-separated directory names to exclude from the scan'
+              )
+              on('--verbose', 'Enable verbose output (default: false)') do
+                Core::Console::Argument::Handler.set(key: :verbose, value: true)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/validation/globals/globals.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require_relative '../../services/environment'
+
+module SecureKeys
+  module Validation
+    module Globals
+      module_function
+
+      # Returns the minimum length for an API key
+      # @return [Integer] The minimum length for an API key
+      def api_key_length
+        Services::Environment.integer(key: :api_key_length, default: 20)
+      end
+
+      # Returns the minimum length for a token
+      # @return [Integer] The minimum length for a token
+      def token_length
+        Services::Environment.integer(key: :token_length, default: 20)
+      end
+
+      # Returns the minimum length for a secret
+      # @return [Integer] The minimum length for a secret
+      def secret_length
+        Services::Environment.integer(key: :secret_length, default: 16)
+      end
+
+      # Returns the minimum length for a password
+      # @return [Integer] The minimum length for a password
+      def password_length
+        Services::Environment.integer(key: :password_length, default: 12)
+      end
+
+      # Returns the minimum length for a generic key
+      # @return [Integer] The minimum length for a key
+      def key_length
+        Services::Environment.integer(key: :key_length, default: 16)
+      end
+
+      # Returns the default file extensions to scan
+      # @return [Array<String>] The default file extensions
+      def default_scan_extensions
+        Services::Environment.fetch(
+          key: :scan_extensions,
+          default: '.swift,.m,.mm,.h,.rb,.py,.js,.ts,.java,.kt,.yaml,.yml,.json,.env,.plist'
+        ).split(',')
+      end
+
+      # Returns the default directory and file names to exclude from scanning
+      # @return [Array<String>] The default exclude patterns
+      def default_scan_excludes
+        Services::Environment.fetch(
+          key: :scan_excludes,
+          default: '.git,node_modules,Pods,build,DerivedData,.build,vendor,.bundle,Carthage,.secure-keys,coverage'
+        ).split(',')
+      end
+
+      # Returns the maximum directory traversal depth for scanning
+      # @return [Integer] The maximum scan depth
+      def max_scan_depth
+        Services::Environment.integer(key: :max_scan_depth, default: 10)
+      end
+
+      # Returns the minimum Shannon entropy threshold for secret validation
+      # @return [Float] The minimum entropy threshold
+      def min_entropy_threshold
+        Services::Environment.decimal(key: :min_entropy_threshold, default: 3.0)
+      end
+    end
+  end
+end

data/lib/validation/models/finding.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Validation
+    # Represents a single secret detected during a file or git diff scan
+    class Finding
+      attr_reader :file, :line, :column, :type, :description, :severity,
+                  :matched_text, :full_line, :is_addition
+
+      # Initialize a new finding
+      # @param file [String] The file path where the secret was found
+      # @param line [Integer] The line number where the secret was found
+      # @param column [Integer] The column offset of the match within the line
+      # @param type [Symbol] The pattern type that matched (e.g. :github_token, :aws_access_key)
+      # @param description [String] A human-readable description of the secret type
+      # @param severity [Symbol] The severity level (:low, :medium, :high, :critical)
+      # @param matched_text [String] The masked matched text, safe for display
+      # @param full_line [String] The full trimmed line of code containing the secret
+      # @param is_addition [Boolean] Whether this line is an addition in a git diff (default: false)
+      def initialize(file:, line:, column:, type:, description:, severity:,
+                     matched_text:, full_line:, is_addition: false)
+        @file = file
+        @line = line
+        @column = column
+        @type = type
+        @description = description
+        @severity = severity
+        @matched_text = matched_text
+        @full_line = full_line
+        @is_addition = is_addition
+      end
+
+      # Check if this finding came from a git diff addition
+      # @return [Boolean] true if the line is a git diff addition
+      def addition?
+        is_addition
+      end
+
+      # Returns a one-line string representation of the finding
+      # @return [String] The formatted finding string
+      def to_s
+        "#{severity_icon} #{file}:#{line}:#{column} [#{type}] #{description} — #{matched_text}"
+      end
+
+      # Returns a hash representation of the finding
+      # @return [Hash] The hash representation
+      def to_h
+        {
+          file:,
+          line:,
+          column:,
+          type:,
+          description:,
+          severity:,
+          matched_text:,
+          full_line:,
+          is_addition:,
+        }
+      end
+
+      private
+
+      # Returns the appropriate icon for the severity level
+      # @return [String] The severity icon
+      def severity_icon
+        case severity
+        when :critical then '🔴'
+        when :high then '🟠'
+        when :medium then '🟡'
+        when :low then '🔵'
+        else '⚪'
+        end
+      end
+    end
+  end
+end