# High-assurance attestation (zero-drop mode)

Source: https://www.testifysec.com/docs/cilock/guides/high-assurance-attestation/

For release builds where "the attestation is complete or it doesn't ship,"

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`:

 

```yaml
- 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`

 

| value | behavior |
| --- | --- |
| \`\` (unset) / `auto` | Probe 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` / `off` | Disabled (recorded as coverage gap `fanotify-disabled`). `--hardening off` sets this. |
| `1` / `on` | REQUIRE 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](https://www.testifysec.com/docs/cilock/guides/high-assurance-attestation/#known-gaps) below.

 

### `CILOCK_FSVERITY`

 

| value | behavior |
| --- | --- |
| \`\` (unset) / `0` / `off` | Disabled. |
| `auto` | Probe FS at startup; opportunistically seal each product on close. |
| `1` / `on` | REQUIRE 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:

 

| counter | meaning |
| --- | --- |
| `ringbufOpenatDrops` | BPF ringbuf dropped openat events |
| `ringbufReadTapDrops` | BPF ringbuf dropped read-tap chunks |
| `ptraceSyscallStopsLost` | ptrace syscall stops whose registers could not be read |
| `fanotifyTimeouts` | Handler took longer than 2s; kernel default-allowed |
| `fanotifyQueueOverflows` | Kernel emitted FAN\_Q\_OVERFLOW |
| `fanotifyDigestsCapHit` | Per-trace 200K digest cap reached |
| `fsVeritySealFailures` | Kernel 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:

 

```json
{
  "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:

 

| source | trust level |
| --- | --- |
| `fanotify-open-time` | Kernel-synchronous hash; race-tight at open time |
| `openat-path-hash` | Hashed via `/proc/<pid>/fd` at openat time; small race window |
| `collector-open-path-hash` | macOS: hashed from the path when the collector opened it, not from the bytes the build read |
| `fanotify-only` | Look up in `summary.fanotifyOnlyDigests` |
| \`\` (empty) | No digest captured (mmap-read with no prior hash; zero-copy syscall) |

 

## Recommended policy.rego snippet

 

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.

 

```rego
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:

 

```rego
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:

 

```rego
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:

 

| mode | hash completeness | overhead vs baseline |
| --- | --- | --- |
| BPF-only | 86-99% (with ~1% wrong-digest cases) | baseline |
| BPF + fanotify | **100%** | ~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.
