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:
- Prefixed .so — all exported symbols renamed (
ZSTD_decompress→rocm_ZSTD_decompress) via direct ELF binary rewriting of.dynsym/.dynstr+ hash table rebuild - Trampoline .a — asm stubs exporting original names, tail-jumping to prefixed names via PLT
- Linker script —
INPUT(stubs.a AS_NEEDED(real.so.1))installed as-lzstd - Redirect header —
#definemacros 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_beginthat 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
-Bsymbolicflag (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:
- Builds a new
.dynstrwith renamed strings appended - Updates
.dynsymst_nameoffsets - Rewrites
DT_SONAMEto match the output filename - Adds a new
PT_LOADsegment for the grown.dynstr - Relocates the PHDR table if needed (borrowed from kpack patterns)
- Rebuilds
.gnu.hashand.hashtables with new name hashes - Updates
DT_STRTAB/DT_STRSZin.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.