elf_utils 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbf65536445ceb5a50fd33bb13227ee00837dde499a258a7e9004b3fc9a9716b
+  data.tar.gz: bc21c9017ecabe98263976c14cde0469a1da4c4bf1abca148d96b7eafdb31541
+SHA512:
+  metadata.gz: 5c976e5b1da62c450aff9448c6b4c5b3984819538d6973179a594cfdf1209805821530d9b7fe61389f064287a7dab28e33635306791e895eae005efe6d279d0b
+  data.tar.gz: c0db80808986319a171ca5f0452369668baa9cef8085fe38e9a76957dd54d79edf1960fd4d9fc7b2100d7793ee7b501150cf5c7b3fb700c1f2ac2a19b3f93894

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 3.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`dlary[at]cisco<dot>com`. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# How to Contribute
+
+Thanks for your interest in contributing to `elf_utils`! Here are a few
+general guidelines on contributing and reporting bugs that we ask you to review.
+Following these guidelines helps to communicate that you respect the time of the
+contributors managing and developing this open source project. In return, they
+should reciprocate that respect in addressing your issue, assessing changes, and
+helping you finalize your pull requests. In that spirit of mutual respect, we
+endeavor to review incoming issues and pull requests within 10 days, and will
+close any lingering issues or pull requests after 60 days of inactivity.
+
+Please note that all of your interactions in the project are subject to our
+[Code of Conduct](/CODE_OF_CONDUCT.md). This includes creation of issues or pull
+requests, commenting on issues or pull requests, and extends to all interactions
+in any real-time space e.g., Slack, Discord, etc.
+
+## Reporting Issues
+
+Before reporting a new issue, please ensure that the issue was not already
+reported or fixed by searching through our
+[issues list](https://github.com/cisco-open/elf_utils/issues).
+
+When creating a new issue, please be sure to include a **title and clear
+description**, as much relevant information as possible, and, if possible, a
+test case.
+
+**If you discover a security bug, please do not report it through GitHub.
+Instead, please see security procedures in [SECURITY.md](/SECURITY.md).**
+
+## Sending Pull Requests
+
+Before sending a new pull request, take a look at existing pull requests and
+issues to see if the proposed change or fix has been discussed in the past, or
+if the change was already implemented but not yet released.
+
+We expect new pull requests to include tests for any affected behavior, and,
+as we follow semantic versioning, we may reserve breaking changes until the
+next major version release.
+
+## Other Ways to Contribute
+
+We welcome anyone that wants to contribute to `elf_utils` to triage and
+reply to open issues to help troubleshoot and fix existing bugs. Here is what
+you can do:
+
+- Help ensure that existing issues follows the recommendations from the
+  _[Reporting Issues](#reporting-issues)_ section, providing feedback to the
+  issue's author on what might be missing.
+- Review existing pull requests, and testing patches against real existing
+  applications that use `elf_utils`.
+- Write a test, or add a missing test case to an existing test.
+
+Thanks again for your interest on contributing to `elf_utils`!
+
+:heart:

data/Gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in elfutils.gemspec
+gemspec
+
+group :test do
+  gem "jsonpath", "~> 1.1"
+  gem "pry", "~> 0.14"
+  gem "pry-rescue", "~> 1.5"
+  gem "pry-stack_explorer", "~> 0.6"
+  gem "rspec", "~> 3.0"
+end
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "standard", "~> 1.3"
+  gem "ruby-prof", "~> 1.6"
+  gem "benchmark", "~> 0.2.1"
+  gem "benchmark-ips", "~> 2.12"
+  gem "rake-compiler", "~> 1.2"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Cisco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/MAINTAINERS.md

@@ -0,0 +1,3 @@
+# Maintainers
+
+- [dmlary](https://github.com/dmlary)

data/README.md

@@ -0,0 +1,126 @@
+# ElfUtils
+
+[![Version](https://img.shields.io/gem/v/elf_utils.svg)](https://rubygems.org/gems/elf_utils)
+[![GitHub](https://img.shields.io/badge/github-elf__utils-blue.svg)](http://github.com/cisco-open/ruby-elf_utils)
+[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/ruby-elf_utils/frames)
+
+[![Contributor-Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md)
+[![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com)
+
+ElfUtils is a Ruby gem for parsing ELF files and DWARF debugging information.
+
+ElfUtils supports 32-bit & 64-bit ELF format, both big and little endian.  It
+also supports DWARF versions 2, 3, 4, and 5.  The handling of both ELF and
+DWARF formats **is not currently exhaustive**, but is sufficient to perform
+many common tasks such as calculating symbol address, finding symbol source
+location, extracting variable data types.
+
+If you encounter a place where the format support is incomplete, please open
+an issue.  We test against the generated binaries in [spec/data/](spec/data),
+but need more real-world examples to ensure proper format coverage.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add elf_utils
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install elf_utils
+
+## Usage
+ElfUtils covers a lot of ELF & DWARF functionality.  The best source for usage
+will be the documentation.  This is a small example of using ElfUtils to
+read a complex type from the memory of a running process, given an executable
+with DWARF debugging information to determine types.
+
+```ruby
+require "elf_utils"
+
+# open an ELF file, in this case an executable
+elf_file = ElfUtils.open("a.out")
+
+# get the Symbol instance for a global variable
+symbol = elf_file.symbol(:some_global_var)      # => #<ElfUtils::Symbol ...>
+
+# get the address of the symbol
+addr = symbol.addr                              # => 0x40001000
+
+# relocate the load segments to account for ASLR.  Addresses for load segments
+# extracted from /proc/pid/map.
+elf_file.load_segments[0].relocate(text_addr)
+elf_file.load_segments[1].relocate(data_addr)
+
+# get the address of the symbol after relocation
+addr = symbol.addr                              # => 0x90301000
+
+# get the data type for the symbol; requires DWARF debug information
+type = symbol.ctype                             # => #<CTypes::Struct ...>
+
+# open the memory for a process running this executable, and read the value of
+# the global variable.
+value = File.open(File.join("/proc", pid, "mem")) do |mem|
+    # read the raw bytes for the variable
+    bytes = mem.pread(type.size, addr)          # => "\xef\x99\xde... "
+
+    # unpack the bytes
+    type.unpack_one(bytes)                      # => { field: val, ... }
+end
+```
+
+### bin/dump_ctypes.rb
+[bin/dump_ctypes.rb] reads the `.debug_info` section of an ELF file, and
+generates ruby code to create each data type found in the binary.  This is
+particularly useful for exporting types for use with foreign-function interface
+(FFI).
+
+```sh
+~/src/elf_utils> bundle exec ./bin/dump_ctypes.rb spec/data/complex_64be-dwarf64-v5 > types.rb
+cu[  0] 0x0        (   0kb)  spec/data/test.c
+cu[  1] 0xdb       (   1kb)  spec/data/types.c
+~/src/elf_utils> head types.rb
+module Types
+  extend CTypes::Helpers
+
+  def self.with_bitfield
+    @with_bitfield ||= CTypes::Struct.builder()
+      .name("with_bitfield")
+      .endian(:big)
+      .attribute(bitfield {
+          field :a, offset: 31, bits: 1, signed: false
+          field :b, offset: 29, bits: 2, signed: true
+```
+
+## Roadmap
+
+See the [open issues](https://github.com/cisco-open/ruby-elf_utils/issues) for
+a list of proposed features (and known issues).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+Running the test suite requires a recent version of llvm be installed.  The
+tests use `llvm-readelf` and `llvm-dwarfdump` for verification.
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to
+learn, inspire, and create. Any contributions you make are **greatly
+appreciated**. For detailed contributing guidelines, please see
+[CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT). License. See
+[LICENSE.txt](LICENSE.txt) for more information.

data/Rakefile

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/clean"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "rake/extensiontask"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::ExtensionTask.new "elf_utils" do |ext|
+  ext.lib_dir = "lib/elf_utils"
+end
+
+task default: %i[compile]
+task spec: %i[compile spec_data]
+
+desc "Build the test data used in the specs"
+task :spec_data
+
+debug = {
+  "release" => "-O2",
+  "dwarf64-v5" => "-gdwarf-5 -gdwarf64 -O0",
+  "dwarf32-v5" => "-gdwarf-5 -gdwarf32 -O0",
+  "dwarf64-v4" => "-gdwarf-4 -gdwarf64 -O0",
+  "dwarf32-v4" => "-gdwarf-4 -gdwarf32 -O0",
+  "dwarf64-v3" => "-gdwarf-3 -gdwarf64 -O0",
+  "dwarf32-v3" => "-gdwarf-3 -gdwarf32 -O0",
+  "dwarf32-v2" => "-gdwarf-2 -gdwarf32 -O0"
+}
+target = {
+  "32le" => "--target=i386-pc-linux-gnu",
+  "64le" => "--target=x86_64-pc-linux-gnu",
+  "32be" => "--target=mips-pc-linux-gnu",
+  "64be" => "--target=mips64-pc-linux-gnu"
+}
+file_types = {
+  "" => "-fuse-ld=lld -nostdlib", # executable
+  ".o" => "-c",                   # object file
+  ".so" => "-fPIC -fuse-ld=lld --shared -nostdlib" # shared object file
+}
+
+# basic elf/dwarf files
+target.each do |target, target_flag|
+  file_types.each do |ext, type_flag|
+    debug.each do |debug, debug_flag|
+      next if debug =~ /64/ && target =~ /32/
+
+      path = "spec/data/test_#{target}-#{debug}#{ext}"
+      task spec_data: path
+      CLEAN << path
+      file path => "spec/data/test.c" do |task|
+        sh "#{ENV["CC"] || "clang"} #{debug_flag} #{target_flag} #{type_flag} #{task.source} -o #{task.name}"
+      end
+    end
+  end
+end
+
+# DWARF files with multiple compilation units, including the types for testing
+target.each do |target, target_flag|
+  debug.each do |debug, debug_flag|
+    next if debug == "release"
+    next if debug =~ /64/ && target =~ /32/
+
+    # grab the flags for an executable build
+    type_flag = file_types[""]
+
+    path = "spec/data/complex_#{target}-#{debug}"
+    task spec_data: path
+    CLEAN << path
+    file path => ["spec/data/test.c", "spec/data/types.c"] do |task|
+      sh "#{ENV["CC"] || "clang"} #{debug_flag} #{target_flag} #{type_flag} #{task.sources.join(" ")} -o #{task.name}"
+    end
+  end
+end

data/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for the
+`elf_utils` project.
+
+- [Disclosing a security issue](#disclosing-a-security-issue)
+- [Vulnerability management](#vulnerability-management)
+- [Suggesting changes](#suggesting-changes)
+
+## Disclosing a security issue
+
+The `elf_utils` maintainers take all security issues in the project
+seriously. Thank you for improving the security of `elf_utils`. We
+appreciate your dedication to responsible disclosure and will make every effort
+to acknowledge your contributions.
+
+`elf_utils` leverages GitHub's private vulnerability reporting.
+
+To learn more about this feature and how to submit a vulnerability report,
+review [GitHub's documentation on private reporting](https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).
+
+Here are some helpful details to include in your report:
+
+- a detailed description of the issue
+- the steps required to reproduce the issue
+- versions of the project that may be affected by the issue
+- if known, any mitigations for the issue
+
+A maintainer will acknowledge the report within three (3) business days, and
+will send a more detailed response within an additional three (3) business days
+indicating the next steps in handling your report.
+
+If you've been unable to successfully draft a vulnerability report via GitHub
+or have not received a response during the alloted response window, please
+reach out via the [Cisco Open security contact email](mailto:oss-security@cisco.com).
+
+After the initial reply to your report, the maintainers will endeavor to keep
+you informed of the progress towards a fix and full announcement, and may ask
+for additional information or guidance.
+
+## Vulnerability management
+
+When the maintainers receive a disclosure report, they will assign it to a
+primary handler.
+
+This person will coordinate the fix and release process, which involves the
+following steps:
+
+- confirming the issue
+- determining affected versions of the project
+- auditing code to find any potential similar problems
+- preparing fixes for all releases under maintenance
+
+## Suggesting changes
+
+If you have suggestions on how this process could be improved please submit an
+issue or pull request.

data/elf_utils.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/elf_utils/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "elf_utils"
+  spec.version = ElfUtils::VERSION
+  spec.authors = ["David M. Lary"]
+  spec.email = ["dmlary@gmail.com"]
+
+  spec.summary = "Library for parsing ELF files and DWARF debugging information"
+  # spec.description = "TODO: Write a longer description or delete this line."
+  spec.homepage = "https://github.com/cisco-open/elf_utils"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.extensions = %w[ext/elf_utils/extconf.rb]
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency "ctypes", "~> 0.2"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/ext/elf_utils/elf_utils.c

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Cisco
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <ruby.h>
+
+static VALUE
+uleb128_unpack_one(int argc, VALUE *argv, VALUE self)
+{
+    if (argc < 1) {
+        rb_raise(rb_eArgError,
+            "wrong number of arguments (given %d, expected at least 1)", argc);
+    }
+
+    char *buf       = StringValuePtr(argv[0]);
+    size_t len      = rb_str_length(argv[0]);
+    size_t offset   = 0;
+    uint64_t result = 0; // ran into conversion issues when using 128bit
+    int shift       = 0;
+
+    while (offset < len) {
+        uint8_t byte = *(buf + offset++);
+        result |= (uint64_t)(byte & 0x7F) << shift;
+
+        // If the MSB is not set, we're done
+        if ((byte & 0x80) == 0) {
+            // not returning a bigint here because the dry-types enum does not
+            // return the correct value for BigInts.
+            return rb_ary_new3(2, rb_uint2inum(result),
+                rb_str_substr(argv[0], offset, len - offset));
+        }
+
+        // Move to the next 7 bits
+        shift += 7;
+    }
+
+    rb_raise(rb_eRuntimeError, "ULEB128 string did not contain a terminator");
+}
+
+// Initialization function called when the extension is loaded
+void
+Init_elf_utils()
+{
+    // Define the class, if not defined already, and bind the C function
+    VALUE rb_elf_utils = rb_define_module("ElfUtils");
+    VALUE rb_types     = rb_define_module_under(rb_elf_utils, "Types");
+    VALUE rb_uleb128   = rb_define_module_under(rb_types, "ULEB128");
+
+    // Define the class method (static function) in the class
+    rb_define_module_function(
+        rb_uleb128, "unpack_one", uleb128_unpack_one, -1);
+}

data/ext/elf_utils/extconf.rb

@@ -0,0 +1,3 @@
+require "mkmf"
+
+create_makefile "elf_utils/elf_utils"