secure-keys 1.1.7 → 1.2.0

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

data/lib/validation/utils/patterns.rb

@@ -0,0 +1,204 @@
+#!/usr/bin/env ruby
+
+# rubocop:disable Lint/Syntax, Metrics/ModuleLength
+
+module SecureKeys
+  module Validation
+    # Known secret patterns with descriptions
+    PATTERNS = {
+      # GitHub
+      github_token: {
+        pattern: /ghp_[a-zA-Z0-9]{36}/,
+        description: 'GitHub Personal Access Token',
+        severity: :high,
+        example: 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+      github_oauth: {
+        pattern: /gho_[a-zA-Z0-9]{36}/,
+        description: 'GitHub OAuth Access Token',
+        severity: :high,
+        example: 'gho_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+      github_app: {
+        pattern: /(ghu|ghs)_[a-zA-Z0-9]{36}/,
+        description: 'GitHub App Token',
+        severity: :high,
+        example: 'ghu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+      github_refresh: {
+        pattern: /ghr_[a-zA-Z0-9]{36}/,
+        description: 'GitHub Refresh Token',
+        severity: :high,
+        example: 'ghr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+
+      # AWS
+      aws_access_key: {
+        pattern: /AKIA[0-9A-Z]{16}/,
+        description: 'AWS Access Key ID',
+        severity: :critical,
+        example: 'AKIAIOSFODNN7EXAMPLE'
+      },
+      aws_secret_key: {
+        pattern: %r{(?i)aws(.{0,20})?['\"][0-9a-zA-Z/+]{40}['\"]},
+        description: 'AWS Secret Access Key',
+        severity: :critical,
+        example: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
+      },
+      aws_session_token: {
+        pattern: %r{(?i)aws(.{0,20})?session(.{0,20})?['\"][0-9a-zA-Z/+]{100,}['\"]},
+        description: 'AWS Session Token',
+        severity: :high,
+        example: 'FwoGZXIvYXdzEBaa...(very long token)'
+      },
+
+      # Google Cloud
+      gcp_api_key: {
+        pattern: /AIza[0-9A-Za-z\-_]{35}/,
+        description: 'Google Cloud API Key',
+        severity: :high,
+        example: 'AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe'
+      },
+      gcp_oauth: {
+        pattern: /ya29\.[0-9A-Za-z\-_]+/,
+        description: 'Google OAuth Access Token',
+        severity: :high,
+        example: 'ya29.a0AfH6SMBx...'
+      },
+
+      # Stripe
+      stripe_secret_key: {
+        pattern: /sk_(live|test)_[0-9a-zA-Z]{24,}/,
+        description: 'Stripe Secret Key',
+        severity: :critical,
+        example: 'sk_live_51H...'
+      },
+      stripe_publishable_key: {
+        pattern: /pk_(live|test)_[0-9a-zA-Z]{24,}/,
+        description: 'Stripe Publishable Key',
+        severity: :medium,
+        example: 'pk_live_51H...'
+      },
+      stripe_restricted_key: {
+        pattern: /rk_(live|test)_[0-9a-zA-Z]{24,}/,
+        description: 'Stripe Restricted Key',
+        severity: :high,
+        example: 'rk_live_51H...'
+      },
+
+      # Slack
+      slack_token: {
+        pattern: /xox[baprs]-[0-9a-zA-Z]{10,48}/,
+        description: 'Slack Token',
+        severity: :high,
+        example: 'xoxb-1234567890123-1234567890123-xxxxxxxxxxxxx'
+      },
+      slack_webhook: {
+        pattern: %r{https://hooks\.slack\.com/services/T[a-zA-Z0-9_]{8,}/B[a-zA-Z0-9_]{8,}/[a-zA-Z0-9_]{24}},
+        description: 'Slack Webhook URL',
+        severity: :medium,
+        example: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
+      },
+
+      # OAuth & JWT
+      jwt_token: {
+        pattern: %r{eyJ[A-Za-z0-9\-_=]+\.eyJ[A-Za-z0-9\-_=]+\.?[A-Za-z0-9\-_.+/=]*},
+        description: 'JWT Token',
+        severity: :medium,
+        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U'
+      },
+
+      # Generic patterns
+      private_key: {
+        pattern: /-----BEGIN (RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/,
+        description: 'Private Key',
+        severity: :critical,
+        example: '-----BEGIN PRIVATE KEY-----'
+      },
+      generic_api_key: {
+        pattern: /(?i)(api[_-]?key|apikey)[\s]*[:=][\s]*['\"]([a-zA-Z0-9_\-]{20,})['\"]/,
+        description: 'Generic API Key',
+        severity: :medium,
+        example: 'api_key: "abcdef1234567890abcdef1234567890"'
+      },
+      generic_secret: {
+        pattern: /(?i)(secret|password|passwd|pwd)[\s]*[:=][\s]*['\"]([^\s'\"]{8,})['\"]/,
+        description: 'Generic Secret/Password',
+        severity: :medium,
+        example: 'secret: "mysecretpassword123"'
+      },
+
+      # Firebase
+      firebase_key: {
+        pattern: /AIza[0-9A-Za-z\-_]{35}/,
+        description: 'Firebase API Key',
+        severity: :medium,
+        example: 'AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe'
+      },
+
+      # Twilio
+      twilio_api_key: {
+        pattern: /SK[a-z0-9]{32}/,
+        description: 'Twilio API Key',
+        severity: :high,
+        example: 'SKxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+      twilio_account_sid: {
+        pattern: /AC[a-z0-9]{32}/,
+        description: 'Twilio Account SID',
+        severity: :low,
+        example: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+
+      # SendGrid
+      sendgrid_api_key: {
+        pattern: /SG\.[a-zA-Z0-9_\-]{22}\.[a-zA-Z0-9_\-]{43}/,
+        description: 'SendGrid API Key',
+        severity: :high,
+        example: 'SG.xxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+
+      # Mailchimp
+      mailchimp_api_key: {
+        pattern: /[a-f0-9]{32}-us[0-9]{1,2}/,
+        description: 'Mailchimp API Key',
+        severity: :medium,
+        example: 'abcdef1234567890abcdef1234567890-us19'
+      },
+
+      # Square
+      square_access_token: {
+        pattern: /sq0atp-[0-9A-Za-z\-_]{22}/,
+        description: 'Square Access Token',
+        severity: :high,
+        example: 'sq0atp-xxxxxxxxxxxxxxxxxxxxxx'
+      },
+
+      # PayPal
+      paypal_braintree: {
+        pattern: /access_token\$production\$[a-z0-9]{16}\$[a-f0-9]{32}/,
+        description: 'PayPal Braintree Access Token',
+        severity: :critical,
+        example: 'access_token$production$xxxxxxxxxxxxxxxx$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+      },
+
+      # Heroku
+      heroku_api_key: {
+        pattern: /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/,
+        description: 'Heroku API Key (UUID format)',
+        severity: :high,
+        example: '12345678-1234-1234-1234-123456789012'
+      },
+
+      # Generic Base64 secrets (often used for keys)
+      base64_secret: {
+        pattern: %r{(?i)(secret|key|token|password)[\s]*[:=][\s]*['\"]([A-Za-z0-9+/]{40,}={0,2})['\"]},
+        description: 'Base64 Encoded Secret',
+        severity: :low,
+        example: 'secret: "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY3ODkw"'
+      }
+    }.freeze
+  end
+end
+
+# rubocop:enable Lint/Syntax, Metrics/ModuleLength

data/lib/validation/utils/weak_secrets.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Validation
+    # Common weak or test values that should never be used
+    WEAK_SECRETS = %w[
+      password password123 123456 secret test demo
+      admin root changeme temp default example
+      sample placeholder your-key-here your_api_key
+      xxxxxxxxxxxx 0000000000 1234567890
+    ].freeze
+  end
+end

data/lib/validation/validation_issue.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+module SecureKeys
+  module Validation
+    # Represents a single issue detected during secret validation
+    class ValidationIssue
+      attr_reader :severity, :type, :message, :recommendation
+
+      # Initialize a new validation issue
+      # @param severity [Symbol] The severity level (:critical, :error, :warning, :info)
+      # @param type [Symbol] The category of the issue (e.g. :empty_value, :weak_secret)
+      # @param message [String] A human-readable description of the issue
+      # @param recommendation [String, nil] An optional actionable recommendation for the developer
+      def initialize(severity:, type:, message:, recommendation:)
+        @severity = severity
+        @type = type
+        @message = message
+        @recommendation = recommendation
+      end
+
+      # Returns a string representation of the issue, including the recommendation if present
+      # @return [String] The formatted issue string
+      def to_s
+        text = "#{severity_icon} #{severity.upcase}: #{message}"
+        text += "\n\t\t💡 #{recommendation}" if recommendation
+        text
+      end
+
+      # Returns a hash representation of the issue
+      # @return [Hash] The hash representation
+      def to_h
+        {
+          severity:,
+          type:,
+          message:,
+          recommendation:,
+        }
+      end
+
+      private
+
+      # Returns the appropriate icon for the severity level
+      # @return [String] The severity icon
+      def severity_icon
+        case severity
+        when :critical then '🔴'
+        when :error then '❌'
+        when :warning then '⚠️'
+        when :info then 'ℹ️'
+        else '•'
+        end
+      end
+    end
+  end
+end