bootprint 0.2.0

data/lib/bootprint/formatters/sarif.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bootprint
+  module Formatters
+    class Sarif
+      LEVELS = { critical: "error", error: "error", warning: "warning", info: "note" }.freeze
+
+      def initialize(report) = @report = report
+
+      def render
+        rules = @report.findings.map(&:rule_id).uniq.map do |id|
+          finding = @report.findings.find { |candidate| candidate.rule_id == id }
+          {
+            "id" => id,
+            "name" => id.tr("-", "_"),
+            "shortDescription" => { "text" => finding.title },
+            "help" => { "text" => finding.remediation&.fetch("summary", "Review this environment difference.") }
+          }
+        end
+        results = @report.findings.map do |finding|
+          result = {
+            "ruleId" => finding.rule_id,
+            "level" => finding.suppressed ? "none" : LEVELS.fetch(finding.severity),
+            "message" => { "text" => [finding.summary, finding.impact, finding.remediation&.fetch("summary", nil)].compact.join(" ") },
+            "properties" => { "category" => finding.category.to_s, "evidence" => finding.evidence, "suppressed" => finding.suppressed }
+          }
+          location = physical_location(finding.source_location)
+          result["locations"] = [{ "physicalLocation" => location }] if location
+          result["suppressions"] = [{ "kind" => "external", "justification" => finding.suppression_reason }] if finding.suppressed
+          result
+        end
+        driver = { "name" => "Bootprint", "version" => VERSION, "rules" => rules }
+        run = { "tool" => { "driver" => driver }, "results" => results }
+        output = ::JSON.pretty_generate(
+          "version" => "2.1.0",
+          "$schema" => "https://json.schemastore.org/sarif-2.1.0.json",
+          "runs" => [run]
+        )
+        "#{output}\n"
+      end
+
+      private
+
+      def physical_location(location)
+        return unless location && File.file?(location["path"])
+
+        region = location["line"] ? { "startLine" => location["line"] } : nil
+        { "artifactLocation" => { "uri" => location["path"] }, "region" => region }.compact
+      end
+    end
+  end
+end

data/lib/bootprint/formatters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "formatters/human"
+require_relative "formatters/json"
+require_relative "formatters/sarif"
+require_relative "formatters/markdown"
+
+module Bootprint
+  module Formatters
+    module_function
+
+    def render(format, report, color: false)
+      case format.to_s
+      when "human" then Human.new(report, color:).render
+      when "json" then JSON.new(report).render
+      when "sarif" then Sarif.new(report).render
+      when "markdown" then Markdown.new(report).render
+      else raise ConfigurationError, "Unknown format #{format.inspect}; use human, json, sarif, or markdown"
+      end
+    end
+  end
+end

data/lib/bootprint/initializer_profiler.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Bootprint
+  module InitializerProfiler
+    NETWORK_METHODS = %i[connect connect_nonblock tcp start open].freeze
+
+    module_function
+
+    def install!
+      return unless Bootprint.configuration.profile_boot
+      return unless defined?(Rails::Initializable::Initializer)
+      return if Rails::Initializable::Initializer.ancestors.include?(Instrumentation)
+
+      ENV.singleton_class.prepend(EnvironmentProbe) unless ENV.singleton_class.ancestors.include?(EnvironmentProbe)
+      Rails::Initializable::Initializer.prepend(Instrumentation)
+    end
+
+    def record_missing_environment(name)
+      collector = Thread.current[:bootprint_missing_environment]
+      collector << name.to_s if collector
+    end
+
+    def config_fingerprint
+      return {} unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      config = Rails.application.config
+      %i[eager_load cache_classes time_zone cache_store session_store].to_h do |name|
+        value = config.public_send(name) if config.respond_to?(name)
+        [name.to_s, value.is_a?(Array) ? value.first.to_s : value.to_s]
+      rescue StandardError
+        [name.to_s, nil]
+      end
+    end
+
+    module EnvironmentProbe
+      def [](name)
+        present = key?(name)
+        value = super
+        Bootprint::InitializerProfiler.record_missing_environment(name) unless present
+        value
+      end
+
+      def fetch(name, *arguments, &)
+        Bootprint::InitializerProfiler.record_missing_environment(name) unless key?(name)
+        super
+      end
+    end
+
+    module Instrumentation
+      def run(*args)
+        start_order = Bootprint::RailsState.initializers&.length.to_i + 1
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        constants_before = Object.constants.to_set
+        config_before = Bootprint::InitializerProfiler.config_fingerprint
+        missing_environment = []
+        Thread.current[:bootprint_missing_environment] = missing_environment
+        network_operation = false
+        tracer = TracePoint.new(:call, :c_call) do |trace|
+          owner = trace.defined_class.to_s
+          network_operation = true if NETWORK_METHODS.include?(trace.method_id) && owner.match?(/Socket|Net::HTTP|OpenURI/)
+        end
+        tracer.enable
+        exception = nil
+        result = super
+        result
+      rescue Exception => error # rubocop:disable Lint/RescueException -- record boot failures, then re-raise
+        exception = { "class" => error.class.name, "message" => Sanitizer.text(error.message) }
+        raise
+      ensure
+        tracer&.disable
+        duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1_000
+        loaded = (Object.constants.to_set - constants_before).map(&:to_s).sort
+        config_after = Bootprint::InitializerProfiler.config_fingerprint
+        mutations = config_after.keys.reject { |key| config_before[key] == config_after[key] }
+        Bootprint::RailsState.record_initializer(
+          "name" => name.to_s,
+          "start_order" => start_order,
+          "completion_order" => Bootprint::RailsState.initializers&.length.to_i + 1,
+          "duration_ms" => duration.round(3),
+          "exception" => exception,
+          "loaded_constants" => loaded.take(100),
+          "missing_environment_variables" => missing_environment.uniq.sort,
+          "network_operation_heuristic" => network_operation,
+          "configuration_mutations" => mutations,
+          "configuration_mutation_heuristic" => !mutations.empty?
+        )
+        Thread.current[:bootprint_missing_environment] = nil
+      end
+    end
+  end
+end

data/lib/bootprint/plugins.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Bootprint
+  module Plugin
+    API_VERSION = "1"
+
+    module_function
+
+    def api_version(value = nil)
+      return API_VERSION unless value
+      raise PluginError, "Plugin requires API #{value}; Bootprint provides #{API_VERSION}" unless value.to_s == API_VERSION
+
+      API_VERSION
+    end
+  end
+
+  module Plugins
+    Definition = Struct.new(:name, :collector_class, :rules_module, :registration_error, keyword_init: true) do
+      def collector(value = nil)
+        self.collector_class = value if value
+        collector_class
+      end
+
+      def rules(value = nil)
+        self.rules_module = value if value
+        rules_module
+      end
+    end
+
+    class << self
+      def register(name, &)
+        definition = Definition.new(name: name.to_s)
+        definition.instance_eval(&)
+        install_rules(definition)
+        registry.reject! { |plugin| plugin.name == definition.name }
+        registry << definition
+        definition
+      rescue StandardError => error
+        definition ||= Definition.new(name: name.to_s)
+        definition.registration_error = Sanitizer.text("#{error.class}: #{error.message}")
+        registry << definition
+        definition
+      end
+
+      def capture(warnings:, strict: false)
+        registry.each_with_object({}) do |plugin, result|
+          if plugin.registration_error
+            handle_failure(plugin, plugin.registration_error, warnings, strict)
+            next
+          end
+          next unless plugin.collector_class
+
+          begin
+            value = plugin.collector_class.respond_to?(:capture) ? plugin.collector_class.capture : plugin.collector_class.new.capture
+            result[plugin.name] = Sanitizer.recursive(Schema.stringify(value))
+          rescue StandardError => error
+            handle_failure(plugin, "#{error.class}: #{error.message}", warnings, strict)
+          end
+        end
+      end
+
+      def all = registry.dup
+      def reset! = @registry = []
+
+      private
+
+      def registry = @registry ||= []
+
+      def install_rules(definition)
+        rules = definition.rules_module
+        return unless rules
+
+        if rules.respond_to?(:install)
+          rules.install
+        elsif rules.respond_to?(:register)
+          rules.register
+        else
+          raise PluginError, "#{definition.name} rules must respond to install or register"
+        end
+      end
+
+      def handle_failure(plugin, message, warnings, strict)
+        sanitized = Sanitizer.text(message)
+        raise PluginError, "Plugin #{plugin.name} failed: #{sanitized}" if strict
+
+        warnings << { "plugin" => plugin.name, "message" => sanitized, "severity" => "warning" }
+      end
+    end
+  end
+end

data/lib/bootprint/policy.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Bootprint
+  class Policy
+    MODES = %w[permissive strict].freeze
+    SEVERITIES = %w[info warning error critical].freeze
+    TOP_LEVEL_KEYS = %w[version minimum_severity fail_on ignore allow rules redaction mode expected_platforms plugins].freeze
+
+    attr_reader :path, :data
+
+    def self.load(path = nil)
+      return new(nil, {}) unless path
+
+      absolute = File.expand_path(path)
+      raise ConfigurationError, "#{absolute}: file not found" unless File.file?(absolute)
+
+      parsed = YAML.safe_load_file(absolute, permitted_classes: [], aliases: false) || {}
+      new(absolute, parsed)
+    rescue Psych::SyntaxError => error
+      raise ConfigurationError, "#{absolute}:#{error.line}:#{error.column}: #{error.problem}"
+    rescue Psych::Exception => error
+      raise ConfigurationError, "#{absolute}: #{error.message}"
+    end
+
+    def initialize(path = nil, data = {})
+      @path = path
+      @data = Schema.stringify(data)
+      validate!
+    end
+
+    def minimum_severity
+      (data["minimum_severity"] || (strict? ? "warning" : "info")).to_sym
+    end
+
+    def fail_on
+      Array(data["fail_on"] || (strict? ? %w[warning error critical] : %w[error critical])).map(&:to_s)
+    end
+
+    def expected_platforms
+      Array(data["expected_platforms"]).map(&:to_s)
+    end
+
+    def optional_environment_variables
+      allow = data["allow"]
+      return [] unless allow.is_a?(Hash)
+
+      Array(allow["environment_variables"]).map(&:to_s)
+    end
+
+    def optional_environment_variable?(name)
+      optional_environment_variables.include?(name.to_s)
+    end
+
+    def allowed_paths
+      allow = data["allow"]
+      if allow.is_a?(Array)
+        allow.map(&:to_s)
+      else
+        Array(allow.is_a?(Hash) ? allow["paths"] : nil).map(&:to_s)
+      end
+    end
+
+    def redaction_patterns
+      Array(data.dig("redaction", "patterns")).map(&:to_s)
+    end
+
+    def redaction_safe_list
+      Array(data.dig("redaction", "safe_list")).map(&:to_s)
+    end
+
+    def plugin_strict?
+      strict? || data.dig("plugins", "strict") == true
+    end
+
+    def strict? = data.fetch("mode", "permissive") == "strict"
+
+    def ignored?(rule_id)
+      Array(data["ignore"]).map(&:to_s).include?(rule_id.to_s)
+    end
+
+    def disabled?(rule_id)
+      data.dig("rules", rule_id.to_s, "enabled") == false
+    end
+
+    def severity_for(rule_id, default)
+      (data.dig("rules", rule_id.to_s, "severity") || default).to_sym
+    end
+
+    def suppression_reason(rule_id)
+      return "ignored by policy" if ignored?(rule_id)
+      return "disabled by policy" if disabled?(rule_id)
+
+      nil
+    end
+
+    def apply!
+      Bootprint.configuration.optional_environment_names |= optional_environment_variables
+      Bootprint.configuration.expected_platforms = expected_platforms
+      Bootprint.configuration.redaction_patterns |= redaction_patterns
+      Bootprint.configuration.redaction_safe_list |= redaction_safe_list
+      Bootprint.configuration.plugin_strict = plugin_strict?
+      self
+    end
+
+    def explain
+      lines = []
+      lines << "Policy: #{path || '(built-in defaults)'}"
+      lines << "Mode: #{strict? ? 'strict' : 'permissive'}"
+      lines << "Minimum reported severity: #{minimum_severity}"
+      lines << "Blocking severities: #{fail_on.join(', ')}"
+      lines << "Ignored rules: #{Array(data['ignore']).join(', ')}" unless Array(data["ignore"]).empty?
+      lines << "Optional environment variables: #{optional_environment_variables.join(', ')}" unless optional_environment_variables.empty?
+      lines << "Expected platforms: #{expected_platforms.join(', ')}" unless expected_platforms.empty?
+      lines << "Rule overrides: #{Array(data['rules']&.keys).join(', ')}" if data["rules"].is_a?(Hash)
+      "#{lines.join("\n")}\n"
+    end
+
+    private
+
+    def validate!
+      error("policy root must be a mapping") unless data.is_a?(Hash)
+      unknown = data.keys - TOP_LEVEL_KEYS
+      error("unknown keys: #{unknown.join(', ')}", unknown.first) unless unknown.empty?
+      error("version must equal 1", "version") unless data.fetch("version", 1) == 1
+      validate_severity(data["minimum_severity"], "minimum_severity") if data["minimum_severity"]
+      unless Array(data["fail_on"]).all? { |severity| SEVERITIES.include?(severity.to_s) }
+        error("fail_on contains an invalid severity", "fail_on")
+      end
+      mode = data.fetch("mode", "permissive")
+      error("mode must be strict or permissive", "mode") unless MODES.include?(mode)
+      error("ignore must be an array", "ignore") if data.key?("ignore") && !data["ignore"].is_a?(Array)
+      error("rules must be a mapping", "rules") if data.key?("rules") && !data["rules"].is_a?(Hash)
+      validate_rule_overrides
+      validate_allow
+      validate_redaction
+    end
+
+    def validate_rule_overrides
+      return unless data["rules"].is_a?(Hash)
+
+      data["rules"].each do |id, settings|
+        error("rule #{id} must be a mapping", id) unless settings.is_a?(Hash)
+        unknown = settings.keys - %w[enabled severity]
+        error("rule #{id} has unknown settings: #{unknown.join(', ')}", id) unless unknown.empty?
+        validate_severity(settings["severity"], id) if settings["severity"]
+        error("rule #{id} enabled must be true or false", id) if settings.key?("enabled") && ![true, false].include?(settings["enabled"])
+      end
+    end
+
+    def validate_allow
+      allow = data["allow"]
+      return if allow.nil? || allow.is_a?(Array)
+
+      error("allow must be a mapping or legacy array", "allow") unless allow.is_a?(Hash)
+      unknown = allow.keys - %w[environment_variables paths]
+      error("allow has unknown settings: #{unknown.join(', ')}", "allow") unless unknown.empty?
+      allow.each { |key, value| error("allow.#{key} must be an array", key) unless value.is_a?(Array) }
+    end
+
+    def validate_redaction
+      redaction = data["redaction"]
+      return unless redaction
+
+      error("redaction must be a mapping", "redaction") unless redaction.is_a?(Hash)
+      unknown = redaction.keys - %w[patterns safe_list]
+      error("redaction has unknown settings: #{unknown.join(', ')}", "redaction") unless unknown.empty?
+      redaction.each do |key, value|
+        error("redaction.#{key} must be an array", key) unless value.is_a?(Array) && value.all?(String)
+      end
+    end
+
+    def validate_severity(value, key)
+      error("#{key} must be one of #{SEVERITIES.join(', ')}", key) unless SEVERITIES.include?(value.to_s)
+    end
+
+    def error(message, key = nil)
+      location = path || ".bootprint.yml"
+      line = key && source_line(key)
+      raise ConfigurationError, "#{location}#{":#{line}" if line}: #{message}"
+    end
+
+    def source_line(key)
+      return unless path && File.file?(path)
+
+      pattern = /^\s*#{Regexp.escape(key.to_s)}\s*:/
+      File.readlines(path, encoding: "UTF-8").index { |line| line.match?(pattern) }&.+(1)
+    end
+  end
+end

data/lib/bootprint/rails_state.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Bootprint
+  module RailsState
+    class << self
+      attr_reader :initializers
+
+      def record_initializer(attributes)
+        (@initializers ||= []) << Schema.stringify(attributes)
+      end
+
+      def reset!
+        @initializers = []
+      end
+    end
+  end
+end

data/lib/bootprint/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "rails_state"
+require_relative "initializer_profiler"
+
+Bootprint::InitializerProfiler.install!
+
+module Bootprint
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/bootprint.rake", __dir__)
+    end
+
+    initializer "bootprint.observe_initializers", before: :load_config_initializers do
+      next unless ENV["BOOTPRINT_INSPECT"] == "1" || Bootprint.configuration.profile_boot
+      next if Bootprint.configuration.profile_boot
+
+      Bootprint::RailsState.reset!
+      ActiveSupport::Notifications.subscribe("load_config_initializer.railties") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        path = event.payload[:initializer]
+        name = path.respond_to?(:to_path) ? path.to_path : path.to_s
+        Bootprint::RailsState.record_initializer(
+          "name" => name,
+          "start_order" => Bootprint::RailsState.initializers.length + 1,
+          "completion_order" => Bootprint::RailsState.initializers.length + 1,
+          "duration_ms" => event.duration.round(3),
+          "exception" => event.payload[:exception] && { "class" => event.payload[:exception].first },
+          "loaded_constants" => [],
+          "network_operation_heuristic" => false
+        )
+      end
+    end
+  end
+end