HostContract

Evidence-backed OCI host requirement synthesizer.

HostContract answers: which host capabilities are actually necessary for this workload, versus merely observed?

The default policy promotes a capability to a hard requirement only when controlled withholding demonstrates that the workload fails without it.

Quick start

Python 3.10+. No Python runtime dependencies. readelf is optional but used by the included demo.

python -m pip install https://github.com/virajsabhaya23/hostcontract/releases/download/v0.2.0/hostcontract-0.2.0-py3-none-any.whl

gcc -O2 -o demo/probe demo/probe.c
python -m hostcontract synthesize \
  --workload demo-image \
  --static examples/static.json \
  --dynamic examples/dynamic.json \
  --experiments examples/experiments.json \
  --coverage examples/coverage.json \
  --elf demo/probe \
  --out out/contract.json \
  --nfd-out out/nfd-compat.yaml

Validate:

python -m hostcontract validate out/contract.json examples/good-host.json
python -m hostcontract validate out/contract.json examples/bad-host.json

The bad host exits 2.

Benchmark:

python -m hostcontract benchmark benchmark/corpus.json --out benchmark/results.json

Implemented: static/dynamic evidence ingestion, real ELF/GLIBC inspection with readelf, counterfactual necessity evidence, CPU/syscall/kernel/glibc/device/module/capability modeling, confidence/provenance, coverage-qualified certificates, host-profile capture, known-good/known-bad validation, NFD v1alpha1 YAML generation, and a 30-case static-vs-dynamic-vs-fused benchmark.

Limitations: strace is not bundled in this runtime, so the example imports deterministic syscall observations. GPU/module benchmark cases are controlled host-profile fixtures. NFD has no native matcher for every synthesized feature class; those are preserved under a documented custom feature namespace.