Skip to main content
View Markdown ↗

Copy this page

Select and copy the Markdown below, then paste it into your LLM.

On this page

High-assurance attestation (zero-drop mode)

For release builds where "the attestation is complete or it doesn't ship," CI/lock supports a zero-drop capture mode that combines kernel-synchronous file hashing (fanotify), opportunistic Merkle-root sealing (fs-verity), and a fail-closed verification gate. This page documents the flag matrix and what each guarantee means.

Quick start (release-grade)

cilock-action has no inputs for --capture-mode or --require-zero-drops, refuses cilock-args, and does not run CI/lock under sudo, so fanotify cannot get the capability it needs there. Run the cilock CLI directly in a run: step instead. Hosted GitHub Actions runners allow passwordless sudo:

- name: build (release-grade)
  env:
    CILOCK_FANOTIFY: "1"          # require synchronous file capture
    CILOCK_FSVERITY: "auto"       # opportunistic Merkle seal on products
    CILOCK_PLATFORM_URL: ${{ vars.CILOCK_PLATFORM_URL }}
  run: |
    # --capture-mode trace:ebpf requires the eBPF backend (fails loudly if unavailable);
    # --require-zero-drops rejects the attestation if any hard drop occurred.
    # material, product and command-run always run; list only the others.
    # -E keeps the GITHUB_* and ACTIONS_ID_TOKEN_* variables the attestors and keyless signing read.
    sudo -E \
      "$(command -v cilock)" run --step build --trace \
      --capture-mode trace:ebpf --require-zero-drops \
      -a environment,git,github,sbom \
      --platform-url "$CILOCK_PLATFORM_URL" \
      -o "$RUNNER_TEMP/build.json" -- ./build.sh

The build will run measurably slower (a typical 60% overhead on small workloads, less on builds dominated by compile time). In exchange you get:

  • Zero silent drops on file content. Every open() under the workspace mount is hashed synchronously by the kernel-blocking fanotify handler.
  • Kernel-rooted product digests when fs-verity is available on the filesystem. The kernel refuses to read corrupted blocks downstream.
  • Fail-closed verification: if any hard drop, fanotify timeout, queue overflow, digest-cap hit or fs-verity seal failure occurred by end-of-trace, the attestation is rejected with a structured error. Unhashed opens are recorded per file, not gated.
  • Tracee privilege drop — the build process runs as the invoker's user (via SUDO_UID), not root, even though CI/lock retains the capabilities it needs for kernel observation.

Environment flag matrix

CILOCK_FANOTIFY

valuebehavior
`` (unset) / autoProbe for fanotify; activate if the probe succeeds. Otherwise continue without it, print a warning, and record the gap as summary.coverage kind fanotify-unavailable. --hardening standard (the default) sets this.
0 / offDisabled (recorded as coverage gap fanotify-disabled). --hardening off sets this.
1 / onREQUIRE fanotify. Error if probe fails (e.g., CAP_SYS_ADMIN missing). --hardening strict sets this.

Capabilities: CAP_SYS_ADMIN required. cilock-action does not run CI/lock under sudo and does not provide it. Run the cilock CLI under sudo, as in the quick start; the tracee then drops back to the invoking user through SUDO_UID.

Filesystem support: ext4, xfs, btrfs (most production filesystems). cilock gives the build a mount namespace of its own and puts a FAN_MARK_MOUNT mark on each of that namespace's mounts, never a filesystem mark, so a stalled handler blocks the build and not the host. Entering that namespace needs CAP_SYS_ADMIN and permission to remount / as a slave mount (Docker's default AppArmor profile denies it), and leaving it needs CAP_SYS_CHROOT as well.

Coverage limits: see Known gaps below.

CILOCK_FSVERITY

valuebehavior
`` (unset) / 0 / offDisabled.
autoProbe FS at startup; opportunistically seal each product on close.
1 / onREQUIRE fs-verity availability. Error if FS doesn't support it.

Filesystem support: ext4 with the verity feature flag enabled at mkfs time (rare on hosted CI; common on Android, ChromeOS, some private k8s clusters). Probe gracefully returns EOPNOTSUPP otherwise.

--require-zero-drops (CLI flag) / WithRequireZeroDrops() (API)

When set, the attestor returns a ZeroDropsError instead of emitting the attestation if any of the following counters in summary.diagnostics is non-zero at end-of-trace:

countermeaning
ringbufOpenatDropsBPF ringbuf dropped openat events
ringbufReadTapDropsBPF ringbuf dropped read-tap chunks
ptraceSyscallStopsLostptrace syscall stops whose registers could not be read
fanotifyTimeoutsHandler took longer than 2s; kernel default-allowed
fanotifyQueueOverflowsKernel emitted FAN_Q_OVERFLOW
fanotifyDigestsCapHitPer-trace 200K digest cap reached
fsVeritySealFailuresKernel ioctl returned error

unhashedOpensTotal and fallbackHashFailures are recorded but not gated: each unhashed open is listed with its path and reason, so a verifier policy can decide on it. partialReadFallbacks is not counted either, because the openat-time path hash stays authoritative. Gate on the soft counters in Rego if your release needs them at zero.

Diagnostic surface

Every trace populates summary.diagnostics with these fields. Use them in Rego policies, dashboards, or alerts:

{
  "summary": {
    "diagnostics": {
      "fanotifyAvailable": true,
      "fanotifyEventsHashed": 2004,
      "fanotifyDigestsMerged": 198,
      "fanotifyTimeouts": 0,
      "fanotifyQueueOverflows": 0,
      "fanotifyDigestsCapHit": 0,
      "fsVerityAvailable": false,
      "fsVerityFilesSealed": 0,
      "fsVeritySealFailures": 0,
      "ringbufOpenatDrops": 0,
      "ringbufReadTapDrops": 0,
      "unhashedOpensTotal": 0,
      "fallbackHashFailures": 0
    },
    "fanotifyOnlyDigests": {
      "/usr/lib/ld-linux-x86-64.so.2": "ab12cd34..."
    }
  }
}

fanotifyOnlyDigests is the kernel-rooted digest for paths fanotify hashed where no tracee process recorded an open — represents BPF-missed events that fanotify still caught.

Each SyscallEvent carries a digestSource field tagging the provenance per event:

sourcetrust level
fanotify-open-timeKernel-synchronous hash; race-tight at open time
openat-path-hashHashed via /proc/<pid>/fd at openat time; small race window
collector-open-path-hashmacOS: hashed from the path when the collector opened it, not from the bytes the build read
fanotify-onlyLook up in summary.fanotifyOnlyDigests
`` (empty)No digest captured (mmap-read with no prior hash; zero-copy syscall)

A step's rego policy receives the command-run attestation itself as input, so the trace summary is input.summary (not input.predicate.summary). The verifier evaluates each module's deny rule and refuses a module that has none. These snippets are evaluated against real command-run attestations by cilock/cli/guide_rego_examples_test.go, so a change here that stops them firing fails that test.

package cilock.fanotify

deny[msg] {
  not input.summary.diagnostics.fanotifyAvailable
  msg := "release-grade attestation requires fanotify (CILOCK_FANOTIFY=1); the trace does not record it as active"
}

deny[msg] {
  timeouts := object.get(input.summary.diagnostics, "fanotifyTimeouts", 0)
  timeouts > 0
  msg := sprintf("fanotify handler timeouts > 0 (got %d): degraded attestation", [timeouts])
}

deny[msg] {
  drops := object.get(input.summary.diagnostics, "ringbufReadTapDrops", 0)
  drops > 0
  msg := sprintf("BPF read-tap drops > 0 (got %d)", [drops])
}

Read each field from input inside the negation, as above. Binding diagnostics := input.summary.diagnostics first and then testing not diagnostics.fanotifyAvailable fails OPEN: when diagnostics is absent the binding is undefined, the rule body stops there, and nothing is denied. Counters the attestor omits when they are zero are read with object.get and a default: the verifier refuses a policy whose deny reads a field the attestation does not carry, because such a deny can never fire.

Requiring trace coverage: summary.coverage

Every traced command-run predicate carries summary.coverage. It holds the tracer that ran (ebpf, ptrace+seccomp, or sandbox-exec+oslog on macOS), one gaps[] entry for each known blind spot, each with a stable kind, and dimensions: whether the trace saw every file read and written (files), every process and its argv (exec), every way the build reached the network (network), and a write behind every product (products).

Do not require coverage.complete. It is true only when there are no gaps at all, and every Linux trace carries network-paths-unobserved: neither Linux tracer records every network path (the eBPF tracer has no accept or receive probe; the ptrace tracer claims no network path). A rule on complete therefore refuses every Linux trace, however privileged. macOS traces are never complete either. Require the dimensions your decision depends on instead. For "which files did this build read, and which programs did it run", that is files and exec; cilock running as root with eBPF and fanotify active produces both complete. The ptrace tracer never does: its syscalls-untraced gap marks every dimension incomplete. A predicate from an older cilock has no coverage, so the rule below refuses it as well:

package cilock.trace_files_exec

deny[msg] {
  not input.summary.coverage.dimensions.files.complete
  msg := "trace does not claim complete file coverage, or records no coverage"
}

deny[msg] {
  not input.summary.coverage.dimensions.exec.complete
  msg := "trace does not claim complete exec coverage, or records no coverage"
}

To accept specific known limits instead, allow the named gap kinds and deny every other kind. Denying unknown kinds means a gap kind added later is refused until someone reviews it. The accepted set below admits the two gaps that cilock running as root with eBPF and fanotify still records on every Linux trace: network-paths-unobserved, and products-outsider-unguarded (nothing in a trace rules out a process outside it writing a product after the build's last write). Drop the second if your policy relies on products being bound to the build's writes; it then refuses every Linux trace until cilock can prove that. Iterating gaps finds nothing to deny when coverage is absent or states no gaps, so those cases need rules of their own. object.get supplies the optional fields, because a message built from an undefined field is itself undefined and would silently drop the denial:

package cilock.trace_gaps

accepted_gaps := {"network-paths-unobserved", "products-outsider-unguarded"}

deny[msg] {
  not input.summary.coverage
  msg := "trace states no coverage (untraced, or produced by an older cilock)"
}

deny[msg] {
  input.summary.coverage.complete != true
  count(object.get(input.summary.coverage, "gaps", [])) == 0
  msg := "trace is incomplete but names no gaps"
}

deny[msg] {
  gap := object.get(input.summary.coverage, "gaps", [])[_]
  kind := object.get(gap, "kind", "")
  not accepted_gaps[kind]
  msg := sprintf("trace gap %q: %s", [kind, object.get(gap, "detail", "")])
}

Known gaps

These are documented in the trace metadata; verifier policy decides whether to accept attestations with them:

  1. mmap-read content — when a tracee opens a file then reads via page faults (JVM classpath, ld.so loader, memory-mapped DBs), fanotify hashes at open time. If the file mutates between open and the page fault, the digest is stale. The SyscallEvent for mmap surfaces the file path so verifiers can policy on it.
  2. Zero-copy syscalls — copy_file_range, splice, sendfile transfer bytes kernel-side without firing fanotify or read-tap. The SyscallEvent records source + destination paths but no content digest.
  3. memfd_create / O_PATH opens — no path to mark; not captured.
  4. Opens fanotify does not hold — fanotify marks every mount of the build's own mount namespace, so system libraries are covered too. Where fanotify is not running, a file's digest is hashed from its path when the tracer sees the open (the fanotify-unavailable or fanotify-disabled coverage gap), and a file rewritten in between can be recorded with the wrong digest.

Cost profile

Measured on a synthetic 200-file burst on Ubuntu 24.04 GHA runner:

modehash completenessoverhead vs baseline
BPF-only86-99% (with ~1% wrong-digest cases)baseline
BPF + fanotify100%~60% on small workloads; less on compile-heavy

The overhead amortizes on builds dominated by compute time. For a typical Go monorepo build (~10s baseline), expect ~16s with fanotify. For a kernel make -j$(nproc) build (~10 min baseline), expect ~12 min — the per-open overhead is dwarfed by compile time.

When NOT to enable fanotify

  • Builds with extreme file open rates where the synchronous block overhead is unacceptable (e.g., Bazel's per-action sandbox setup that opens 100K+ files per action).
  • Filesystems that reject FAN_MARK_FILESYSTEM AND FAN_MARK_MOUNT (rare; FUSE-mounted volumes).
  • Environments without CAP_SYS_ADMIN (most non-sudo container workloads).

In these cases use the BPF-only path (default) and accept the ~1-4% drop rate. Surface summary.diagnostics.ringbufReadTapDrops in your CI dashboard so you know when it's degrading.

Reference generated from the product documentation. Match commands and support details to your installed release.