augure-profiler 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a668c990f083c8eb2d00f67ce45ccb99fb37525ee1013e484e63cf6b00f0b561
+  data.tar.gz: f86407235e580f36e236b52b1c406dfb7159b5d9dea733ec5d293ff68ac54678
+SHA512:
+  metadata.gz: 1493d1d5d121787f04ce661350f6eb89922cfe64555f15e9cf6cd90c7d543f45cd7d7e8eff4fcfaf7b4ad9b1492f7fd362cce5b043f10d80e319895824f2cf5f
+  data.tar.gz: 3a19f8acd46eaa23537b10bf279442631e93a567fd22d81e5aec918e50b63c5ae782874c8779836afa3815f6f5a21bd7c8169fd84e0e2450b182ff214c4d13f4

data/exe/augure-profile

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Bootstrap the bundler context from the checkout: the CLI runs from any
+# working directory (when not already inside `bundle exec`).
+unless defined?(Bundler)
+  ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __dir__)
+  require "bundler/setup"
+end
+
+require "optparse"
+require_relative "../lib/augure-profiler"
+
+out_path = nil
+OptionParser.new do |opts|
+  opts.banner = "Usage: augure-profile <binary> [-o target.facts]"
+  opts.on("-o PATH", "Write facts to PATH (default: stdout)") { |v| out_path = v }
+  opts.on("--version", "Print the version") do
+    puts "augure-profiler #{AugureProfiler::VERSION}"
+    exit 0
+  end
+end.parse!(ARGV)
+
+binary = ARGV.shift or abort(<<~USAGE)
+  Usage: augure-profile <binary> [-o target.facts]
+
+  Generates an augure fact file from an ELF binary: checksec, PLT
+  imports, unsafe-symbol hints and semantically classified gadgets.
+  The binary is read-only; the profiler never executes anything.
+USAGE
+
+begin
+  facts = AugureProfiler::Profiler.new(binary).facts
+  if out_path
+    File.write(out_path, facts.to_s)
+    warn "augure-profile: wrote #{out_path} (#{facts.size} facts)"
+  else
+    puts facts
+  end
+rescue Metasm::ParseError, StandardError => e
+  abort("augure-profile: #{binary}: #{e.message}")
+end

data/home/runner/work/augure/augure/profiler/exe/augure-profile

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Bootstrap the bundler context from the checkout: the CLI runs from any
+# working directory (when not already inside `bundle exec`).
+unless defined?(Bundler)
+  ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __dir__)
+  require "bundler/setup"
+end
+
+require "optparse"
+require_relative "../lib/augure-profiler"
+
+out_path = nil
+OptionParser.new do |opts|
+  opts.banner = "Usage: augure-profile <binary> [-o target.facts]"
+  opts.on("-o PATH", "Write facts to PATH (default: stdout)") { |v| out_path = v }
+  opts.on("--version", "Print the version") do
+    puts "augure-profiler #{AugureProfiler::VERSION}"
+    exit 0
+  end
+end.parse!(ARGV)
+
+binary = ARGV.shift or abort(<<~USAGE)
+  Usage: augure-profile <binary> [-o target.facts]
+
+  Generates an augure fact file from an ELF binary: checksec, PLT
+  imports, unsafe-symbol hints and semantically classified gadgets.
+  The binary is read-only; the profiler never executes anything.
+USAGE
+
+begin
+  facts = AugureProfiler::Profiler.new(binary).facts
+  if out_path
+    File.write(out_path, facts.to_s)
+    warn "augure-profile: wrote #{out_path} (#{facts.size} facts)"
+  else
+    puts facts
+  end
+rescue Metasm::ParseError, StandardError => e
+  abort("augure-profile: #{binary}: #{e.message}")
+end

data/home/runner/work/augure/augure/profiler/lib/augure-profiler/dynamic_trace.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "metasm"
+require "open3"
+require "tmpdir"
+
+module AugureProfiler
+  # The dynamic layer: the debugger in the loop, like the original
+  # tool's dbg.pm. Three answers static analysis cannot give:
+  #   1. WHICH instruction wrote the overflowing bytes over the return
+  #      slot (the taint, proven by a watchpoint on the very address the
+  #      static frame read computed);
+  #   2. the runtime map (libc, stack, heap) of a live run - the decor
+  #      confirmed, not inferred;
+  #   3. nothing else - the tests of the built bytes remain the truth.
+  module DynamicTrace
+    module_function
+
+    # 1. The write-site proof, ONE gdb session (no cross-run address
+    # to carry: the stack shifts between runs, the session cannot):
+    # break the vulnerable function the static read named, watch the
+    # return slot living at $rsp on entry, continue - the stop whose
+    # new value carries the input's bytes IS the writing instruction.
+    def write_site(binary, input)
+      static = StaticOffset.offset(binary)
+      return nil unless static&.dig(:function)
+
+      input_file = File.join(Dir.tmpdir, "augure_write_input_#{Process.pid}")
+      File.binwrite(input_file, input)
+      cmds = [
+        "break #{static[:function]}",
+        "run < #{input_file}",
+        "watch *(unsigned long *) $rsp"
+      ]
+      6.times { cmds << "continue" }
+      cmds << "bt 3" << "x/i $pc"
+      out, _err, _st = Open3.capture3({"DEBUGINFOD_URLS" => ""}, "gdb", "-batch",
+        *cmds.flat_map { |c| ["-ex", c] }, binary)
+      blocks = out.split(/Hardware (?:access |)watchpoint \d+: \*/)
+      # the stop whose new value carries our filler bytes (the input's
+      # leading word) - the call machinery does not write the pattern
+      the_stop = blocks.find { |b| b =~ /New value = 4702111234474983745|New value = 4702111234474983746/ }
+      return nil unless the_stop
+
+      new_line = the_stop.lines.index { |l| l.include?("4702111234474983745") }
+      pc = new_line ? the_stop.lines[(new_line + 1)..].find { |l| l =~ /0x[0-9a-f]+ in / } : nil
+      func = pc&.slice(/in [A-Za-z_@][\w@<>]*/)&.sub("in ", "") || "unknown"
+      addr = pc&.slice(/\A\s*0x[0-9a-f]+/)&.strip
+      {function: func, instruction: addr.to_s, caller: static[:function], sink: static[:sink]}
+    ensure
+      File.delete(input_file) if input_file && File.exist?(input_file)
+    end
+
+    # 2. The runtime map: what the loader actually mapped for this run.
+    # Returns {libc_base:, stack_base:, stack_end:, heap_base:} (nils
+    # when absent) - the decor confirmed.
+    def runtime_map(binary)
+      # at starti the loader has not mapped libc yet: break main, the
+      # decor is complete by then
+      out, _err, _st = Open3.capture3({"DEBUGINFOD_URLS" => ""}, "gdb", "-batch",
+        "-ex", "break main", "-ex", "run", "-ex", "info proc mappings", binary)
+      libc_base = nil
+      stack_base = nil
+      stack_end = nil
+      heap_base = nil
+      out.lines.each do |l|
+        if (m = l.match(/\A\s*(0x[0-9a-f]+)\s+(0x[0-9a-f]+)\s+\S+\s+\S+\s+(.+?)\s*\z/i))
+          lo = m[1].to_i(16)
+          hi = m[2].to_i(16)
+          what = m[3].to_s.strip
+          libc_base ||= lo if /libc\.so/.match?(what)
+          stack_base ||= lo if /\[\s*stack\s*\]/i.match?(what)
+          stack_end = hi if /\[\s*stack\s*\]/i.match?(what)
+          heap_base ||= lo if what.include?("[heap]")
+        end
+      end
+      {libc_base: libc_base, stack_base: stack_base, stack_end: stack_end, heap_base: heap_base}
+    end
+  end
+end

data/home/runner/work/augure/augure/profiler/lib/augure-profiler/fuzzer.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module AugureProfiler
+  # Input fuzzing: mutate a seed, deliver to the target's stdin, detect
+  # crashes by signal. The built-in RubyMutator is zero-dependency and
+  # covers CTF-grade discovery; radamsa (subprocess) upgrades the
+  # mutation quality when installed. This is the fact DISCOVERY layer
+  # for binaries that have no write-up.
+  class TriageError < StandardError; end
+
+  module RubyMutator
+    BOUNDARY_BYTES = ["\x00".b, "\xff".b, "\x80".b, "\n".b, "%n".b].freeze
+
+    module_function
+
+    def mutate(seed, count, rng, max_len: 256)
+      (0...count).map do
+        variant = apply_one_mutation(seed.dup, rng)
+        variant = variant[0, max_len]
+        variant << ("A" * 8) if variant.empty?
+        variant
+      end
+    end
+
+    def apply_one_mutation(input, rng)
+      case rng.rand(4)
+      when 0 then bit_flip(input, rng)
+      when 1 then repeat_chunk(input, rng)
+      when 2 then inject_boundary(input, rng)
+      else extend_pattern(input, rng)
+      end
+    end
+
+    def bit_flip(input, rng)
+      return input if input.empty?
+
+      i = rng.rand(input.bytesize)
+      input.setbyte(i, input.getbyte(i) ^ (1 << rng.rand(8)))
+      input
+    end
+
+    def repeat_chunk(input, rng)
+      return input if input.empty?
+
+      at = rng.rand(input.bytesize)
+      len = [rng.rand(input.bytesize) + 1, 16].min
+      input.insert(at, input[at, len] * 2)
+    end
+
+    def inject_boundary(input, rng)
+      at = rng.rand(input.bytesize + 1)
+      input.insert(at, BOUNDARY_BYTES[rng.rand(BOUNDARY_BYTES.size)])
+    end
+
+    # The classic: grow with the cyclic pattern - offsets become readable
+    # in the crash report.
+    def extend_pattern(input, rng)
+      growth = "A" * (8 + rng.rand(64))
+      (input + growth.b)
+    end
+  end
+
+  module Fuzzer
+    CRASH_SIGNALS = [
+      Signal.list["SEGV"], Signal.list["ABRT"], Signal.list["ILL"]
+    ].freeze
+
+    module_function
+
+    def run(binary, seed: "AAAA", inputs: 50, max_len: 256, mutator: :ruby, rng: Random.new)
+      # The CTF bread-and-butter first: a deterministic length sweep.
+      # Crashes here reveal the OFFSET (the pattern bytes in the faulting
+      # address are readable in the triage report).
+      sweep = (8..max_len).step(8).map { |len| (seed * (len / seed.length + 1))[0, len] }
+      random = case mutator
+      when :ruby then RubyMutator.mutate(seed, inputs, rng, max_len: max_len)
+      when :radamsa then radamsa_mutations(seed, inputs)
+      else raise ArgumentError, "unknown mutator #{mutator.inspect}"
+      end
+
+      (sweep + random).filter_map do |input|
+        _out, _err, status = Open3.capture3(binary, stdin_data: input)
+        {input: input} if status.signaled? && CRASH_SIGNALS.include?(status.termsig)
+      end
+    end
+
+    def radamsa_mutations(seed, count)
+      return Array.new(count) { seed } unless system("sh", "-c", "command -v radamsa >/dev/null 2>&1")
+
+      (0...count).map do
+        out, _err, status = Open3.capture3("sh", "-c", "printf '%s' \"$1\" | radamsa", "sh", "-", seed)
+        (status.success? && !out.empty?) ? out : seed
+      end
+    end
+  end
+
+  # Crash triage: WHAT happened, in facts the decision layer consumes.
+  # Backends are uniform: run(binary, input) -> {signal, registers,
+  # fault_addr, control}. Default gdb (batch); rizin/r2 and lldb cover
+  # the other toolchains. metasm stays on the static side.
+  class TriageError < StandardError; end
+
+  module Triage
+    module_function
+
+    def resolve_backend(override: nil)
+      candidates = [override, :gdb, :rizin, :lldb].compact
+      candidates.find do |b|
+        bin = {gdb: "gdb", rizin: "rizin", r2: "radare2", lldb: "lldb"}[b]
+        bin && system("sh", "-c", "command -v '#{bin}' >/dev/null 2>&1")
+      end
+    end
+
+    def run(binary, input, backend: nil)
+      resolved = resolve_backend(override: backend)
+      raise TriageError, "no triage backend found (gdb, rizin or lldb required)" unless resolved
+
+      send(:"#{resolved}_triage", binary, input)
+    end
+
+    # The msf-style pattern: unique 3-grams (aA0aA1...), so ANY 3+ byte
+    # subsequence pins its exact offset. The crash address read under the
+    # debugger is found back in the pattern - that IS the offset to the
+    # return address, computed instead of guessed.
+    def cyclic(length)
+      out = +""
+      until out.size >= length
+        ("a".."z").each do |a|
+          ("A".."Z").each do |b|
+            ("0".."9").each do |c|
+              out << a + b + c
+              return out[0, length] if out.size >= length
+            end
+          end
+        end
+      end
+      out[0, length]
+    end
+
+    # The offset of `bytes` inside the pattern: try the full register
+    # width first, then the 32-bit truncation (the classic case where
+    # only four pattern bytes survive in the saved return slot).
+    def cyclic_offset(pattern, bytes)
+      [8, 4].each do |width|
+        next if bytes.bytesize < width
+
+        found = pattern.index(bytes[0, width])
+        return found if found
+      end
+      nil
+    end
+
+    # Two steps, like a human would: find the crash LENGTH with the
+    # deterministic sweep, then send a cyclic pattern of exactly that
+    # length so the crash lands on the corrupted return (an oversized
+    # pattern would fault on the stack write itself, never at the ret).
+    # The crash address read under the debugger is found back in the
+    # pattern - that IS the offset to the return address, computed
+    # instead of guessed. Returns nil when the binary does not crash or
+    # the pointer is not ours.
+    def offset(binary, backend: nil)
+      sweep = Fuzzer.run(binary, inputs: 40, max_len: 1024)
+      crash_len = sweep.first&.dig(:input)&.bytesize
+      return nil unless crash_len
+
+      # The sweep length is the MINIMAL overflow; the pattern needs
+      # enough tail to fill the whole saved-return slot with pattern
+      # bytes (8 on x64) while staying far from the write-fault zone.
+      pattern = cyclic(crash_len + 64)
+      report = run(binary, pattern, backend: backend)
+      return nil unless report[:signal] == "SIGSEGV"
+
+      # rip first (the clean case); then the saved-frame-pointer slot:
+      # a leave;ret epilogue crashes in leave when rbp is smashed, and
+      # the return slot sits exactly one register-width above it.
+      regs = report[:registers]
+      [["rip", 0], ["eip", 0], ["rbp", 8], ["ebp", 8]].each do |reg, shift|
+        addr = regs[reg]
+        next unless addr.is_a?(String) && addr.start_with?("0x")
+
+        off = cyclic_offset(pattern, [addr[2..].to_i(16)].pack("Q<"))
+        return off + shift if off
+      end
+      nil
+    end
+
+    def facts(report)
+      return "" unless report[:signal] == "SIGSEGV"
+
+      facts = ["vuln(\"sof\").\n"]
+      if report[:control]
+        facts << "return_addr_filtered(\"false\").\n"
+      end
+      facts.join
+    end
+
+    def gdb_triage(binary, input)
+      input_file = File.join(Dir.tmpdir, "augure_fuzz_input_#{Process.pid}")
+      File.binwrite(input_file, input)
+      # DEBUGINFOD_URLS empty: gdb's debuginfo auto-download queries the
+      # network and turns every batch run into a minutes-long stall (the
+      # CI triage went 180s per example on it).
+      out, _err, _status = Open3.capture3(
+        {"DEBUGINFOD_URLS" => ""}, "gdb", "-batch",
+        "-ex", "run < #{input_file}", "-ex", "info registers",
+        "-ex", "x/i $pc", binary
+      )
+      parse_gdb(out)
+    ensure
+      File.delete(input_file) if input_file && File.exist?(input_file)
+    end
+
+    def parse_gdb(output)
+      signal = output[/Program received signal (SIG\w+)/, 1]
+      registers = {}
+      output.each_line do |line|
+        if (m = line.match(/\A(\w+)\s+(0x[0-9a-f]+|\d+)\s/))
+          registers[m[1]] = m[2]
+        end
+      end
+      # The faulting address: the instruction pointer when control was
+      # hijacked, else the faulting line's address.
+      fault_addr = registers["rip"] || registers["eip"] || output[/\A(0x[0-9a-f]+)/, 1]
+      control = detect_control(registers, output)
+      {signal: signal, registers: registers, fault_addr: fault_addr, control: control}
+    end
+
+    # Input-pattern control: the faulting address is made of pattern
+    # bytes - the return address IS under input control.
+    def detect_control(registers, _output)
+      %w[rip eip].each do |reg|
+        addr = registers[reg]
+        next unless addr.is_a?(String) && addr.start_with?("0x")
+
+        bytes = [addr[2..].to_i(16)].pack("Q<").delete("\x00A")
+        return reg.to_sym if addr.include?("4141") || bytes.empty?
+      end
+      :none
+    end
+
+    def rizin_triage(binary, input)
+      input_file = File.join(Dir.tmpdir, "augure_fuzz_input_#{Process.pid}")
+      File.binwrite(input_file, input)
+      out, _err, _status = Open3.capture3(
+        "rizin", "-d", "-q", "-c", "dc; drp; dk 9", binary, "-", "<", input_file
+      )
+      parse_rizin(out)
+    ensure
+      File.delete(input_file) if input_file && File.exist?(input_file)
+    end
+
+    def parse_rizin(output)
+      signal = output[/signal (\d+|SIG\w+)/, 1] ? "SIGSEGV" : nil
+      signal ||= "SIGSEGV" if /Segmentation fault/.match?(output)
+      registers = {}
+      output.each_line do |line|
+        if (m = line.match(/\A(\w+)\s+=\s+(0x[0-9a-f]+)/))
+          registers[m[1]] = m[2]
+        end
+      end
+      {signal: signal, registers: registers, fault_addr: registers["rip"] || registers["eip"],
+       control: :none}
+    end
+
+    def lldb_triage(binary, input)
+      input_file = File.join(Dir.tmpdir, "augure_fuzz_input_#{Process.pid}")
+      File.binwrite(input_file, input)
+      out, _err, _status = Open3.capture3(
+        "lldb", "--batch", "-o", "run < #{input_file}", "-o", "register read",
+        "-o", "bt", binary
+      )
+      parse_lldb(out)
+    ensure
+      File.delete(input_file) if input_file && File.exist?(input_file)
+    end
+
+    def parse_lldb(output)
+      signal = output[/received signal (SIG\w+)/, 1]
+      registers = {}
+      output.each_line do |line|
+        if (m = line.match(/\A\s*(\w+) = (0x[0-9a-f]+)/))
+          registers[m[1]] = m[2]
+        end
+      end
+      {signal: signal, registers: registers, fault_addr: registers["rip"] || registers["eip"],
+       control: :none}
+    end
+  end
+end

data/home/runner/work/augure/augure/profiler/lib/augure-profiler/gadget_hunt.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "metasm"
+require_relative "static_offset"
+
+module AugureProfiler
+  # The general gadget hunter: the byte patterns catch the classics;
+  # this walks EVERY offset of the executable sections, decodes the
+  # chain that ends on a ret, and classifies it semantically. The
+  # multi-instruction gadgets (pop rsi; pop r15; ret) the patterns
+  # never see come out of here.
+  module GadgetHunt
+    MAX_CHAIN = 8
+    # the instructions that end a hunt-able chain
+    TERMINAL = %w[ret].freeze
+    # the semantics that kill control (the chain dies there)
+    KILLERS = %w[call jmp lret hlt iret syscall int leave loop].freeze
+
+    module_function
+
+    # Returns [{type:, addr:}] - the facts-ready tuples.
+    def hunt(path)
+      elf = Metasm::ELF.decode_file(path)
+      arch = (elf.header.e_class.to_s == "64") ? :x64 : :x86
+      cpu = (arch == :x64) ? Metasm::X64.new : Metasm::Ia32.new
+      gadgets = []
+      elf.sections.select { |s| s.flags.map(&:to_s).include?("EXECINSTR") && s.size.to_i > 0 }
+        .each do |sec|
+        data = StaticOffset.section_data(path, sec)
+        base = sec.addr.to_i
+        # ONE EncodedData per section: decode_instruction reads from
+        # edata.ptr, so each offset is a pointer move - not a copy of
+        # the remaining section (the old data[off..] was O(n^2) in
+        # memory traffic: ~512 GB cumulative for a 1 MB .text).
+        edata = Metasm::EncodedData.new(data)
+        (0...data.bytesize).each do |i|
+          chain = decode_chain(cpu, edata, i, base)
+          next unless chain
+
+          type = classify(chain)
+          next unless type
+
+          gadgets << {type: type, addr: base + i}
+        end
+      end
+      gadgets
+    end
+
+    # decode up to MAX_CHAIN instructions starting at offset i; the
+    # chain must END on a terminal (ret) with no killer inside. Returns
+    # the instruction STRINGS or nil. edata is shared: decode_at moves
+    # its ptr, callers must not assume it stays put.
+    def decode_chain(cpu, edata, i, _base)
+      instrs = []
+      off = i
+      limit = edata.data.bytesize
+      MAX_CHAIN.times do
+        return nil if off >= limit
+
+        di = decode_at(cpu, edata, off)
+        return nil unless di
+
+        text = di.instruction.to_s
+        op = di.instruction.opname
+        return nil if KILLERS.include?(op)
+
+        break if TERMINAL.include?(op)
+
+        instrs << text
+        off += di.bin_length.to_i
+        return nil if instrs.size >= MAX_CHAIN
+      end
+      return nil if instrs.empty?
+
+      instrs + ["ret"]
+    end
+
+    # decode one instruction at edata offset off - metasm's one-shot
+    # decode_instruction reading from the shared EncodedData's ptr
+    def decode_at(cpu, edata, off)
+      edata.ptr = off
+      di = cpu.decode_instruction(edata, 0)
+      di&.instruction ? di : nil
+    rescue Metasm::DecodeError, Metasm::ParseError
+      nil
+    end
+
+    def classify(instrs)
+      tail = instrs.last
+      return nil unless tail == "ret"
+
+      pops = instrs[0...-1].select { |i| i.start_with?("pop ") }
+      if instrs.length == pops.length + 1 && pops.any?
+        regs = pops.map { |i| i.delete_prefix("pop ") }
+        return "pop_#{regs.join("_")}_ret"
+      end
+      return "syscall_ret" if instrs.length == 2 && instrs.first.start_with?("syscall")
+      return "int80_ret" if instrs.length == 2 && instrs.first.start_with?("int 0x80")
+      return "xchg_rsp_rax" if instrs.length == 2 && instrs.first =~ /xchg .*rsp.*|xchg .*esp.*/
+
+      if instrs.length == 2 && instrs.first.start_with?("mov ") && instrs.first.include?("[") &&
+          instrs.first.include?("]")
+        return "mov_deref_write"
+      end
+
+      nil
+    end
+  end
+end