elftools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c59b0333aab08b885d294a4d0295d6bac48eb11c
+  data.tar.gz: 79ce95770fcf3911db8c7260bc6009d8e3cf2839
+SHA512:
+  metadata.gz: f1bf67e49c1d910509199fd1c4276760ecc022a9e88a1045ddd3aeccab62f258a176bc57b059b71eec3b74bde3d652d666b53284a701785df5c79a385dbfc8aa
+  data.tar.gz: e5b41464b5b6d092bbb0cf752b73594a8771d5c91840ee471fd0744ed7259d994c25a3a46d2e2d509907aef12b1e0c817a77b1d544f3c5bd01c350e2f3b4cd0a

data/README.md

@@ -0,0 +1,139 @@
+[![Build Status](https://travis-ci.org/david942j/rbelftools.svg?branch=master)](https://travis-ci.org/david942j/rbelftools)
+[![Code Climate](https://codeclimate.com/github/david942j/rbelftools/badges/gpa.svg)](https://codeclimate.com/github/david942j/rbelftools)
+[![Issue Count](https://codeclimate.com/github/david942j/rbelftools/badges/issue_count.svg)](https://codeclimate.com/github/david942j/rbelftools)
+[![Test Coverage](https://codeclimate.com/github/david942j/rbelftools/badges/coverage.svg)](https://codeclimate.com/github/david942j/rbelftools/coverage)
+[![Inline docs](https://inch-ci.org/github/david942j/rbelftools.svg?branch=master)](https://inch-ci.org/github/david942j/rbelftools)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)
+
+# Introduction
+
+ELF parser in pure ruby implementation. This work is inspired by [pyelftools](https://github.com/eliben/pyelftools) by [Eli Bendersky](https://github.com/eliben).
+
+The motivation to create this repository is want to be a dependency of [pwntools-ruby](https://github.com/peter50216/pwntools-ruby). Since ELF parser is a big work, it should not be implemented directly in pwntools.
+
+**rbelftools**'s target is to create a nice ELF parser library in ruby. More features are work in progress.
+
+# Install
+
+Available on RubyGems.org!
+```bash
+gem install elftools
+```
+
+# Example Usage
+
+## Start from file object
+```ruby
+require 'elftools'
+elf = ELFTools::ELFFile.new(File.open('spec/files/amd64.elf'))
+#=> #<ELFTools::ELFFile:0x00560b147f8328 @elf_class=64, @endian=:little, @stream=#<File:spec/files/amd64>>
+
+elf.machine
+#=> 'Advanced Micro Devices X86-64'
+
+elf.build_id
+#=> '73ab62cb7bc9959ce053c2b711322158708cdc07'
+```
+
+## Sections
+```ruby
+elf.section_by_name('.dynstr')
+#=>
+# #<ELFTools::Sections::StrTabSection:0x00560b148cef40
+# @header=
+#  {:sh_name=>86,
+#   :sh_type=>3,
+#   :sh_flags=>2,
+#   :sh_addr=>4195224,
+#   :sh_offset=>920,
+#   :sh_size=>113,
+#   :sh_link=>0,
+#   :sh_info=>0,
+#   :sh_addralign=>1,
+#   :sh_entsize=>0},
+# @name=".dynstr">
+```
+```ruby
+elf.sections.map(&:name).join(' ')
+#=> " .interp .note.ABI-tag .note.gnu.build-id .gnu.hash .dynsym .dynstr .gnu.version .gnu.version_r .rela.dyn .rela.plt .init .plt .plt.got .text .fini .rodata .eh_frame_hdr .eh_frame .init_array .fini_array .jcr .dynamic .got .got.plt .data .bss .comment .shstrtab .symtab .strtab"
+```
+```ruby
+elf.section_by_name('.note.gnu.build-id').data
+#=> "\x04\x00\x00\x00\x14\x00\x00\x00\x03\x00\x00\x00GNU\x00s\xABb\xCB{\xC9\x95\x9C\xE0S\xC2\xB7\x112!Xp\x8C\xDC\a"
+```
+
+## Symbols
+```ruby
+symtab_section = elf.section_by_name('.symtab')
+symtab_section.num_symbols
+#=> 75
+
+symtab_section.symbol_by_name('puts@@GLIBC_2.2.5')
+#=>
+# #<ELFTools::Symbol:0x00560b14af67a0
+#  @header={:st_name=>348, :st_info=>18, :st_other=>0, :st_shndx=>0, :st_value=>0, :st_size=>0},
+#  @name="puts@@GLIBC_2.2.5">
+
+symbols = symtab_section.symbols # Array of symbols
+symbols.map(&:name).reject(&:empty?).first(5).join(' ')
+#=> "crtstuff.c __JCR_LIST__ deregister_tm_clones register_tm_clones __do_global_dtors_aux"
+```
+
+## Segments
+```ruby
+elf.segment_by_type(:note)
+#=>
+# #<ELFTools::Segments::NoteSegment:0x00555beaafe218
+# @header=
+#  {:p_type=>4,
+#   :p_flags=>4,
+#   :p_offset=>624,
+#   :p_vaddr=>624,
+#   :p_paddr=>624,
+#   :p_filesz=>68,
+#   :p_memsz=>68,
+#   :p_align=>4}>
+
+elf.segment_by_type(:interp).interp_name
+#=> "/lib64/ld-linux-x86-64.so.2"
+```
+
+# Why rbelftools
+
+1. Fully documented
+
+   Always important for an Open-Source project. Online document is [here](http://www.rubydoc.info/github/david942j/rbelftools/master/frames)
+2. Fully tested
+
+   Of course.
+3. Lazy loading on everything
+
+   To use **rbelftools**, only need to pass the stream object of ELF file.
+   **rbelftools** will read the stream object **as least times as possible** when parsing
+   the file. Most information will not be fetched until you need it, which makes
+   **rbelftools** efficient.
+4. To be a library
+
+   **rbelftools** is designed to be a library for furthur usage.
+   It will _not_ add any too trivial features.
+   For example, to check if NX disabled, you can use
+   `elf.segment_by_type(:gnu_stack).executable?` but not `elf.nx?`
+5. Section and segment parser
+
+   Providing common sections and segments parser. For example, .symtab, .shstrtab
+   .dynamic sections and INTERP, DYNAMIC segments, etc.
+
+# Development
+```bash
+git clone https://github.com/david942j/rbelftools.git
+cd rbelftools
+bundle
+rake
+```
+Any comments or suggestions are welcome!
+
+# Cross Platform
+**rbelftools** can be used on Linux and OSX. Should also work on Windows but not tested.
+
+# License
+MIT License

data/lib/elftools/constants.rb

@@ -0,0 +1,182 @@
+module ELFTools
+  # Define constants from elf.h.
+  # Mostly refer from https://github.com/torvalds/linux/blob/master/include/uapi/linux/elf.h.
+  module Constants
+    # ELF magic header
+    ELFMAG = "\x7FELF".freeze
+
+    # Section header types, records in +sh_type+.
+    module SHT
+      SHT_NULL     = 0
+      SHT_PROGBITS = 1
+      SHT_SYMTAB   = 2
+      SHT_STRTAB   = 3
+      SHT_RELA     = 4
+      SHT_HASH     = 5
+      SHT_DYNAMIC  = 6
+      SHT_NOTE     = 7
+      SHT_NOBITS   = 8
+      SHT_REL      = 9
+      SHT_SHLIB    = 10
+      SHT_DYNSYM   = 11
+      SHT_NUM      = 12
+      SHT_LOPROC   = 0x70000000
+      SHT_HIPROC   = 0x7fffffff
+      SHT_LOUSER   = 0x80000000
+      SHT_HIUSER   = 0xffffffff
+    end
+    include SHT
+
+    # Program header types, records in +p_type+.
+    module PT
+      PT_NULL         = 0
+      PT_LOAD         = 1
+      PT_DYNAMIC      = 2
+      PT_INTERP       = 3
+      PT_NOTE         = 4
+      PT_SHLIB        = 5
+      PT_PHDR         = 6
+      PT_TLS          = 7          # Thread local storage segment
+      PT_LOOS         = 0x60000000 # OS-specific
+      PT_HIOS         = 0x6fffffff # OS-specific
+      PT_LOPROC       = 0x70000000
+      PT_HIPROC       = 0x7fffffff
+      PT_GNU_EH_FRAME = 0x6474e550
+      PT_GNU_STACK    = (PT_LOOS + 0x474e551)
+    end
+    include PT
+
+    # Dynamic table types, records in +d_tag+.
+    module DT
+      DT_NULL       = 0
+      DT_NEEDED     = 1
+      DT_PLTRELSZ   = 2
+      DT_PLTGOT     = 3
+      DT_HASH       = 4
+      DT_STRTAB     = 5
+      DT_SYMTAB     = 6
+      DT_RELA       = 7
+      DT_RELASZ     = 8
+      DT_RELAENT    = 9
+      DT_STRSZ      = 10
+      DT_SYMENT     = 11
+      DT_INIT       = 12
+      DT_FINI       = 13
+      DT_SONAME     = 14
+      DT_RPATH      = 15
+      DT_SYMBOLIC   = 16
+      DT_REL        = 17
+      DT_RELSZ      = 18
+      DT_RELENT     = 19
+      DT_PLTREL     = 20
+      DT_DEBUG      = 21
+      DT_TEXTREL    = 22
+      DT_JMPREL     = 23
+      DT_ENCODING   = 32
+      DT_LOOS       = 0x6000000d
+      DT_HIOS       = 0x6ffff000
+      DT_VALRNGLO   = 0x6ffffd00
+      DT_VALRNGHI   = 0x6ffffdff
+      DT_ADDRRNGLO  = 0x6ffffe00
+      DT_ADDRRNGHI  = 0x6ffffeff
+      DT_VERSYM     = 0x6ffffff0
+      DT_RELACOUNT  = 0x6ffffff9
+      DT_RELCOUNT   = 0x6ffffffa
+      DT_FLAGS_1    = 0x6ffffffb
+      DT_VERDEF     = 0x6ffffffc
+      DT_VERDEFNUM  = 0x6ffffffd
+      DT_VERNEED    = 0x6ffffffe
+      DT_VERNEEDNUM = 0x6fffffff
+      DT_LOPROC     = 0x70000000
+      DT_HIPROC     = 0x7fffffff
+    end
+    include DT
+
+    # These constants define the various ELF target machines.
+    module EM
+      EM_NONE           = 0
+      EM_M32            = 1
+      EM_SPARC          = 2
+      EM_386            = 3
+      EM_68K            = 4
+      EM_88K            = 5
+      EM_486            = 6      # Perhaps disused
+      EM_860            = 7
+      EM_MIPS           = 8      # MIPS R3000 (officially, big-endian only)
+      # Next two are historical and binaries and
+      # modules of these types will be rejected by Linux.
+      EM_MIPS_RS3_LE    = 10     # MIPS R3000 little-endian
+      EM_MIPS_RS4_BE    = 10     # MIPS R4000 big-endian
+
+      EM_PARISC         = 15     # HPPA
+      EM_SPARC32PLUS    = 18     # Sun's "v8plus"
+      EM_PPC            = 20     # PowerPC
+      EM_PPC64          = 21     # PowerPC64
+      EM_SPU            = 23     # Cell BE SPU
+      EM_ARM            = 40     # ARM 32 bit
+      EM_SH             = 42     # SuperH
+      EM_SPARCV9        = 43     # SPARC v9 64-bit
+      EM_H8_300         = 46     # Renesas H8/300
+      EM_IA_64          = 50     # HP/Intel IA-64
+      EM_X86_64         = 62     # AMD x86-64
+      EM_S390           = 22     # IBM S/390
+      EM_CRIS           = 76     # Axis Communications 32-bit embedded processor
+      EM_M32R           = 88     # Renesas M32R
+      EM_MN10300        = 89     # Panasonic/MEI MN10300, AM33
+      EM_OPENRISC       = 92     # OpenRISC 32-bit embedded processor
+      EM_BLACKFIN       = 106    # ADI Blackfin Processor
+      EM_ALTERA_NIOS2   = 113    # Altera Nios II soft-core processor
+      EM_TI_C6000       = 140    # TI C6X DSPs
+      EM_AARCH64        = 183    # ARM 64 bit
+      EM_TILEPRO        = 188    # Tilera TILEPro
+      EM_MICROBLAZE     = 189    # Xilinx MicroBlaze
+      EM_TILEGX         = 191    # Tilera TILE-Gx
+      EM_BPF            = 247    # Linux BPF - in-kernel virtual machine
+      EM_FRV            = 0x5441 # Fujitsu FR-V
+      EM_AVR32          = 0x18ad # Atmel AVR32
+
+      # This is an interim value that we will use until the committee comes up with a final number.
+      EM_ALPHA          = 0x9026
+
+      # Bogus old m32r magic number, used by old tools.
+      EM_CYGNUS_M32R    = 0x9041
+      # This is the old interim value for S/390 architecture
+      EM_S390_OLD       = 0xA390
+      # Also Panasonic/MEI MN10300, AM33
+      EM_CYGNUS_MN10300 = 0xbeef
+
+      # Return the architecture name according to +val+.
+      # Used by {ELFTools::ELFFile#machine}.
+      #
+      # Only supports famous archs.
+      # @param [Integer] val Value of +e_machine+.
+      # @return [String]
+      #   Name of architecture.
+      # @example
+      #   mapping(3)
+      #   #=> 'Intel 80386'
+      #   mapping(6)
+      #   #=> 'Intel 80386'
+      #   mapping(62)
+      #   #=> 'Advanced Micro Devices X86-64'
+      #   mapping(1337)
+      #   #=> '<unknown>: 0x539'
+      def self.mapping(val)
+        case val
+        when EM_NONE then 'None'
+        when EM_386, EM_486 then 'Intel 80386'
+        when EM_860 then 'Intel 80860'
+        when EM_MIPS then 'MIPS R3000'
+        when EM_PPC then 'PowerPC'
+        when EM_PPC64 then 'PowerPC64'
+        when EM_ARM then 'ARM'
+        when EM_IA_64 then 'Intel IA-64'
+        when EM_AARCH64 then 'AArch64'
+        when EM_X86_64 then 'Advanced Micro Devices X86-64'
+        else format('<unknown>: 0x%x', val)
+        end
+      end
+    end
+    include EM
+  end
+end

data/lib/elftools/dynamic.rb

@@ -0,0 +1,106 @@
+module ELFTools
+  # Define common methods for dynamic sections and
+  # dynamic segments.
+  #
+  # Notice: this module can only be included by
+  # {ELFTools::Sections::DynamicSection} and
+  # {ELFTools::Segments::DynamicSegment} because
+  # methods here assume some attributes exist.
+  module Dynamic
+    # Iterate all tags.
+    #
+    # Notice: this method assume the following methods
+    # already exist:
+    #   header
+    #   tag_start
+    # @param [Block] block You can give a block.
+    # @return [Array<ELFTools::Dynamic::Tag>] Array of tags.
+    def each_tags
+      arr = []
+      0.step do |i|
+        tag = tag_at(i)
+        yield tag if block_given?
+        arr << tag
+        break if tag.header.d_tag == ELFTools::Constants::DT_NULL
+      end
+      arr
+    end
+    alias tags each_tags
+
+    # Get a tag of specific type.
+    # @param [Integer, Symbol, String] type
+    #   Constant value, symbol, or string of type
+    #   is acceptable. See examples for more information.
+    # @return [ELFTools::Dynamic::Tag] The desired tag.
+    # @example
+    #   dynamic = elf.segment_by_type(:dynamic)
+    #   # type as integer
+    #   dynamic.tag_by_type(0) # the null tag
+    #   #=>  #<ELFTools::Dynamic::Tag:0x0055b5a5ecad28 @header={:d_tag=>0, :d_val=>0}>
+    #   dynamic.tag_by_type(ELFTools::Constants::DT_NULL)
+    #   #=>  #<ELFTools::Dynamic::Tag:0x0055b5a5ecad28 @header={:d_tag=>0, :d_val=>0}>
+    #
+    #   # symbol
+    #   dynamic.tag_by_type(:null)
+    #   #=>  #<ELFTools::Dynamic::Tag:0x0055b5a5ecad28 @header={:d_tag=>0, :d_val=>0}>
+    #   dynamic.tag_by_type(:pltgot)
+    #   #=> #<ELFTools::Dynamic::Tag:0x0055d3d2d91b28 @header={:d_tag=>3, :d_val=>6295552}>
+    #
+    #   # string
+    #   dynamic.tag_by_type('null')
+    #   #=>  #<ELFTools::Dynamic::Tag:0x0055b5a5ecad28 @header={:d_tag=>0, :d_val=>0}>
+    #   dynamic.tag_by_type('DT_PLTGOT')
+    #   #=> #<ELFTools::Dynamic::Tag:0x0055d3d2d91b28 @header={:d_tag=>3, :d_val=>6295552}>
+    def tag_by_type(type)
+      type = Util.to_constant(Constants::DT, type)
+      each_tags do |tag|
+        return tag if tag.header.d_tag == type
+      end
+      nil
+    end
+
+    # Get the +n+-th tag.
+    #
+    # Tags are lazy loaded.
+    # Notice: this method assume the following methods
+    # already exist:
+    #   header
+    #   tag_start
+    #
+    # Notice: we cannot do bound checking of +n+ here since
+    # the only way to get size of tags is calling +tags.size+.
+    # @param [Integer] n The index.
+    # @return [ELFTools::Dynamic::Tag] The desired tag.
+    def tag_at(n)
+      return if n < 0
+      @tag_at_map ||= {}
+      return @tag_at_map[n] if @tag_at_map[n]
+      dyn = ELF_Dyn.new(endian: endian)
+      dyn.elf_class = header.elf_class
+      stream.pos = tag_start + n * dyn.num_bytes
+      @tag_at_map[n] = Tag.new(dyn.read(stream), stream)
+    end
+
+    private
+
+    def endian
+      header.class.self_endian
+    end
+
+    # A tag class.
+    class Tag
+      attr_reader :header # @return [ELFTools::ELF_Dyn] The dynamic tag header.
+      attr_reader :stream # @return [File] Streaming object.
+
+      # Instantiate a {ELFTools::Dynamic::Tag} object.
+      # @param [ELF_Dyn] header The dynamic tag header.
+      # @param [File] stream Streaming object.
+      def initialize(header, stream)
+        @header = header
+        @stream = stream
+      end
+      # TODO: Get the name of tags, e.g. SONAME
+      # TODO: Handle (non)-PIE ELF correctly.
+    end
+  end
+end