ruby_ability_graph 0.1.0

data/lib/ruby_ability_graph/rule_classifier.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyAbilityGraph
+  # Classifies a single CanCan::Rule's condition:
+  # "resolved" (unconditional or flat scalar hash, fully structured) or
+  # "unsupported" (block, association-reaching, or otherwise opaque).
+  # Shape only -- source/dynamic-generation handling lives in Enumerator.
+  class RuleClassifier
+    Classification = Struct.new(:confidence, :condition, :reason, :source, keyword_init: true)
+
+    def self.call(rule:, model:)
+      new(rule: rule, model: model).call
+    end
+
+    def initialize(rule:, model:)
+      @rule = rule
+      @model = model
+    end
+
+    def call
+      # only_block?, not @rule.block -- cancancan only made `block` a public
+      # reader from ~3.x on (it's a private ivar in, e.g., 1.17.0, still
+      # bundled by real apps -- found via dogfooding dradis-ce). only_block?
+      # (conditions_empty? && block-present) is public across both and, since
+      # both versions treat a Hash-conditions-plus-block combo as a raise-on-
+      # declaration error, it's equivalent to "has a block" for every rule
+      # that could actually exist.
+      return unsupported("block_condition") if @rule.only_block?
+
+      conditions = @rule.conditions
+      return resolved(nil) if blank?(conditions)
+      return unsupported("unrecognized_condition_value") unless conditions.is_a?(Hash)
+
+      classify_hash(conditions)
+    end
+
+    private
+
+    def blank?(conditions)
+      conditions.nil? || (conditions.respond_to?(:empty?) && conditions.empty?)
+    end
+
+    def classify_hash(conditions)
+      conditions.each do |key, value|
+        return unsupported("association_chained") if value.is_a?(Hash)
+        return unsupported("requires_association_traversal") if association_key?(key)
+        return unsupported("unrecognized_condition_value") unless scalar?(value)
+      end
+      resolved(conditions)
+    end
+
+    # Deliberately no special-casing by key name (e.g. tenant_id/team_id) --
+    # a flat scalar comparison is resolved regardless of what it's called.
+    def association_key?(key)
+      @model.respond_to?(:reflect_on_association) && !@model.reflect_on_association(key).nil?
+    end
+
+    def scalar?(value)
+      value.nil? || value == true || value == false ||
+        value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(Symbol)
+    end
+
+    def resolved(condition)
+      Classification.new(confidence: "resolved", condition: condition, reason: nil, source: nil)
+    end
+
+    def unsupported(reason)
+      Classification.new(confidence: "unsupported", condition: nil, reason: reason, source: nil)
+    end
+  end
+end

data/lib/ruby_ability_graph/scan_options.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RubyAbilityGraph
+  # Parses and validates `scan` subcommand argv into an options hash + app
+  # path. Split out from CLI so that class stays a thin command dispatcher
+  # as flags accumulate (see .rubocop.yml's CLI Metrics/ClassLength note).
+  class ScanOptions
+    def self.parse(argv)
+      new.parse(argv)
+    end
+
+    def parse(argv)
+      options = defaults
+      build_parser(options).parse!(argv)
+
+      app_path = argv.shift
+      abort(CLI::USAGE) unless app_path
+
+      validate!(options)
+      [options, app_path]
+    end
+
+    private
+
+    def defaults
+      {
+        ability_file: Harness::DEFAULT_ABILITY_FILE, ability_class: "Ability",
+        requires: [], rails_boot: false, format: "table"
+      }
+    end
+
+    def build_parser(options)
+      OptionParser.new do |opts|
+        add_roles_file_option!(opts, options)
+        add_ability_file_option!(opts, options)
+        add_ability_class_option!(opts, options)
+        add_ruby_bin_option!(opts, options)
+        add_format_option!(opts, options)
+        add_policy_file_option!(opts, options)
+        add_html_report_option!(opts, options)
+        add_loader_strategy_options!(opts, options)
+      end
+    end
+
+    def add_roles_file_option!(opts, options)
+      opts.on("--roles-file FILE", "YAML file mapping role name => user stand-in attributes") do |v|
+        options[:roles_file] = v
+      end
+    end
+
+    def add_ability_file_option!(opts, options)
+      opts.on("--ability-file FILE", "Path to the Ability class file, relative to APP_PATH") do |v|
+        options[:ability_file] = v
+      end
+    end
+
+    def add_ability_class_option!(opts, options)
+      opts.on("--ability-class NAME", "Constant name of the Ability class, e.g. Spree::Ability for a " \
+                                      "namespaced/engine-provided one (default: Ability)") do |v|
+        options[:ability_class] = v
+      end
+    end
+
+    def add_ruby_bin_option!(opts, options)
+      opts.on("--ruby-bin PATH", "Ruby executable for the target subprocess (default: " \
+                                 "\"ruby\" via PATH); target can use a different Ruby version. " \
+                                 "See README.") do |v|
+        options[:ruby_bin] = v
+      end
+    end
+
+    def add_format_option!(opts, options)
+      opts.on("--format FORMAT", %w[table json], "Output format: table (default) or json") do |v|
+        options[:format] = v
+      end
+    end
+
+    def add_policy_file_option!(opts, options)
+      opts.on("--policy-file FILE", "YAML file declaring role/action/model access expectations " \
+                                    "(see README); violations are flagged and exit non-zero") do |v|
+        options[:policy_file] = v
+      end
+    end
+
+    def add_html_report_option!(opts, options)
+      opts.on("--html-report FILE", "Write a self-contained, interactive HTML graph of the results " \
+                                    "(see README) to this path, relative to APP_PATH") do |v|
+        options[:html_report] = v
+      end
+    end
+
+    def add_loader_strategy_options!(opts, options)
+      add_require_option!(opts, options)
+      add_rails_boot_option!(opts, options)
+      add_rails_env_option!(opts, options)
+    end
+
+    def add_require_option!(opts, options)
+      opts.on("--require FILE", "Path, relative to APP_PATH, to preload before the " \
+                                "Ability file (repeatable), see #2. Not compatible " \
+                                "with --rails-boot.") do |v|
+        options[:requires] << v
+      end
+    end
+
+    def add_rails_boot_option!(opts, options)
+      opts.on("--rails-boot", "Run inside the target's own `bin/rails runner` for real " \
+                              "Zeitwerk autoloading, see #3. Not compatible with --require.") do
+        options[:rails_boot] = true
+      end
+    end
+
+    def add_rails_env_option!(opts, options)
+      opts.on("--rails-env ENV", "RAILS_ENV to boot under with --rails-boot (default: " \
+                                 "#{Harness::DEFAULT_RAILS_ENV.inspect}).") do |v|
+        options[:rails_env] = v
+      end
+    end
+
+    def validate!(options)
+      abort("--rails-env only applies with --rails-boot.") if options[:rails_env] && !options[:rails_boot]
+
+      return unless options[:rails_boot] && !options[:requires].empty?
+
+      abort("--require is not compatible with --rails-boot -- once Zeitwerk is live via bin/rails runner, " \
+            "referenced classes resolve on their own; a manual --require list is superfluous. " \
+            "Drop one or the other.")
+    end
+  end
+end

data/lib/ruby_ability_graph/scan_presenter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "table_formatter"
+require_relative "terminal_safe"
+
+module RubyAbilityGraph
+  # Turns a scan's results (plus an optional PolicyChecker::Report) into the
+  # CLI's printed output, in either format, and decides the process exit
+  # status -- kept separate from CLI so that class stays a thin dispatcher.
+  class ScanPresenter
+    SCHEMA_VERSION = 1
+
+    def initialize(format:, results:, policy_report:)
+      @format = format
+      @results = results
+      @policy_report = policy_report
+    end
+
+    def render
+      @format == "json" ? render_json : render_table
+    end
+
+    # nil policy_report means no --policy-file was given. An unmatched policy
+    # (typo'd model/action) counts as a problem too, same as a real violation.
+    def problems?
+      !@policy_report.nil? && (@policy_report.violations.any? || @policy_report.unmatched.any?)
+    end
+
+    private
+
+    def render_json
+      payload = { "schema_version" => SCHEMA_VERSION, "results" => @results }
+      if @policy_report
+        payload["policy_violations"] = @policy_report.violations
+        payload["policy_unmatched"] = @policy_report.unmatched
+      end
+      JSON.pretty_generate(payload)
+    end
+
+    def render_table
+      return TableFormatter.call(@results) if @policy_report.nil?
+
+      sections = [render_violations, render_unmatched].compact
+      "#{TableFormatter.call(@results)}\n\n#{sections.join("\n\n")}"
+    end
+
+    def render_violations
+      return "Policy check: no violations." if @policy_report.violations.empty?
+
+      lines = ["Policy violations (#{@policy_report.violations.size}):"] +
+              @policy_report.violations.map { |v| violation_line(v) }
+      lines.join("\n")
+    end
+
+    def render_unmatched
+      return nil if @policy_report.unmatched.empty?
+
+      lines = ["Policy entries with no matching scan result -- check for typos " \
+               "(#{@policy_report.unmatched.size}):"] + @policy_report.unmatched.map { |p| unmatched_line(p) }
+      lines.join("\n")
+    end
+
+    def violation_line(violation)
+      role, action, model = %w[role action model].map { |k| TerminalSafe.sanitize(violation[k]) }
+      allowed_roles = violation["allowed_roles"].map { |r| TerminalSafe.sanitize(r) }.join(", ")
+      "  #{role} can #{action} #{model} but is not in allowed_roles (#{allowed_roles}) [#{violation['confidence']}]"
+    end
+
+    def unmatched_line(policy)
+      "  #{TerminalSafe.sanitize(policy['model'])} / #{TerminalSafe.sanitize(policy['action'])}"
+    end
+  end
+end

data/lib/ruby_ability_graph/table_formatter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "terminal_safe"
+
+module RubyAbilityGraph
+  # Renders scan results (role x action x model rows, string-keyed as they
+  # come back from Harness) as a plain-text table -- the human-readable
+  # counterpart to `--format json`, plus a resolved/unsupported coverage
+  # summary line.
+  class TableFormatter
+    HEADERS = %w[ROLE ACTION MODEL ALLOWED CONFIDENCE CONDITION].freeze
+
+    def self.call(results)
+      new(results).call
+    end
+
+    def initialize(results)
+      @results = results
+    end
+
+    def call
+      rows = sorted_rows
+      widths = column_widths(rows)
+      table_lines = [format_row(HEADERS, widths), format_row(separator_cells(widths), widths)]
+      rows.each { |row| table_lines << format_row(row, widths) }
+      "#{table_lines.join("\n")}\n\n#{summary_line}"
+    end
+
+    private
+
+    def sorted_rows
+      @results.sort_by { |r| [r["role"], r["model"], r["action"]] }
+              .map { |r| [r["role"], r["action"], r["model"], r["allowed"].to_s, r["confidence"], condition_cell(r)] }
+    end
+
+    def condition_cell(result)
+      result["condition"].nil? ? "-" : TerminalSafe.sanitize(result["condition"])
+    end
+
+    def separator_cells(widths)
+      widths.map { |w| "-" * w }
+    end
+
+    def column_widths(rows)
+      HEADERS.each_index.map { |i| ([HEADERS[i].length] + rows.map { |r| r[i].to_s.length }).max }
+    end
+
+    def format_row(cells, widths)
+      cells.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip
+    end
+
+    def summary_line
+      resolved = @results.count { |r| r["confidence"] == "resolved" }
+      total = @results.size
+      "#{resolved}/#{total} resolved (#{coverage_pct(resolved, total)}%)"
+    end
+
+    def coverage_pct(resolved, total)
+      return 0 if total.zero?
+
+      ((resolved.to_f / total) * 100).round(1)
+    end
+  end
+end

data/lib/ruby_ability_graph/terminal_safe.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RubyAbilityGraph
+  # Strips control chars (e.g. ANSI escapes) before untrusted values hit the terminal.
+  module TerminalSafe
+    CONTROL_CHARS = /[\p{Cc}&&[^\n]]/
+
+    def self.sanitize(value)
+      value.to_s.gsub(CONTROL_CHARS, "")
+    end
+  end
+end

data/lib/ruby_ability_graph/version.rb

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

data/lib/ruby_ability_graph.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "ruby_ability_graph/version"
+require_relative "ruby_ability_graph/role_stand_in"
+require_relative "ruby_ability_graph/rule_classifier"
+require_relative "ruby_ability_graph/enumerator"
+require_relative "ruby_ability_graph/harness"
+require_relative "ruby_ability_graph/inspector"
+require_relative "ruby_ability_graph/terminal_safe"
+require_relative "ruby_ability_graph/table_formatter"
+require_relative "ruby_ability_graph/policy_checker"
+require_relative "ruby_ability_graph/html_report"
+require_relative "ruby_ability_graph/scan_presenter"
+require_relative "ruby_ability_graph/scan_options"
+require_relative "ruby_ability_graph/cli"
+
+module RubyAbilityGraph
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: ruby_ability_graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jessica Grider
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  ruby_ability_graph loads a Rails app's CanCanCan Ability class in isolation,
+  enumerates roles x actions x models, and reports resolved permissions --
+  distinguishing patterns it can fully resolve from ones it honestly flags as
+  unsupported rather than guessing.
+executables:
+- ruby-ability-graph
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/ruby-ability-graph
+- lib/ruby_ability_graph.rb
+- lib/ruby_ability_graph/cli.rb
+- lib/ruby_ability_graph/enumerator.rb
+- lib/ruby_ability_graph/harness.rb
+- lib/ruby_ability_graph/html_report.rb
+- lib/ruby_ability_graph/inspector.rb
+- lib/ruby_ability_graph/policy_checker.rb
+- lib/ruby_ability_graph/role_stand_in.rb
+- lib/ruby_ability_graph/rule_classifier.rb
+- lib/ruby_ability_graph/scan_options.rb
+- lib/ruby_ability_graph/scan_presenter.rb
+- lib/ruby_ability_graph/table_formatter.rb
+- lib/ruby_ability_graph/terminal_safe.rb
+- lib/ruby_ability_graph/version.rb
+homepage: https://github.com/m1gd0n-dev/ruby-ability-graph
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/m1gd0n-dev/ruby-ability-graph
+  source_code_uri: https://github.com/m1gd0n-dev/ruby-ability-graph
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Maps CanCanCan authorization rules into a visual, queryable 'who can access
+  what' model.
+test_files: []