Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(rube): M3 gadget scanner - reflection-based sink discovery with reachability filter
CarterPerez-devb57e20d8fa9d
diff --git a/PROJECTS/beginner/deserialization-gadget-lab/justfile b/PROJECTS/beginner/deserialization-gadget-lab/justfileindex cfdd464c..38e0a41e 100644--- a/PROJECTS/beginner/deserialization-gadget-lab/justfile+++ b/PROJECTS/beginner/deserialization-gadget-lab/justfile@@ -13,6 +13,10 @@ default:test:{{run_ro}} ruby -Ilib -Itest test/marshal/parser_test.rb+ {{run_ro}} ruby -Ilib -Itest test/scanner_test.rb++scan namespace="":+ {{run_ro}} ruby -Ilib -e 'require "rube"; ns = "{{namespace}}"; r = Rube::Scanner.new(namespace: ns.empty? ? nil : ns).scan; puts "modules=#{r.scanned_modules} candidates=#{r.candidates.length} gated=#{r.gated.length} reachable=#{r.reachable.length}"; puts; r.reachable.each { |c| puts format(" %-10s %-46s %s", c.gate, c.to_s, c.source_location) }'control:{{run_ro}} ruby -Ilib -Itest test/control_check.rbdiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rbindex 337b48c6..2c889a9a 100644--- a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rb+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube.rb@@ -6,6 +6,7 @@ require_relative "rube/marshal/constants"require_relative "rube/marshal/errors"require_relative "rube/marshal/node"require_relative "rube/marshal/parser"+require_relative "rube/scanner"module Rubeenddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/scanner.rb b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/scanner.rbnew file mode 100644index 00000000..616e20cc--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/lib/rube/scanner.rb@@ -0,0 +1,217 @@+# ©AngelaMos | 2026+# scanner.rb++module Rube+ class Scanner+ GATED_METHODS = %w[marshal_load _load_data].freeze+ GATED_SINGLETON_METHODS = %w[_load].freeze+ UNGATED_METHODS = %w[hash eql? == <=> []= to_s method_missing respond_to_missing? coerce].freeze++ GATE_GATED = :gated+ GATE_UNGATED = :ungated++ PRISM_AVAILABLE = begin+ require "prism"+ true+ rescue LoadError+ false+ end++ LOCATION_SEPARATOR = ":"+ UNKNOWN_LOCATION = nil++ class Candidate+ attr_reader :class_name, :method_name, :gate, :source_location, :arity++ def initialize(class_name:, method_name:, gate:, source_location:, arity:, singleton:, touches_state:)+ @class_name = class_name+ @method_name = method_name+ @gate = gate+ @source_location = source_location+ @arity = arity+ @singleton = singleton+ @touches_state = touches_state+ end++ def singleton?+ @singleton+ end++ def gated?+ gate == GATE_GATED+ end++ def zero_arity?+ arity.zero?+ end++ def touches_state?+ @touches_state+ end++ def reachable?+ return true if gated?++ zero_arity? && touches_state?+ end++ def to_s+ "#{class_name}#{singleton? ? '.' : '#'}#{method_name}"+ end+ end++ class Report+ attr_reader :candidates, :scanned_modules++ def initialize(candidates, scanned_modules)+ @candidates = candidates+ @scanned_modules = scanned_modules+ end++ def gated+ candidates.select(&:gated?)+ end++ def ungated+ candidates.reject(&:gated?)+ end++ def reachable+ candidates.select(&:reachable?)+ end+ end++ def initialize(namespace: nil)+ @namespace = namespace+ @candidates = []+ @definition_cache = {}+ @scanned_modules = 0+ end++ def scan+ each_named_module do |mod, name|+ @scanned_modules += 1+ collect_instance_methods(mod, name)+ collect_singleton_methods(mod, name)+ end++ Report.new(@candidates.sort_by(&:to_s), @scanned_modules)+ end++ private++ attr_reader :namespace++ def each_named_module+ ObjectSpace.each_object(Module) do |mod|+ name = safe_name(mod)+ next unless name+ next unless in_namespace?(name)++ yield mod, name+ end+ end++ def safe_name(mod)+ name = mod.name+ name if name.is_a?(String) && !name.empty?+ rescue StandardError+ nil+ end++ def in_namespace?(name)+ namespace.nil? || name == namespace || name.start_with?("#{namespace}::")+ end++ def collect_instance_methods(mod, name)+ own = own_instance_methods(mod)++ (own & GATED_METHODS).each do |method_name|+ record(mod, name, method_name, GATE_GATED, singleton: false)+ end++ (own & UNGATED_METHODS).each do |method_name|+ record(mod, name, method_name, GATE_UNGATED, singleton: false)+ end+ end++ def collect_singleton_methods(mod, name)+ own = mod.singleton_methods(false).map(&:to_s)++ (own & GATED_SINGLETON_METHODS).each do |method_name|+ record(mod, name, method_name, GATE_GATED, singleton: true)+ end+ end++ def own_instance_methods(mod)+ (mod.instance_methods(false) + mod.private_instance_methods(false)).map(&:to_s)+ rescue StandardError+ []+ end++ def record(mod, name, method_name, gate, singleton:)+ handle = singleton ? mod.singleton_method(method_name) : mod.instance_method(method_name)++ @candidates << Candidate.new(+ class_name: name,+ method_name: method_name,+ gate: gate,+ source_location: format_location(handle.source_location),+ arity: handle.arity,+ singleton: singleton,+ touches_state: touches_state?(handle)+ )+ rescue StandardError, ScriptError+ nil+ end++ def format_location(location)+ return UNKNOWN_LOCATION unless location++ location.join(LOCATION_SEPARATOR)+ end++ def touches_state?(handle)+ return false unless PRISM_AVAILABLE++ path, line = handle.source_location+ return false unless path && line++ node = definition_at(path, line)+ return false unless node++ node.compact_child_nodes.any? { |child| state_reference?(child) }+ rescue StandardError, ScriptError+ false+ end++ def definition_at(path, line)+ definitions_for(path)[line]+ end++ def definitions_for(path)+ @definition_cache[path] ||= begin+ found = {}+ collect_definitions(Prism.parse_file(path).value, found)+ found+ rescue StandardError, ScriptError+ {}+ end+ end++ def collect_definitions(node, found)+ return unless node.is_a?(Prism::Node)++ found[node.location.start_line] = node if node.is_a?(Prism::DefNode)+ node.compact_child_nodes.each { |child| collect_definitions(child, found) }+ end++ def state_reference?(node)+ return false unless node.is_a?(Prism::Node)+ return true if node.is_a?(Prism::InstanceVariableReadNode)+ return true if node.is_a?(Prism::CallNode) && node.receiver.nil?++ node.compact_child_nodes.any? { |child| state_reference?(child) }+ end+ end+enddiff --git a/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rb b/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rbindex 409e3f41..2eddbd71 100644--- a/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rb+++ b/PROJECTS/beginner/deserialization-gadget-lab/test/control_check.rb@@ -76,3 +76,32 @@ result = Rube::Marshal::Parser.new(payload).parseputs " classes: #{result.class_names.inspect}"puts " sinks: #{result.sinks.map { |s| "#{s.class_name}##{s.sink_method}" }.inspect}"puts " gated: #{result.gated_sinks.map(&:class_name).inspect}"++puts+puts "=== control 6: M1 stream parsing and M3 reflection must agree ==="+puts " Two independent routes to the same fact. The parser reads bytes off a"+puts " payload; the scanner walks the live class graph. Neither consults the"+puts " other. If they disagree, one of them is wrong."+from_stream = result.gated_sinks.map { |s| "#{s.class_name}##{s.sink_method}" }.uniq.sort+scanned = Rube::Scanner.new(namespace: "Gem").scan.gated.map(&:to_s)+from_reflection = from_stream.select { |entry| scanned.include?(entry) }.sort+puts " parser (M1): #{from_stream.inspect}"+puts " scanner (M3): #{scanned.inspect}"+if from_stream == from_reflection && !from_stream.empty?+ puts " AGREE - every sink the parser found in the payload is a sink the scanner"+ puts " independently located in the class graph"+else+ puts " DISAGREE - parser found #{(from_stream - from_reflection).inspect} that reflection did not"+end++puts+puts "=== control 7: scanner precision, it must not report everything ==="+full = Rube::Scanner.new.scan+ratio = (full.candidates.length.to_f / full.scanned_modules * 100).round(1)+puts " #{full.scanned_modules} modules scanned -> #{full.candidates.length} candidates (#{ratio}% hit rate)"+puts " gated: #{full.gated.length}"+puts(ratio < 100 ? " PASS - scanner discriminates" : " FAIL - scanner reports every module, it is not filtering")+puts+puts " NOTE: ObjectSpace only sees loaded code. #{full.scanned_modules} modules is a bare"+puts " Ruby with RubyGems. A booted Rails app eager-loaded is several times that."+puts " Coverage is bounded by what has been required, and that is a real limit."diff --git a/PROJECTS/beginner/deserialization-gadget-lab/test/scanner_test.rb b/PROJECTS/beginner/deserialization-gadget-lab/test/scanner_test.rbnew file mode 100644index 00000000..701250f8--- /dev/null+++ b/PROJECTS/beginner/deserialization-gadget-lab/test/scanner_test.rb@@ -0,0 +1,198 @@+# ©AngelaMos | 2026+# scanner_test.rb++require_relative "test_helper"++module Rube+ class ScannerTest < Minitest::Test+ def scan(**options)+ Scanner.new(**options).scan+ end++ def local_scan+ scan(namespace: "Rube::ScannerTest")+ end++ def candidates_for(class_name)+ local_scan.candidates.select { |c| c.class_name == class_name }+ end++ def test_finds_gated_sink_defined_on_a_class+ found = candidates_for("Rube::ScannerTest::GatedFixture")+ assert_equal ["marshal_load"], found.map(&:method_name)+ assert_equal :gated, found.first.gate+ end++ def test_finds_singleton_load_as_gated_sink+ found = candidates_for("Rube::ScannerTest::UserDefFixture")+ assert_includes found.map(&:method_name), "_load"+ end++ def test_finds_ungated_dispatch_method+ found = candidates_for("Rube::ScannerTest::UngatedFixture")+ assert_equal ["hash"], found.map(&:method_name)+ assert_equal :ungated, found.first.gate+ end++ def test_finds_method_missing_as_ungated+ found = candidates_for("Rube::ScannerTest::ProxyFixture")+ assert_includes found.map(&:method_name), "method_missing"+ end++ def test_negative_control_class_with_no_auto_invoked_methods_is_not_reported+ assert_empty candidates_for("Rube::ScannerTest::InertFixture")+ end++ def test_precision_control_inherited_methods_are_not_reported+ assert_empty candidates_for("Rube::ScannerTest::InheritsOnlyFixture")+ end++ def test_candidates_carry_source_location+ candidate = candidates_for("Rube::ScannerTest::GatedFixture").first+ refute_nil candidate.source_location+ assert_includes candidate.source_location, "scanner_test.rb"+ end++ def test_candidates_report_arity+ candidate = candidates_for("Rube::ScannerTest::GatedFixture").first+ assert_equal 1, candidate.arity+ end++ def test_ungated_methods_report_zero_arity+ candidate = candidates_for("Rube::ScannerTest::UngatedFixture").first+ assert_predicate candidate, :zero_arity?+ end++ def test_reachability_via_instance_variable_read+ candidate = candidates_for("Rube::ScannerTest::StatefulFixture").first+ assert_predicate candidate, :touches_state?+ assert_predicate candidate, :reachable?+ end++ def test_reachability_via_implicit_self_call+ candidate = candidates_for("Rube::ScannerTest::AccessorFixture").first+ assert_predicate candidate, :touches_state?, "attr_reader access must count as touching state"+ assert_predicate candidate, :reachable?+ end++ def test_negative_control_stateless_method_is_not_reachable+ candidate = candidates_for("Rube::ScannerTest::StatelessFixture").first+ refute_predicate candidate, :touches_state?+ refute_predicate candidate, :reachable?+ end++ def test_gated_sinks_are_reachable_regardless_of_state+ candidate = candidates_for("Rube::ScannerTest::GatedFixture").first+ assert_predicate candidate, :reachable?+ end++ def test_reachable_is_a_strict_subset_of_candidates+ report = scan(namespace: "Gem")+ refute_empty report.reachable+ assert_operator report.reachable.length, :<, report.candidates.length,+ "reachability filter kept everything, so it is not filtering"+ end++ def test_rediscovers_accessor_backed_stdlib_sink+ report = scan(namespace: "Gem")+ names = report.reachable.map(&:to_s)+ assert_includes names, "Gem::Requirement#hash"+ end++ def test_rediscovers_a_real_stdlib_sink_without_hardcoding+ report = scan(namespace: "Gem")+ names = report.gated.map { |c| "#{c.class_name}##{c.method_name}" }+ assert_includes names, "Gem::Requirement#marshal_load"+ refute_includes Scanner::GATED_METHODS + Scanner::UNGATED_METHODS, "Gem::Requirement"+ end++ def test_namespace_filter_excludes_everything_else+ report = scan(namespace: "Rube::ScannerTest")+ assert(report.candidates.all? { |c| c.class_name.start_with?("Rube::ScannerTest") })+ end++ def test_report_partitions_gated_and_ungated+ report = local_scan+ assert_equal report.candidates.length, report.gated.length + report.ungated.length+ assert_empty(report.gated & report.ungated)+ end++ def test_scan_is_deterministic+ first = local_scan.candidates.map(&:to_s).sort+ second = local_scan.candidates.map(&:to_s).sort+ assert_equal first, second+ end++ def test_anonymous_classes_are_skipped+ Class.new { def marshal_load(data); end }+ refute(local_scan.candidates.any? { |c| c.class_name.nil? || c.class_name.empty? })+ end++ def test_scanning_does_not_instantiate_anything+ refute GatedFixture.instantiated+ local_scan+ refute GatedFixture.instantiated, "scanner constructed a candidate class"+ end++ class GatedFixture+ @instantiated = false++ class << self+ attr_accessor :instantiated+ end++ def marshal_load(data); end+ end++ class UserDefFixture+ def self._load(data)+ allocate+ end+ end++ class UngatedFixture+ def hash+ super+ end+ end++ class ProxyFixture+ def method_missing(name, *args)+ super+ end++ def respond_to_missing?(name, include_private = false)+ super+ end+ end++ class StatefulFixture+ def hash+ @seed.to_i+ end+ end++ class AccessorFixture+ attr_reader :seed++ def hash+ seed.to_i+ end+ end++ class StatelessFixture+ def hash+ 42+ end+ end++ class InertFixture+ def ordinary_method; end++ def another_one(argument); end+ end++ class InheritsOnlyFixture+ end+ end+end