Skip to content

evidence-schema.md

Latest commit

 

History

History
97 lines (83 loc) · 6.87 KB

evidence-schema.md

File metadata and controls

97 lines (83 loc) · 6.87 KB
Raw

bpfcompat evidence schema (v0.1)

The compatibility report is bpfcompat's core artifact: a portable, machine-readable record of whether a compiled eBPF object loads (and attaches) on each target kernel, with a classified reason when it does not. The classification taxonomy and this stable format — not the VM layer — are what make the evidence reusable across CI, dashboards, and audits.

Top level

Field Type Notes
schema_version string Always present. Gate on this.
run object { id, started_at }
artifact object { path, source?, source_digest?, basename, sha256, size_bytes } — the validated .bpf.o or synthetic command identity; source preserves the original OCI reference and source_digest the immutable image digest it resolved to
command object, optional Command-mode invocation digest, expected exit code, and optional loader binary name/size/SHA-256. Command text is not persisted.
validator object, optional Artifact-mode libbpf validator binary name, size, and SHA-256. The staged bytes are reused for every target.
matrix object { path, name?, profiles[] } — the kernel set requested
targets[] array one entry per kernel profile (below)
summary object { status, verdict?, complete?, notes[]? } — status is pass/fail/error; verdict is COMPATIBLE/INCOMPATIBLE/INFRA_ERROR; complete: false means at least one target produced no compatibility answer
paths object { run_dir, json, markdown? }

targets[] — per-kernel result

Field Type Notes
profile_id string e.g. ubuntu-22.04-5.15
required bool whether this target gates the run. Only required targets set the run verdict and exit code — for any outcome, including infrastructure failure and an environment mismatch. Optional targets report information and reduce summary.complete, never the gate
status string pass | fail | partial | infra_error | unsupported
verdict enum COMPATIBLE | INCOMPATIBLE | INFRA_ERROR | UNSUPPORTED — see compatibility-contract.md
environment object { requested_kernel_family, observed_kernel, kernel_family_match, image_source_url, image_sha256 } — kernel_family_match: false means this target ran a different kernel series than the profile requested and cannot support a claim about it
profile / host object { distro, version, kernel_family, kernel, arch } (requested vs actual)
validation object { load_status, load_error_code, load_error, attach_mode, attach_status, attach_attempted, attach_passed, attach_failed }
functional object optional behavior tests: { status, tests[] }
btf object { kernel_btf_available, artifact_has_btf, artifact_has_btf_ext }
failed_stage string load | attach | functional | command | transport | infra
classification_code enum why it failed — see taxonomy below
classification_confidence string high | medium | low
classification_reason string human-readable explanation
started_at / finished_at / duration_ms — timing
validator_exit / notes[] — validator detail

Sanitized (public) reports omit host internals

When BPFCOMPAT_API_REDACT_RUNTIME_DETAILS is set (the public demo posture), the server strips host-revealing fields before returning a report: vm_run_dir, qemu_command, serial_log, validator_result, and any absolute audit paths. Self-hosted runs (your own CI, the CLI) keep the full detail locally.

Classification taxonomy

The stable set of classification_code values, each with the remediation bpfcompat suggests. This is the part that turns a raw libbpf/verifier error into an actionable cause — and the part that compounds in value as more real-world failures are catalogued.

Code Meaning Typical remediation
MISSING_BTF Kernel has no embedded BTF for CO-RE Non-CO-RE fallback, external BTF (BTFHub), or drop the CO-RE dependency for that band
CORE_RELOCATION_FAILURE A CO-RE relocation could not be applied Validate against the target BTF layout; ship a profile-specific variant where field layouts diverge
UNSUPPORTED_PROGRAM_TYPE Program type not available on this kernel Older-kernel-compatible variant (e.g. avoid fentry/fexit before 5.5)
UNSUPPORTED_MAP_TYPE Map type not available (e.g. ringbuf < 5.8) Map-compatible fallback (e.g. perfbuf instead of ringbuf)
UNSUPPORTED_ATTACH_TYPE Attach/hook not available Change the hook strategy, or make attach optional in the manifest
POLICY_DENIED Host policy blocked load/attach Check kernel lockdown, unprivileged-BPF sysctl, capabilities, runner policy
CAPABILITY_FAILURE A probed helper/map/prog capability failed Compare against the target profile; select a compatible variant
VERIFIER_REJECTION The verifier rejected the program Inspect the validator/libbpf log in the report
FUNCTIONAL_TEST_FAILURE Loaded, but a behavior test failed Inspect the functional command output / project test assets
COMMAND_VALIDATION_FAILURE Command mode: the project's own loader exited with an unexpected code Inspect functional.tests[].stderr_tail; the shipped loader failed on this kernel
UNSUPPORTED_TRANSPORT bpfcompat has no execution transport for this profile — not a statement about the artifact (verdict: UNSUPPORTED) Route the profile to a supported executor, or mark it optional

Consumers should treat unknown codes as a generic failure (forward-compatible).

Minimal example

{
  "schema_version": "v0.1",
  "run": { "id": "20260611T194515Z-33a59b", "started_at": "2026-06-11T19:46:48Z" },
  "artifact": { "basename": "bpf_probe.o", "sha256": "4895…2722", "size_bytes": 1127120 },
  "matrix": { "name": "falco-modern-bpf-proof", "profiles": ["ubuntu-20.04-5.4", "ubuntu-24.04-6.8"] },
  "summary": { "status": "pass" },
  "targets": [
    { "profile_id": "ubuntu-24.04-6.8", "required": true, "status": "pass",
      "btf": { "kernel_btf_available": true } },
    { "profile_id": "ubuntu-20.04-5.4", "required": false, "status": "fail",
      "failed_stage": "load", "classification_code": "UNSUPPORTED_MAP_TYPE",
      "classification_confidence": "high",
      "classification_reason": "map ringbuf_maps failed to create (-22); ring buffer requires kernel >= 5.8" }
  ]
}