bootprint 0.2.0

data/lib/bootprint/sanitizer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Bootprint
+  module Sanitizer
+    REDACTED = "[REDACTED]"
+    JWT_PATTERN = /\AeyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\z/
+    PRIVATE_KEY_PATTERN = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/
+    URL_CREDENTIAL_PATTERN = %r{\A([a-z][a-z0-9+.-]*://)([^/@\s]+)@}i
+    HIGH_ENTROPY_PATTERN = %r{\A[A-Za-z0-9+/_=-]{32,}\z}
+
+    module_function
+
+    def text(value)
+      sanitized = value.to_s.dup
+      replacements.each do |path, marker|
+        path_variants(path).each do |variant|
+          sanitized.gsub!(variant, marker)
+        end
+      end
+      sanitized.gsub(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/, "?")
+    end
+
+    def path(value)
+      text(value)
+    end
+
+    def recursive(value, patterns: Bootprint.configuration.redaction_patterns, privacy: Bootprint.configuration.privacy)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), result|
+          name = key.to_s
+          result[name] = if secret_name?(name, patterns) && !boolean?(nested)
+                           redaction_metadata(nested)
+                         elsif safe_digest_name?(name) && !nested.is_a?(Hash) && !nested.is_a?(Array)
+                           nested.to_s
+                         else
+                           recursive(nested, patterns:, privacy:)
+                         end
+        end
+      when Array
+        value.map { |nested| recursive(nested, patterns:, privacy:) }
+      when String
+        sanitize_value(value, privacy:)
+      else
+        value
+      end
+    end
+
+    def secret_name?(name, patterns = Bootprint.configuration.redaction_patterns)
+      return false if Bootprint.configuration.redaction_safe_list.any? { |entry| File.fnmatch?(entry, name, File::FNM_CASEFOLD) }
+
+      patterns.any? { |pattern| name.upcase.include?(pattern.to_s.upcase) }
+    end
+
+    def safe_digest_name?(name)
+      name.match?(/(?:checksum|sha256|digest)\z/i)
+    end
+
+    def boolean?(value)
+      [true, false].include?(value)
+    end
+
+    def sensitive_value?(value)
+      string = value.to_s
+      PRIVATE_KEY_PATTERN.match?(string) || JWT_PATTERN.match?(string) ||
+        URL_CREDENTIAL_PATTERN.match?(string) || high_entropy?(string)
+    end
+
+    def sanitize_value(value, privacy: :standard)
+      result = text(value)
+      result = result.gsub(URL_CREDENTIAL_PATTERN, "\\1#{REDACTED}@")
+      result = REDACTED if PRIVATE_KEY_PATTERN.match?(result) || JWT_PATTERN.match?(result) || high_entropy?(result)
+      result = "<HOST>" if privacy.to_sym == :strict && hostname_like?(result)
+      result
+    end
+
+    def high_entropy?(value)
+      return false unless HIGH_ENTROPY_PATTERN.match?(value)
+
+      value.chars.uniq.length >= 16
+    end
+
+    def hostname_like?(value)
+      value.match?(/\A(?=.{1,253}\z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}\z/i)
+    end
+
+    def redaction_metadata(value)
+      { "present" => !value.nil?, "redacted" => true }
+    end
+
+    def replacements
+      app_root = File.expand_path(Dir.pwd)
+      home = begin
+        File.expand_path(Dir.home)
+      rescue ArgumentError
+        nil
+      end
+      [[app_root, "<APP_ROOT>"], [home, "<HOME>"]].reject { |path, _marker| path.nil? || path.empty? }
+    end
+
+    def path_variants(path)
+      [path, path.tr("\\", "/"), path.tr("/", "\\")].uniq.sort_by { |variant| -variant.length }
+    end
+  end
+end

data/lib/bootprint/schema.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Bootprint
+  module Schema
+    CURRENT_VERSION = 2
+    ENVIRONMENT_SECTIONS = %w[runtime dependencies native_libraries configuration filesystem operating_system].freeze
+
+    module_function
+
+    def migrate(data)
+      raise InvalidSnapshotError, "Snapshot root must be a JSON object" unless data.is_a?(Hash)
+
+      version = data.is_a?(Hash) ? data["schema_version"] || data[:schema_version] : nil
+      case version
+      when CURRENT_VERSION then stringify(data)
+      when 1 then migrate_v1(stringify(data))
+      when nil then raise InvalidSnapshotError, "Snapshot does not declare schema_version"
+      else
+        if version.is_a?(Integer) && version > CURRENT_VERSION
+          raise InvalidSnapshotError, "Snapshot schema #{version} is newer than supported schema #{CURRENT_VERSION}; upgrade Bootprint"
+        end
+
+        raise InvalidSnapshotError, "Unsupported snapshot schema #{version.inspect}"
+      end
+    end
+
+    def validate!(data)
+      raise InvalidSnapshotError, "Snapshot root must be a JSON object" unless data.is_a?(Hash)
+      raise InvalidSnapshotError, "schema_version must equal #{CURRENT_VERSION}" unless data["schema_version"] == CURRENT_VERSION
+      raise InvalidSnapshotError, "generated_at must be an ISO-8601 string" unless data["generated_at"].is_a?(String)
+      raise InvalidSnapshotError, "bootprint_version must be a string" unless data["bootprint_version"].is_a?(String)
+
+      environment = data["environment"]
+      raise InvalidSnapshotError, "environment must be an object" unless environment.is_a?(Hash)
+
+      missing = ENVIRONMENT_SECTIONS - environment.keys
+      raise InvalidSnapshotError, "environment is missing sections: #{missing.join(', ')}" unless missing.empty?
+
+      invalid = ENVIRONMENT_SECTIONS.reject { |key| environment[key].is_a?(Hash) }
+      raise InvalidSnapshotError, "environment sections must be objects: #{invalid.join(', ')}" unless invalid.empty?
+
+      variables = environment.dig("configuration", "environment_variables")
+      unless variables.is_a?(Hash) && variables.values.all? { |value| [true, false].include?(value) }
+        raise InvalidSnapshotError, "configuration.environment_variables must map names to booleans"
+      end
+
+      true
+    end
+
+    def migrate_v1(old)
+      known = %w[schema_version metadata runtime toolchain gems libraries environment operating_system rails]
+      unknown = old.except(*known)
+      rails = old["rails"] || {}
+      {
+        "schema_version" => CURRENT_VERSION,
+        "generated_at" => old.dig("metadata", "captured_at") || Time.now.utc.iso8601,
+        "bootprint_version" => VERSION,
+        "environment" => {
+          "name" => old.dig("metadata", "label"),
+          "runtime" => old["runtime"] || {},
+          "dependencies" => {
+            "toolchain" => old["toolchain"] || {},
+            "gems" => old.dig("gems", "resolved") || {},
+            "lockfile" => { "sha256" => old.dig("gems", "lockfile_sha256"), "platforms" => [] }.compact
+          },
+          "native_libraries" => old["libraries"] || {},
+          "configuration" => {
+            "environment_variables" => old.dig("environment", "variables") || {},
+            "required_environment_variables" => [],
+            "optional_environment_variables" => [],
+            "rails" => rails
+          },
+          "filesystem" => default_filesystem,
+          "operating_system" => old["operating_system"] || {}
+        }.compact,
+        "capture" => { "migrated_from" => 1 },
+        "extensions" => unknown
+      }
+    end
+
+    def default_filesystem
+      {
+        "path_separator" => File::ALT_SEPARATOR || File::SEPARATOR,
+        "temporary_directory" => { "present" => true, "writable" => true },
+        "required_directories" => {}
+      }
+    end
+
+    def stringify(value)
+      case value
+      when Hash then value.to_h { |key, nested| [key.to_s, stringify(nested)] }
+      when Array then value.map { |nested| stringify(nested) }
+      else value
+      end
+    end
+
+    def deterministic(value)
+      case value
+      when Hash then value.keys.sort.to_h { |key| [key, deterministic(value[key])] }
+      when Array
+        normalized = value.map { |nested| deterministic(nested) }
+        normalized.all? { |item| scalar?(item) } ? normalized.sort_by(&:to_s) : normalized
+      else value
+      end
+    end
+
+    def scalar?(value)
+      value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+    end
+  end
+end

data/lib/bootprint/security/auditor.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Bootprint
+  module Security
+    class Auditor
+      Issue = Struct.new(:path, :kind, :message, keyword_init: true) do
+        def to_h = { "path" => path, "kind" => kind, "message" => message }
+      end
+
+      def initialize(snapshot)
+        @snapshot = snapshot
+      end
+
+      def audit
+        issues = []
+        walk(@snapshot.data, [], issues)
+        issues
+      end
+
+      private
+
+      def walk(value, path, issues)
+        case value
+        when Hash
+          value.each do |key, nested|
+            current = path + [key]
+            if Sanitizer.secret_name?(key) && !presence_boolean?(nested) && !redacted_metadata?(nested)
+              issues << Issue.new(path: current.join("."), kind: "secret-name",
+                                  message: "Secret-like field is not represented by redaction metadata.")
+            end
+            walk(nested, current, issues)
+          end
+        when Array
+          value.each_with_index { |nested, index| walk(nested, path + [index], issues) }
+        when String
+          return if Sanitizer.safe_digest_name?(path.last.to_s)
+
+          if Sanitizer.sensitive_value?(value)
+            issues << Issue.new(path: path.join("."), kind: "sensitive-value",
+                                message: "Value resembles a credential, token, private key, or credential-bearing URL.")
+          elsif absolute_home_path?(value)
+            issues << Issue.new(path: path.join("."), kind: "home-path", message: "Absolute user-home path was not normalized.")
+          end
+        end
+      end
+
+      def redacted_metadata?(value)
+        value.is_a?(Hash) && value["redacted"] == true && value.keys.all? { |key| %w[present source redacted].include?(key) }
+      end
+
+      def presence_boolean?(value)
+        [true, false].include?(value)
+      end
+
+      def absolute_home_path?(value)
+        home = File.expand_path(Dir.home)
+        value.include?(home) || value.include?(home.tr("\\", "/"))
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/bootprint/snapshot.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+require_relative "collectors/runtime"
+require_relative "collectors/toolchain"
+require_relative "collectors/gems"
+require_relative "collectors/libraries"
+require_relative "collectors/environment"
+require_relative "collectors/filesystem"
+require_relative "collectors/operating_system"
+require_relative "collectors/rails"
+
+module Bootprint
+  class Snapshot
+    SCHEMA_VERSION = Schema::CURRENT_VERSION
+    NON_SEMANTIC_PATHS = %w[generated_at capture.duration_ms capture.plugins].freeze
+
+    attr_reader :data
+
+    def self.capture(label: nil, privacy: Bootprint.configuration.privacy)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      Bootprint.configuration.privacy = privacy.to_sym
+      warnings = []
+      environment = {
+        "name" => label,
+        "runtime" => safely_collect(Collectors::Runtime, warnings),
+        "dependencies" => dependency_data(warnings),
+        "native_libraries" => safely_collect(Collectors::Libraries, warnings),
+        "configuration" => configuration_data(warnings),
+        "filesystem" => safely_collect(Collectors::Filesystem, warnings),
+        "operating_system" => safely_collect(Collectors::OperatingSystem, warnings)
+      }.compact
+
+      plugin_data = if defined?(Bootprint::Plugins)
+                      Bootprint::Plugins.capture(warnings:, strict: Bootprint.configuration.plugin_strict)
+                    else
+                      {}
+                    end
+      environment["plugins"] = plugin_data unless plugin_data.empty?
+      duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1_000
+      new({
+            "schema_version" => SCHEMA_VERSION,
+            "generated_at" => Time.now.utc.iso8601,
+            "bootprint_version" => VERSION,
+            "environment" => Sanitizer.recursive(environment, privacy:),
+            "capture" => {
+              "duration_ms" => duration.round(3),
+              "privacy" => privacy.to_s,
+              "warnings" => warnings
+            }
+          })
+    end
+
+    def self.load(path)
+      parsed = JSON.parse(File.read(path, encoding: "UTF-8"))
+      new(parsed)
+    rescue JSON::ParserError => error
+      raise InvalidSnapshotError, "#{File.expand_path(path)} is not valid JSON: #{error.message}"
+    rescue Errno::ENOENT
+      raise InvalidSnapshotError, "Snapshot not found: #{File.expand_path(path)}"
+    end
+
+    def self.safely_collect(collector, warnings)
+      collector.capture
+    rescue StandardError => error
+      warnings << {
+        "collector" => collector.key,
+        "message" => Sanitizer.text("#{error.class}: #{error.message}"),
+        "severity" => "warning"
+      }
+      { "capture_error" => Sanitizer.text("#{error.class}: #{error.message}") }
+    end
+
+    def self.dependency_data(warnings)
+      gems = safely_collect(Collectors::Gems, warnings)
+      {
+        "toolchain" => safely_collect(Collectors::Toolchain, warnings),
+        "gems" => gems["resolved"] || {},
+        "lockfile" => gems.except("resolved")
+      }
+    end
+
+    def self.configuration_data(warnings)
+      environment = safely_collect(Collectors::Environment, warnings)
+      rails = safely_collect(Collectors::Rails, warnings)
+      {
+        "environment_variables" => environment["variables"] || {},
+        "required_environment_variables" => Bootprint.configuration.required_environment_names.sort,
+        "optional_environment_variables" => Bootprint.configuration.optional_environment_names.sort,
+        "rails" => rails || {}
+      }
+    end
+
+    def initialize(data)
+      migrated = Schema.migrate(Schema.stringify(data))
+      Schema.validate!(migrated)
+      @data = Schema.deterministic(migrated)
+    end
+
+    def write(path)
+      directory = File.dirname(File.expand_path(path))
+      FileUtils.mkdir_p(directory)
+      File.write(path, "#{JSON.pretty_generate(data)}\n")
+      path
+    end
+
+    def [](key) = data[key.to_s]
+    def environment = data["environment"]
+    def name = environment["name"] || "unnamed"
+
+    def semantic_data
+      Marshal.load(Marshal.dump(data)).tap do |copy|
+        copy.delete("generated_at")
+        copy.delete("bootprint_version")
+        copy["capture"]&.delete("duration_ms")
+        copy["capture"]&.delete("warnings")
+      end
+    end
+  end
+end

data/lib/bootprint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bootprint
+  VERSION = "0.2.0"
+end

data/lib/bootprint.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "bootprint/version"
+require_relative "bootprint/errors"
+require_relative "bootprint/configuration"
+require_relative "bootprint/sanitizer"
+require_relative "bootprint/schema"
+require_relative "bootprint/plugins"
+require_relative "bootprint/snapshot"
+require_relative "bootprint/diff"
+require_relative "bootprint/doctor"
+require_relative "bootprint/policy"
+
+module Bootprint
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def rule(name, severity: nil, &block)
+      Rules.define(name, severity: severity, &block)
+    end
+
+    def capture(label: nil, **options)
+      Snapshot.capture(label:, **options)
+    end
+  end
+end
+
+require_relative "bootprint/rules"
+require_relative "bootprint/diagnosis"
+require_relative "bootprint/analysis"
+
+require_relative "bootprint/railtie" if defined?(Rails::Railtie)

data/lib/tasks/bootprint.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+namespace :bootprint do
+  desc "Capture a sanitized Rails runtime fingerprint"
+  task capture: :environment do
+    require "bootprint"
+    path = ENV.fetch("BOOTPRINT_OUTPUT", "bootprint.lock")
+    Bootprint.capture(label: Rails.env.to_s).write(path)
+    puts "Captured Bootprint snapshot to #{path}"
+  end
+
+  desc "Run Bootprint Rails runtime diagnostics"
+  task doctor: :environment do
+    require "bootprint/cli"
+    exit_code = Bootprint::CLI.start(["doctor"])
+    abort "Bootprint doctor found blocking issues" unless exit_code.zero?
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: bootprint
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Magnexis
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Bootprint captures sanitized Ruby and Rails runtime fingerprints, diagnoses
+  dangerous environment drift, and provides policy-aware remediation for CI, Docker,
+  staging, and production.
+email:
+- hello@magnexis.com
+executables:
+- bootprint
+extensions: []
+extra_rdoc_files: []
+files:
+- ".bootprint.yml.example"
+- ARCHITECTURE.md
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- RELEASE.md
+- ROADMAP.md
+- SECURITY.md
+- assets/branding/README.md
+- assets/branding/bootprint-logo-128.png
+- assets/branding/bootprint-logo-512.png
+- assets/branding/bootprint-logo-64.png
+- assets/branding/bootprint-logo.png
+- docs/capturing.md
+- docs/ci.md
+- docs/comparing.md
+- docs/custom-rules.md
+- docs/docker.md
+- docs/findings.md
+- docs/installation.md
+- docs/maintainer-setup.md
+- docs/plugins.md
+- docs/policy.md
+- docs/privacy.md
+- docs/quick-start.md
+- docs/rails.md
+- docs/snapshot-schema.md
+- docs/troubleshooting.md
+- exe/bootprint
+- lib/bootprint.rb
+- lib/bootprint/analysis.rb
+- lib/bootprint/cli.rb
+- lib/bootprint/collectors/environment.rb
+- lib/bootprint/collectors/filesystem.rb
+- lib/bootprint/collectors/gems.rb
+- lib/bootprint/collectors/libraries.rb
+- lib/bootprint/collectors/operating_system.rb
+- lib/bootprint/collectors/rails.rb
+- lib/bootprint/collectors/runtime.rb
+- lib/bootprint/collectors/toolchain.rb
+- lib/bootprint/configuration.rb
+- lib/bootprint/diagnosis.rb
+- lib/bootprint/diff.rb
+- lib/bootprint/docker.rb
+- lib/bootprint/doctor.rb
+- lib/bootprint/errors.rb
+- lib/bootprint/formatters.rb
+- lib/bootprint/formatters/human.rb
+- lib/bootprint/formatters/json.rb
+- lib/bootprint/formatters/markdown.rb
+- lib/bootprint/formatters/sarif.rb
+- lib/bootprint/initializer_profiler.rb
+- lib/bootprint/plugins.rb
+- lib/bootprint/policy.rb
+- lib/bootprint/rails_state.rb
+- lib/bootprint/railtie.rb
+- lib/bootprint/rules.rb
+- lib/bootprint/rules/builtin.rb
+- lib/bootprint/rules/finding.rb
+- lib/bootprint/rules/registry.rb
+- lib/bootprint/rules/rule.rb
+- lib/bootprint/sanitizer.rb
+- lib/bootprint/schema.rb
+- lib/bootprint/security/auditor.rb
+- lib/bootprint/snapshot.rb
+- lib/bootprint/version.rb
+- lib/tasks/bootprint.rake
+homepage: https://github.com/theworker02/bootprint
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/theworker02/bootprint/tree/main
+  homepage_uri: https://github.com/theworker02/bootprint
+  documentation_uri: https://github.com/theworker02/bootprint/tree/main/docs
+  changelog_uri: https://github.com/theworker02/bootprint/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/theworker02/bootprint/issues
+  funding_uri: https://github.com/sponsors/theworker02
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Diagnose runtime-environment drift in Ruby applications
+test_files: []