feat(build): Gate the Linux port with full CI and document its runtime contract

.github/workflows/linux-port.yml

@@ -12,6 +12,8 @@ concurrency:
 
 env:
   GO_VERSION: 1.26.x
+  GOLANGCI_LINT_VERSION: v2.9.0
+  CLANG_VERSION: 18
 
 jobs:
   ebpf:
@@ -28,22 +30,37 @@ jobs:
         uses: actions/setup-go@v5
         with:
           go-version: ${{ env.GO_VERSION }}
+      # Deliberately before clang is installed: a checkout must build from the
+      # committed objects alone.
+      - name: Build without generation tools
+        run: make
       - name: Install clang
         run: |
           sudo apt-get update
-          sudo apt-get install -y clang llvm
-          clang --version
+          sudo apt-get install -y clang-${{ env.CLANG_VERSION }} llvm-${{ env.CLANG_VERSION }}
+          clang-${{ env.CLANG_VERSION }} --version
+      # The versioned packages ship no unversioned symlinks, so name both tools.
       - name: Check generation drift
+        run: make ebpf-drift CLANG=clang-${{ env.CLANG_VERSION }} LLVM_STRIP=llvm-strip-${{ env.CLANG_VERSION }}
+      - name: Install golangci-lint
         run: |
-          make -B ebpf
-          git diff --exit-code -- internal/ebpf/bpf
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin ${{ env.GOLANGCI_LINT_VERSION }}
+      - name: Lint
+        run: |
+          export PATH=$(go env GOPATH)/bin:$PATH
+          make lint
       - name: Unit tests
         run: make test
+      - name: Race tests
+        run: make test-race
       - name: Validate rules
         run: |
-          make build
           ./cmd/fibratus/fibratus rules validate \
             --filters.rules.from-paths="rules/linux/*.yml" \
             --filters.macros.from-paths="rules/linux/macros/*.yml"
+      # Fails, rather than skips, when the runner cannot host the backend, so a
+      # green integration run always means programs actually loaded.
+      - name: Probe eBPF prerequisites
+        run: sudo -E env "PATH=$PATH" go test -tags ebpf_integration -count=1 -run TestPrerequisitesAreMet -v ./internal/ebpf
       - name: Privileged process source
-        run: sudo -E env "PATH=$PATH" go test -tags ebpf_integration -count=1 ./internal/ebpf
+        run: sudo -E env "PATH=$PATH" make test-integration

Makefile

@@ -4,6 +4,15 @@ SHELL := /bin/bash
 .SHELLFLAGS := -euo pipefail -c
 
 BPF2GO_VERSION := v0.20.0
+GOLANGCI_LINT_VERSION := v2.9.0
+
+# The committed objects are byte-compared in CI, and clang encodes its version
+# into BTF, so generating with a different major produces a spurious diff.
+CLANG_VERSION := 18
+
+# The generated objects target x86-64 and the runtime refuses other
+# architectures, so building the binary pins the same one.
+TARGET_ARCH ?= amd64
 
 # Specifies a list of build flags
 TAGS ?=
@@ -12,6 +21,7 @@ BPF_DIR := internal/ebpf
 BPF_OUT := $(BPF_DIR)/bpf
 
 CLANG ?= clang
+LLVM_STRIP ?= llvm-strip
 GO ?= go
 GOFMT ?= gofmt
 BPF2GO ?= go run github.com/cilium/ebpf/cmd/bpf2go@$(BPF2GO_VERSION)
@@ -20,6 +30,7 @@ BPF_FLAGS := \
 	-go-package bpf \
 	-output-dir $(BPF_OUT) \
 	-cc $(CLANG) \
+	-strip $(LLVM_STRIP) \
 	-target bpfel,bpfeb \
 	-tags linux
 
@@ -42,19 +53,48 @@ BPF_TARGETS := $(foreach name,$(BPF_NAMES), \
 titlecase = $(shell printf '%s' '$(1)' | awk '{print toupper(substr($$0,1,1)) substr($$0,2)}')
 
 .PHONY: ebpf
-ebpf: $(BPF_TARGETS)
+ebpf: check-clang $(BPF_TARGETS)
 $(BPF_OUT)/%_bpfel.go $(BPF_OUT)/%_bpfeb.go &: $(BPF_DIR)/c/%.bpf.c
 	$(BPF2GO) $(BPF_FLAGS) -output-stem $* $(call titlecase,$*) $(BPF_DIR)/c/$*.bpf.c -- $(BPF_CFLAGS)
 
+.PHONY: check-clang
+check-clang:
+	@command -v $(CLANG) >/dev/null 2>&1 || { \
+		echo "$(CLANG) not found. Generating the eBPF objects needs clang $(CLANG_VERSION)."; \
+		exit 1; \
+	}
+	@command -v $(LLVM_STRIP) >/dev/null 2>&1 || { \
+		echo "$(LLVM_STRIP) not found. Versioned llvm packages ship llvm-strip-$(CLANG_VERSION)"; \
+		echo "without the unversioned name bpf2go looks for."; \
+		echo "Point LLVM_STRIP at it, e.g. make ebpf LLVM_STRIP=llvm-strip-$(CLANG_VERSION)."; \
+		exit 1; \
+	}
+	@have=$$($(CLANG) --version | sed -n 's/.*clang version \([0-9]*\).*/\1/p' | head -1); \
+	if [ "$$have" != "$(CLANG_VERSION)" ]; then \
+		echo "clang $$have found but the committed objects were generated with $(CLANG_VERSION)."; \
+		echo "Regenerating with another major rewrites every object and fails ebpf-drift."; \
+		echo "Point CLANG at the right binary, e.g. make ebpf CLANG=clang-$(CLANG_VERSION)."; \
+		exit 1; \
+	fi
+
+# Regenerating must be reproducible: same sources and same clang, same bytes.
+.PHONY: ebpf-drift
+ebpf-drift:
+	$(MAKE) -B ebpf
+	git diff --exit-code -- $(BPF_OUT)
+
 ifeq ($(strip $(TAGS)),)
 BUILD_TAGS :=
 else
 BUILD_TAGS := -tags $(TAGS)
 endif
 
+# Builds from the committed objects alone, so a fresh checkout needs no clang
+# and no kernel headers. Naming the target pair keeps this buildable from a
+# developer machine that is neither, which is the cheapest way to prove it.
 .PHONY: build
 build:
-	$(GO) build $(BUILD_TAGS) -o ./cmd/fibratus/fibratus ./cmd/fibratus/
+	GOOS=linux GOARCH=$(TARGET_ARCH) $(GO) build $(BUILD_TAGS) -o ./cmd/fibratus/fibratus ./cmd/fibratus/
 
 .PHONY: fmt
 fmt:
@@ -76,6 +116,28 @@ TEST_PKGS := \
 test:
 	$(GO) test $(TEST_PKGS)
 
+.PHONY: test-race
+test-race:
+	$(GO) test -race $(TEST_PKGS)
+
+# Needs a 5.9+ kernel with runtime BTF, and root to load and attach.
+.PHONY: test-integration
+test-integration:
+	$(GO) test -tags ebpf_integration -count=1 ./internal/ebpf
+
+# Narrower than TEST_PKGS on purpose. Packages outside this set carry helpers
+# that only Windows reaches, so `unused` reports them on every Linux run and
+# there is nothing to fix without moving Windows code around.
+LINT_PKGS := \
+	./internal/ebpf/... \
+	./internal/bootstrap/... \
+	./pkg/filter/... \
+	./pkg/rules/...
+
+.PHONY: lint
+lint:
+	golangci-lint run $(LINT_PKGS)
+
 .PHONY: clean
 clean:
 	rm -f cmd/fibratus/fibratus

docs/_sidebar.md

@@ -2,6 +2,7 @@
   * [Installation](setup/installation.md)
   * [Quick Start](setup/quick-start.md)
   * [Configuration](setup/configuration.md)
+  * [Linux](setup/linux.md)
 * ---
 * [Architecture](architecture.md)
 * ---

docs/setup/linux.md

@@ -0,0 +1,93 @@
+# Linux
+
+On Linux, Fibratus collects telemetry through eBPF CO-RE programs attached to syscall and scheduler tracepoints, instead of ETW. The rule engine, filters, actions, and outputs are the same on both platforms.
+
+## Runtime prerequisites
+
+These are hard requirements. Fibratus probes each one at startup and refuses to run if any is missing, rather than degrading to partial telemetry.
+
+| Requirement | Why |
+| --- | --- |
+| Linux 5.9 or later | BPF task iterators, used to build the initial process tree, appear in 5.9 |
+| Runtime kernel BTF at `/sys/kernel/btf/vmlinux` | CO-RE relocations and `iter/task` attachment resolve against the running kernel's own type information |
+| `x86_64` | The shipped BPF objects are built for this architecture |
+| Ring buffer map support | Events reach userspace through `BPF_MAP_TYPE_RINGBUF` |
+
+There is no BTFHub download and no embedded build-host BTF. A kernel compiled without `CONFIG_DEBUG_INFO_BTF` cannot run the backend, and no amount of configuration works around it. Most distribution kernels from 5.9 onwards enable it; if `/sys/kernel/btf/vmlinux` is absent, the kernel was built without it.
+
+Nothing needs to be compiled at install time. The BPF objects are generated ahead of time and committed, so neither clang nor kernel headers are required on the host.
+
+## Capabilities
+
+Running as root works. To run unprivileged, grant:
+
+| Capability | Needed for |
+| --- | --- |
+| `CAP_BPF` | Loading programs and creating maps |
+| `CAP_PERFMON` | Attaching to tracepoints |
+| `CAP_SYS_PTRACE` | Reading `/proc/<pid>/exe` and `/proc/<pid>/cmdline` of processes owned by other users |
+| `CAP_KILL` | Only if a rule uses the `kill` action against processes you do not own |
+
+`CAP_BPF` and `CAP_PERFMON` were split out of `CAP_SYS_ADMIN` in 5.8. On a kernel that predates the split, or on a distribution that has not adopted it, `CAP_SYS_ADMIN` is the equivalent.
+
+Two environment-specific cases override all of the above. Under kernel lockdown in `confidentiality` mode, loading tracing programs is refused no matter which capabilities you hold; check with `cat /sys/kernel/security/lockdown`. Below 5.11, BPF memory is charged against `RLIMIT_MEMLOCK`, so a low limit causes load failures that read as permission errors; Fibratus raises the limit at startup, which itself needs privilege.
+
+## Reading a failed startup
+
+Fibratus prints the probe result before anything else:
+
+```
+eBPF prerequisites ok: kernel=6.8.0-40-generic btf=/sys/kernel/btf/vmlinux ringbuf=true iter=true
+```
+
+When a prerequisite is missing it refuses to start and names every failure at once, so one run tells you everything that needs fixing:
+
+```
+eBPF prerequisites: kernel 5.4.0-91-generic is below required 5.9; usable kernel BTF required at /sys/kernel/btf/vmlinux
+```
+
+Failures after that line are attachment problems rather than prerequisite problems. `cannot create bpf perf link: permission denied` on an optional tracepoint is expected and harmless: `fork`, `vfork`, and the legacy `open`, `unlink`, and `rename` syscalls are skipped when the kernel refuses a perf link on them, because libc routes through `clone`, `openat`, `unlinkat`, and `renameat` anyway. The same message on a required tracepoint is fatal and means capabilities or lockdown.
+
+## Process enrichment
+
+The initial process tree comes from a single `iter/task` pass over `task_struct`, which is race-free against processes starting during startup. Executable paths and command lines are then filled in best effort from `/proc/<pid>/exe` and `/proc/<pid>/cmdline`.
+
+That second step is allowed to fail. A process that exits between the iterator pass and the procfs read leaves those two fields empty, and Fibratus counts it rather than dropping the process. Enrichment never replaces what the iterator produced, so a failed read cannot corrupt process identity.
+
+## Metrics
+
+Counters are exported as expvars and available through `fibratus stats`.
+
+| Metric | Meaning |
+| --- | --- |
+| `ebpf.events.processed` | Events decoded from the ring buffer |
+| `ebpf.events.excluded` | Events dropped in userspace by config or filters |
+| `ebpf.events.unknown` | Records carrying a type this build does not know |
+| `ebpf.events.parse.errors` | Malformed ring buffer records |
+| `ebpf.ringbuf.drops` | Events the kernel could not queue because the ring buffer was full |
+| `ebpf.approver.drops` | Events rejected in the kernel by an approver, before reaching the ring buffer |
+| `ebpf.enrichment.miss` | Processes whose procfs enrichment failed |
+| `ebpf.startup.pending.queued` | Live events buffered while the baseline scan ran |
+| `ebpf.startup.pending.dropped` | Live events discarded because that buffer was full |
+| `ebpf.startup.replay.applied` | Buffered events replayed once the baseline completed |
+| `ebpf.startup.snapshot.upserts` | Processes recorded by the baseline scan |
+| `ebpf.startup.snapshot.late` | Baseline records that arrived after the switch to live dispatch |
+
+`ebpf.ringbuf.drops` growing steadily is the signal that consumers are not keeping up; it is the one counter worth alerting on. `ebpf.approver.drops` growing is normal and desirable, since it counts work avoided.
+
+## Building from source
+
+Ordinary builds consume the committed objects:
+
+```
+make
+```
+
+Regenerating them needs clang, pinned to the major the committed objects were built with, because clang records its version in BTF and a different major rewrites every object:
+
+```
+make ebpf          # regenerate
+make ebpf-drift    # regenerate and fail if the result differs from what is committed
+```
+
+Other targets: `make test`, `make test-race`, `make lint`, and `make test-integration`, which needs root and a host meeting the prerequisites above.

internal/ebpf/prerequisites_integration_test.go

@@ -0,0 +1,49 @@
+//go:build linux && ebpf_integration
+
+/*
+ * Copyright 2026 by Mostafa Moradian
+ * https://www.fibratus.io
+ * All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package ebpf
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestPrerequisitesAreMet asserts the host satisfies the runtime contract
+// instead of skipping when it does not. A runner that silently loses runtime
+// BTF, or drops below the kernel floor, would otherwise report a green suite
+// that never loaded a program. It runs the same gate Open does, so the arch
+// check is covered too.
+func TestPrerequisitesAreMet(t *testing.T) {
+	report, err := checkRuntimeSupport()
+	if report != nil {
+		t.Logf("kernel=%s (ok=%v, floor=%s) btf=%s (ok=%v) ringbuf=%v ringbuf_helper=%v tracing=%v iter=%v",
+			report.KernelRelease, report.KernelOK, MinKernelVersion,
+			report.BTFPath, report.BTFOK,
+			report.RingbufOK, report.RingbufHelper, report.TracingOK, report.IterOK)
+	}
+	require.NoError(t, err, "host does not meet the Linux eBPF runtime contract")
+	require.NotNil(t, report)
+	require.True(t, report.KernelOK)
+	require.True(t, report.BTFOK)
+	require.True(t, report.RingbufOK)
+	require.True(t, report.TracingOK)
+	require.True(t, report.IterOK)
+}

pkg/filter/accessor_stubs_linux.go

@@ -35,9 +35,8 @@ func (noopAccessor) SetFields([]Field)                             {}
 func (noopAccessor) SetSegments([]fields.Segment)                  {}
 func (noopAccessor) IsFieldAccessible(*event.Event) bool           { return false }
 
-func newModuleAccessor() Accessor     { return noopAccessor{} }
-func newRegistryAccessor() Accessor   { return noopAccessor{} }
-func newHandleAccessor() Accessor     { return noopAccessor{} }
-func newPEAccessor() Accessor         { return noopAccessor{} }
-func newDNSAccessor() Accessor        { return noopAccessor{} }
-func newThreadpoolAccessor() Accessor { return noopAccessor{} }
+func newModuleAccessor() Accessor   { return noopAccessor{} }
+func newRegistryAccessor() Accessor { return noopAccessor{} }
+func newHandleAccessor() Accessor   { return noopAccessor{} }
+func newPEAccessor() Accessor       { return noopAccessor{} }
+func newDNSAccessor() Accessor      { return noopAccessor{} }

pkg/filter/fields/defs_windows.go

@@ -29,6 +29,17 @@ import (
 func platformString() params.Type     { return params.UnicodeString }
 func platformAnsiString() params.Type { return params.AnsiString }
 
+// isNumber is the field argument validation function that
+// returns true if all characters are digits.
+var isNumber = func(s string) bool {
+	for _, c := range s {
+		if !unicode.IsNumber(c) {
+			return false
+		}
+	}
+	return true
+}
+
 var fields = platformFields(map[Field]FieldInfo{
 	EvtPID:          {EvtPID, "process identifier generating the event", params.Uint32, []string{"evt.pid = 6"}, nil, nil},
 	EvtTID:          {EvtTID, "thread identifier generating the event", params.Uint32, []string{"evt.tid = 1024"}, nil, nil},

pkg/filter/fields/fields.go

@@ -21,7 +21,6 @@ package fields
 import (
 	"github.com/rabbitstack/fibratus/pkg/event/params"
 	"sort"
-	"unicode"
 )
 
 // FieldInfo is the field metadata descriptor.
@@ -34,17 +33,6 @@ type FieldInfo struct {
 	Argument    *Argument
 }
 
-// isNumber is the field argument validation function that
-// returns true if all characters are digits.
-var isNumber = func(s string) bool {
-	for _, c := range s {
-		if !unicode.IsNumber(c) {
-			return false
-		}
-	}
-	return true
-}
-
 // Argument defines field argument information.
 type Argument struct {
 	// Optional indicates if the argument is optional.