secure-keys 1.1.6 → 1.2.0

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

data/lib/validation/models/scan_result.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Validation
+    # Aggregates all findings from a single scan run
+    class ScanResult
+      attr_reader :findings, :files_count
+
+      # Initialize a new scan result
+      # @param findings [Array<Finding>] The list of detected secrets
+      # @param files_count [Integer] The total number of files (or diff lines) scanned
+      def initialize(findings:, files_count:)
+        @findings = findings
+        @files_count = files_count
+      end
+
+      # Check if the scan produced no findings
+      # @return [Boolean] true if no secrets were detected
+      def clean?
+        findings.empty?
+      end
+
+      # Returns findings filtered by a specific severity level
+      # @param severity [Symbol] The severity to filter by (:low, :medium, :high, :critical)
+      # @return [Array<Finding>] Findings matching the given severity
+      def by_severity(severity:)
+        findings.select { |finding| finding.severity == severity }
+      end
+
+      # Returns a hash representation of the scan result
+      # @return [Hash] The hash representation, suitable for JSON export
+      def to_h
+        {
+          files_scanned: files_count,
+          total_findings: findings.length,
+          by_severity: {
+            critical: by_severity(severity: :critical).length,
+            high: by_severity(severity: :high).length,
+            medium: by_severity(severity: :medium).length,
+            low: by_severity(severity: :low).length,
+          },
+          findings: findings.map(&:to_h),
+        }
+      end
+    end
+  end
+end

data/lib/validation/scanner.rb

@@ -0,0 +1,269 @@
+#!/usr/bin/env ruby
+
+require_relative '../core/console/logger'
+require_relative '../core/console/shell'
+require_relative 'globals/globals'
+require_relative 'utils/patterns'
+require_relative 'models/finding'
+require_relative 'models/scan_result'
+
+module SecureKeys
+  module Validation
+    # Scans files and git diffs for exposed secrets using the known PATTERNS set
+    class Scanner
+      private
+
+      attr_accessor :findings, :options
+
+      public
+
+      # Initialize a new scanner
+      # @param options [Hash] Override specific default scanning options
+      # @option options [Array<String>] :extensions File extensions to include in the scan
+      # @option options [Array<String>] :excludes Directory and file names to exclude
+      # @option options [Integer] :max_depth Maximum directory traversal depth
+      # @option options [Boolean] :follow_symlinks Whether to follow symbolic links
+      def initialize(options: {})
+        self.options = default_options.merge(options)
+        self.findings = []
+      end
+
+      # Scan a directory recursively for exposed secrets
+      # @param path [String] The root directory path to scan (default: current directory)
+      # @param options [Hash] Additional options to merge for this scan only
+      # @return [ScanResult] The aggregated scan result
+      def scan_directory(path: '.', options: {})
+        self.findings = []
+        self.options = self.options.merge(options)
+
+        Core::Console::Logger.verbose(message: "Scanning directory: #{path}")
+        Core::Console::Logger.verbose(message: "Extensions: #{file_extensions.join(', ')}")
+        Core::Console::Logger.verbose(message: "Excludes: #{exclude_patterns.join(', ')}")
+
+        files = find_files(path:)
+
+        Core::Console::Logger.verbose(message: "Found #{files.length} files to scan")
+
+        files.each { |file| scan_file(file_path: file) }
+
+        ScanResult.new(findings:, files_count: files.length)
+      end
+
+      # Scan staged or unstaged git changes for exposed secrets
+      # @param staged_only [Boolean] When true, scans only staged changes (default: true)
+      # @return [ScanResult] The aggregated scan result
+      def scan_git_diff(staged_only: true)
+        self.findings = []
+
+        command = staged_only ? 'git diff --cached' : 'git diff'
+        diff_output, = Core::Console::Shell.sh(command:)
+
+        return ScanResult.new(findings: [], files_count: 0) if diff_output.strip.empty?
+
+        current_file = nil
+        line_number = 0
+
+        diff_output.each_line do |line|
+          if line.start_with?('+++')
+            current_file = line.sub(%r{^\+\+\+ b/}, '').strip
+            line_number = 0
+          elsif line.start_with?('@@') && current_file
+            hunk_match = line.match(/\+(\d+)/)
+            line_number = hunk_match ? hunk_match[1].to_i - 1 : 0
+          elsif line.start_with?('+') && current_file && !line.start_with?('+++')
+            line_number += 1
+            check_line(
+              file_path: current_file,
+              line_number:,
+              line: line[1..],
+              is_addition: true
+            )
+          end
+        end
+
+        ScanResult.new(findings:, files_count: diff_output.lines.count)
+      end
+
+      private
+
+      # Scan a single file line by line for exposed secrets
+      # @param file_path [String] The path to the file to scan
+      def scan_file(file_path:)
+        return unless File.file?(file_path)
+
+        Core::Console::Logger.verbose(message: "Scanning #{file_path}...")
+
+        content = File.read(file_path)
+        line_number = 0
+
+        content.each_line do |line|
+          line_number += 1
+          check_line(file_path:, line_number:, line:)
+        end
+      rescue StandardError => e
+        Core::Console::Logger.verbose(message: "Failed to scan #{file_path}: #{e.message}")
+      end
+
+      # Check a single line against all known secret patterns and suspicious assignments
+      # @param file_path [String] The path of the file being scanned
+      # @param line_number [Integer] The current line number within the file
+      # @param line [String] The content of the line to check
+      # @param is_addition [Boolean] Whether the line is a git diff addition (default: false)
+      def check_line(file_path:, line_number:, line:, is_addition: false)
+        return if line.strip.start_with?('#', '//', '/*', '*')
+        return if line.length < 10
+
+        seen = {}
+
+        PATTERNS.each do |type, config|
+          match = line.match(config[:pattern])
+          next unless match
+
+          signature = [match.begin(0), match[0]]
+          next if seen[signature]
+
+          seen[signature] = true
+          masked = mask_secret(secret: match[0])
+
+          findings << Finding.new(
+            file: file_path,
+            line: line_number,
+            column: match.begin(0),
+            type:,
+            description: config[:description],
+            severity: config[:severity],
+            matched_text: masked,
+            full_line: line.strip.sub(match[0], masked),
+            is_addition:
+          )
+        end
+
+        check_suspicious_assignments(file_path:, line_number:, line:, is_addition:)
+      end
+
+      # Check a line for generic suspicious variable assignment patterns not caught by PATTERNS
+      # @param file_path [String] The path of the file being scanned
+      # @param line_number [Integer] The current line number within the file
+      # @param line [String] The content of the line
+      # @param is_addition [Boolean] Whether the line is a git diff addition
+      def check_suspicious_assignments(file_path:, line_number:, line:, is_addition:)
+        suspicious_pattern = /(?i)(api_?key|secret|token|password|passwd|pwd|auth|credential)\s*[=:]\s*['"]([^'"]{8,})['"]/
+
+        return unless line.match?(suspicious_pattern)
+        return if already_matched_by_pattern?(line:)
+
+        match = line.match(suspicious_pattern)
+        masked = mask_secret(secret: match[0])
+
+        findings << Finding.new(
+          file: file_path,
+          line: line_number,
+          column: match.begin(0),
+          type: :suspicious_assignment,
+          description: 'Suspicious secret assignment',
+          severity: :low,
+          matched_text: masked,
+          full_line: line.strip.sub(match[0], masked),
+          is_addition:
+        )
+      end
+
+      # Check whether a line was already captured by one of the specific PATTERNS
+      # @param line [String] The line content to check
+      # @return [Boolean] true if the line matches any known pattern
+      def already_matched_by_pattern?(line:)
+        PATTERNS.values.any? { |config| line.match?(config[:pattern]) }
+      end
+
+      # Recursively find all scannable files under a root path
+      # @param path [String] The root directory path
+      # @return [Array<String>] The list of matching absolute file paths
+      def find_files(path:)
+        result = []
+        traverse_directory(
+          path:,
+          result:,
+          current_depth: 0,
+          max_depth: options.fetch(:max_depth, Globals.max_scan_depth)
+        )
+        result
+      end
+
+      # Recursively traverse a directory, collecting files that match the scan criteria
+      # @param path [String] The current directory path
+      # @param result [Array<String>] The accumulator for matching file paths
+      # @param current_depth [Integer] The current traversal depth
+      # @param max_depth [Integer] The maximum allowed traversal depth
+      def traverse_directory(path:, result:, current_depth:, max_depth:)
+        return if current_depth > max_depth
+
+        Dir.each_child(path) do |entry|
+          next if excluded?(name: entry)
+
+          full_path = File.join(path, entry)
+
+          next if File.symlink?(full_path) && !options.fetch(:follow_symlinks, false)
+
+          if File.directory?(full_path)
+            traverse_directory(
+              path: full_path,
+              result:,
+              current_depth: current_depth + 1,
+              max_depth:
+            )
+          elsif File.file?(full_path) && included_extension?(path: full_path)
+            result << full_path
+          end
+        end
+      rescue Errno::EACCES, Errno::ENOENT => e
+        Core::Console::Logger.verbose(message: "Skipping #{path}: #{e.message}")
+      end
+
+      # Check whether a file or directory name matches an exclude pattern
+      # @param name [String] The file or directory name to check
+      # @return [Boolean] true if the entry should be excluded
+      def excluded?(name:)
+        exclude_patterns.any? { |pattern| name == pattern }
+      end
+
+      # Check whether a file path has an extension that should be scanned
+      # @param path [String] The file path to check
+      # @return [Boolean] true if the file extension is in the inclusion list
+      def included_extension?(path:)
+        file_extensions.include?(File.extname(path))
+      end
+
+      # Returns the configured list of file extensions to scan
+      # @return [Array<String>] The file extensions
+      def file_extensions
+        options.fetch(:extensions, Globals.default_scan_extensions)
+      end
+
+      # Returns the configured list of directory and file names to exclude
+      # @return [Array<String>] The exclude patterns
+      def exclude_patterns
+        options.fetch(:excludes, Globals.default_scan_excludes)
+      end
+
+      # Mask a secret value so only the first four characters are visible
+      # @param secret [String] The secret string to mask
+      # @return [String] The masked string, safe for display in logs
+      def mask_secret(secret:)
+        return '***' if secret.length <= 6
+
+        "#{secret[0..3]}#{'*' * (secret.length - 4)}"
+      end
+
+      # Builds the default scanning options from globals
+      # @return [Hash] The default options hash
+      def default_options
+        {
+          extensions: Globals.default_scan_extensions,
+          excludes: Globals.default_scan_excludes,
+          max_depth: Globals.max_scan_depth,
+          follow_symlinks: false,
+        }
+      end
+    end
+  end
+end

data/lib/validation/utils/entropy.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Validation
+    module Entropy
+      module_function
+
+      # Calculate the Shannon entropy of a string
+      # @param string [String] The string to analyze
+      # @return [Float] The Shannon entropy value (higher means more random)
+      def calculate(string:)
+        return 0.0 if string.empty?
+
+        frequencies = Hash.new(0)
+        string.each_char { |char| frequencies[char] += 1 }
+
+        frequencies.each_value.sum do |count|
+          frequency = count.to_f / string.length
+          -frequency * Math.log2(frequency)
+        end
+      end
+    end
+  end
+end

data/lib/validation/utils/min_length.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require_relative '../globals/globals'
+
+module SecureKeys
+  module Validation
+    # Minimum length requirements by key type
+    MIN_LENGTHS = {
+      api_key: Globals.api_key_length,
+      token: Globals.token_length,
+      secret: Globals.secret_length,
+      password: Globals.password_length,
+      key: Globals.key_length,
+    }.freeze
+  end
+end