Skip to main content

isolate-elf — ELF Symbol Isolation for Bundled System Dependencies

Tool for renaming dynamic symbols in shared libraries to prevent interposition when bundled copies coexist with system copies in the same process.

What it does

Given libzstd.so.1, isolate-elf produces four artifacts:

  1. Prefixed .so — all exported symbols renamed (ZSTD_decompress → rocm_ZSTD_decompress) via direct ELF binary rewriting of .dynsym/.dynstr + hash table rebuild
  2. Trampoline .a — asm stubs exporting original names, tail-jumping to prefixed names via PLT
  3. Linker script — INPUT(stubs.a AS_NEEDED(real.so.1)) installed as -lzstd
  4. Redirect header — #define macros for compile-time bypass of trampolines

Autoconf AC_CHECK_LIB(zstd, ZSTD_decompress) works unmodified — the linker script provides the original name via the trampoline, which pulls in the real .so.

Usage

# Isolate a library
isolate-elf isolate libzstd.so.1 --prefix rocm_ --name zstd -o output/

# Dry-run: see what would be renamed
isolate-elf inspect libzstd.so.1

# Strict mode: treat warnings as errors
isolate-elf isolate libzstd.so.1 --prefix rocm_ --name zstd -o output/ --werror

# Allow specific warning categories
isolate-elf isolate libzstd.so.1 --prefix rocm_ --name zstd -o output/ --werror --allow-object-symbol

Symbol classification

What gets renamed

Only defined, exported symbols (GLOBAL or WEAK bind, DEFAULT or PROTECTED visibility, not UND section) that don't match the CRT/glibc exclusion list.

What does NOT get renamed

Undefined imports — symbols the library expects the linker to resolve from other DSOs. These include:

  • Standard libc imports (malloc, printf, dlopen, etc.)
  • Weak undefined hooks — symbols like ZSTD_trace_compress_begin that libraries declare as optional callbacks. These are intentionally left as external binding points:
    • If nobody provides them, they resolve to NULL (weak semantics)
    • If a consumer provides them, they bind in as designed
    • Renaming them would break the hook mechanism entirely
    • The -Bsymbolic flag (applied by TheRock) ensures the library's own defined symbols still resolve internally — these weak imports are the only deliberate opening

CRT/glibc symbols — even if a library re-exports malloc (common for allocator wrappers), we don't rename it. The CRT exclusion list covers ~150 common libc/pthread/math symbols plus glob patterns for __cxa_*, __gcc_*, etc.

Warning categories

Category Trigger Behavior
object-symbol OBJECT (global data) in exports Renamed in .so, excluded from trampolines (can't trampoline data)
tls-symbol TLS symbol in exports Renamed in .so, excluded from trampolines
ifunc-symbol GNU_IFUNC in exports Trampolined via PLT (works but less tested)
versioned-symbol Non-AMDROCM version tag Renamed, version tag preserved
weak-override WEAK symbol shadowing glibc name Excluded from renaming

Use --werror to make all warnings fatal, --allow-<category> to selectively permit specific categories.

ELF rewriting internals

objcopy --redefine-syms does not modify .dynsym (only .symtab), so isolate-elf includes its own ELF binary rewriter (elf_rewrite.py) that:

  1. Builds a new .dynstr with renamed strings appended
  2. Updates .dynsym st_name offsets
  3. Rewrites DT_SONAME to match the output filename
  4. Adds a new PT_LOAD segment for the grown .dynstr
  5. Relocates the PHDR table if needed (borrowed from kpack patterns)
  6. Rebuilds .gnu.hash and .hash tables with new name hashes
  7. Updates DT_STRTAB/DT_STRSZ in .dynamic

Testing

# Unit tests (synthetic test libraries)
pytest tests/

# Integration tests (real sysdep libraries from TheRock S3 mirror)
pytest integration/

# All tests
pytest tests/ integration/

# Dump before/after artifacts for manual inspection
pytest integration/ --dump-artifacts=/tmp/isolate-elf-dump

Integration tests download real sysdep sources, build them, isolate, then verify: symbol correctness (readelf), autoconf link simulation, negative link test, and runtime isolation via LD_DEBUG=bindings scraping.

Metadata

Release files for isolate-elf 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for isolate-elf 0.2.0
File Size Uploaded Provenance Actions
isolate_elf-0.2.0.tar.gz 27.7 kB With provenance Details for isolate_elf-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for isolate-elf 0.2.0
File Interpreter ABI Platform Actions
isolate_elf-0.2.0-py3-none-any.whl Python 3 none any Details for isolate_elf-0.2.0-py3-none-any.whl

Total release size: 54.5 kB

Release files / isolate_elf-0.2.0.tar.gz

Download URL isolate_elf-0.2.0.tar.gz
Size 27.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c7ed05a4c4ee0adb5e5041ee0184dfdbab417771368b706bfd9b24be79d11d19
BLAKE2b-256 checksum
How to use checksums
3f4b6cb56df9c72aa8a7456eb069d7130907d09a1a3996ad2e760e193448b122
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.

Transparency log

Release files / isolate_elf-0.2.0-py3-none-any.whl

Download URL isolate_elf-0.2.0-py3-none-any.whl
Size 26.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a5b18ce1bbaa69426d1a88497cd97a6573bdca2a6f96c7b9e45a4eff2a909995
BLAKE2b-256 checksum
How to use checksums
d7292a8508cc8fad2e77efe72bbc1eaefd339b4a0099faf38afe2edfb0d7bd8a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.

Transparency log

Security for isolate-elf 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for isolate_elf-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page