Skip to content

About

Regression testing for actual ELF symbol bindings in controlled Linux/glibc workloads, with explicit provider contracts and runtime evidence.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

BindWitness: a verified symbol binding to a shared library

BindWitness

CI Go version License: Apache-2.0 Capture: Linux / glibc

Verify which shared object actually provides your native symbols.

BindWitness is a small CLI for regression testing selected ELF symbol bindings in a trusted smoke workload. It runs the real glibc loader, records LD_DEBUG=bindings,files diagnostics, and checks an explicit JSON contract. Use it when changing native dependencies, plugin loading order, or a Python native extension's environment. A smoke test can produce the same output while binding to the wrong library; BindWitness checks the provider itself.

The CLI uses only the Go standard library. A C compiler is needed for the included test fixtures, not for running the CLI.

Supported environments

Native capture supports Linux AMD64 and ARM64, each with glibc 2.36 and 2.41. The v0.1.1 release validation passed all four combinations in pinned Debian Bookworm and Trixie userspaces. See the validation guide for environments and commands. Other architecture/glibc combinations return UNRESOLVED; offline check and compare use the saved platform provenance and remain portable, including on macOS ARM64.

An Ubuntu 24.04 runner executes the workload inside the pinned Debian container. This validates that Debian userspace, not native Ubuntu's different glibc version.

The capture scope is one process in the base linker namespace, with immutable artifacts and no unload/reload cycles. Use absolute paths for selected shared objects: the loader's relative DSO names do not establish which working directory was used to load them. The executable's original argv[0] is preserved and can be relative. See capture limitations.

Native capture on macOS, Windows, musl, Mach-O and PE is unsupported. BindWitness does not perform general ABI analysis or predict unexecuted paths.

Quick start

Download the Linux AMD64 or ARM64 archive and SHA256SUMS from GitHub Releases. Verify the archive's checksum before extracting. Archives contain the CLI, license and documentation; examples and validation workloads are in the source checkout.

Clone the repository and build with Go 1.25 or newer:

git clone https://github.com/0then0/bindwitness.git
cd bindwitness
mkdir -p build
CGO_ENABLED=0 go build -trimpath -o build/bindwitness ./cmd/bindwitness

On supported Linux, build the demonstration with GCC or Clang and check it:

sh scripts/build-fixtures.sh
./build/bindwitness check --config examples/native.json --report build/check.json

Expected result: PASS, exit 0. Two plugins export shared_value, and the consumer must bind to logical object a. The fixture host resolves its library arguments to absolute paths before loading them.

Run the full demonstration:

python3 scripts/native-validation.py build/bindwitness build/demo

Reversing plugin order still prints result=12, but produces FAIL with the binding to b as its witness. The script also checks missing coverage, saved observations and comparison; it exits 0 when all expected outcomes are obtained.

For your application, start from examples/native.json and follow the configuration guide. Run a dynamic ELF executable directly; for a script, explicitly name its ELF interpreter.

Commands

Every operation requires --config and --report. The report directory must already exist.

# Save evidence. This does not enforce the binding contract.
./build/bindwitness capture --config examples/native.json --report build/capture.json

# Capture and check the selected bindings.
./build/bindwitness check --config examples/native.json --report build/check.json

# Check saved evidence without executing the workload or reading its artifacts.
./build/bindwitness check --config examples/native.json \
  --observation build/capture.json --report build/offline.json

# Compare two observations using explicit logical object mappings.
./build/bindwitness compare --config examples/compare.json \
  --left build/demo/native-positive.json --right build/demo/native-mismatch.json \
  --report build/compare.json

A saved check report can also be passed to --observation, --left or --right. Compare uses exact reference, symbol and trace version. It distinguishes a provider change from a rebuild of the same logical provider and from missing observations. See comparison configuration.

CI outcomes

  • 0 / PASS: required bindings were observed and met the contract with sufficient, supported evidence. For capture, this means capture conditions held; the contract has not been checked.
  • 1 / FAIL: a concrete provider change, disallowed provider or exact artifact pin mismatch was observed.
  • 2 / UNRESOLVED: coverage or evidence is insufficient, including truncation, ambiguous identity, unsupported scope, deadline or cancellation.
  • 3 / INFRASTRUCTURE_ERROR: invalid input, unsupported report version, launch failure, harness error or failure to save the mandatory report.

A valid violation remains FAIL even if later diagnostics are incomplete. The report retains both findings. A normal nonzero workload exit code is recorded separately; CI can also gate on observation.workload.exit_code.

Missing observations are not provider-change witnesses. In compare, unequal provider sets sharing a provider indicate unmatched coverage and return UNRESOLVED. A successful comparison describes the declared observed scope, not complete program equivalence.

Evidence

Reports include bounded raw trace lines, binding events, file identities and provenance. Every event retains the loader's reference/provider names, raw symbol, trace version, namespace IDs and its source line. The terminal shows the first actionable witness; JSON preserves the full evidence.

Identity includes resolved path, SHA-256, ELF class/machine, and SONAME/build ID when available. Objects are never merged solely by basename, SONAME or hash. Pre/post checks detect available signs of artifact changes. Hashes describe files read from disk; they do not prove mapped bytes or detect every change followed by restoration. Workloads and saved reports are trusted developer inputs.

See report format and limitations and the versioned contract, comparison and report schemas.

Testing and releases

The validation guide explains Linux containers, race and fuzz checks, installed/release binaries, real CPython/zlib validation and release packaging. GitHub Actions uses the same scripts.

The Perl bundled/system zlib case study uses real Compress::Raw::Zlib releases to demonstrate provider sensitivity to global load order and the upstream prefix fix. The workloads produce identical successful application output across different binding verdicts, with saved offline evidence, coverage controls and checks for failed library loads. This is an integration case rather than an exact reproduction of the published upstream failure.

The AMD64 GitHub Actions example downloads the release binary, verifies its checksum and checks the native demo's explicit required provider contract in Debian Bookworm. Copy it into .github/workflows/ to run the published v0.1.2 demonstration. It preserves the report on success or failure and gates CI on the BindWitness exit code.

testdata is part of the test suite: it contains C source fixtures, real loader traces and representative reports with provenance. Keep it in source checkouts. Generated binaries and new validation runs belong in ignored build/ and dist/ directories.

Related tools

Runtime binding analysis has existed for decades. BindWitness provides a small contract workflow for selected bindings of an actual workload.

  • libtree explains dependency trees and library resolution.
  • Libabigail abicompat checks ABI compatibility, including information beyond runtime bindings.
  • abicheck deps examines dependency resolution and compares dependency stacks.
  • ldaudit-yaml captures loader audit events; latrace traces library calls through the audit interface.
  • Solaris lari analyzes runtime interfaces and saved linker bindings.
  • MONDO monitors dynamic linking using loader traces and a graphical interface.

BindWitness uses ordinary glibc diagnostics, with no custom loader or LD_AUDIT module. Binding events are not call counts, call stacks, proven dlsym callers or final IFUNC execution addresses.

Motivation

LLVM/LLDB PR #204710 discusses ELF interposition involving duplicated HostInfoBase code. ROCm/AITER issue #4585 describes HIP symbols resolving to an earlier global TileLang stub. Compress::Raw::Zlib issue #8 and PR #11 discuss zlib symbol collisions and prefixed bundled exports. These are upstream motivations; the included fixtures do not claim to reproduce those bugs.

Contributing and project policies

See CONTRIBUTING.md for development setup, validation commands and pull request guidance. Report reproducible bugs and propose improvements through the issue templates. Participation follows the code of conduct.

Report vulnerabilities privately using SECURITY.md. The changelog summarizes released changes; detailed release notes are in docs/releases.

License

Apache License 2.0.

About

Regression testing for actual ELF symbol bindings in controlled Linux/glibc workloads, with explicit provider contracts and runtime evidence.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages