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.
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.
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/bindwitnessOn 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.jsonExpected 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/demoReversing 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.
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.jsonA 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.
- 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.
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.
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.
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.
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.
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.