Rewrite fstrace on eBPF (Rust + Aya) with full feature parity

Replace the C/ptrace implementation with an eBPF tracer written in Rust on
top of Aya. Tracing now happens in-kernel via fexit probes on the traced
syscalls plus sched_process_{fork,exec,exit} tracepoints and a ring buffer,
instead of stopping the target on every syscall from userspace. No features
are dropped: full syscall coverage, path resolution (cwd/dirfd/AT_FDCWD +
normalization), the fd->path cache, process-tree scoping, and exit/signal/
env passthrough are all preserved, alongside filters, debounce, and
per-process logging.

Architecture (privileged/unprivileged split)
- fstrace-daemon: the privileged half. Loads and attaches the embedded eBPF
  object, owns the ring buffer and the traced-pid map, and serves multiple
  clients over a Unix socket. It routes events purely by root-namespace pid,
  so it works correctly from inside its own pid+mount namespace and needs no
  --pid=host. When tracefs is absent (e.g. a scratch container) it mounts
  tracefs itself before loading.
- fstrace: the unprivileged client. Runs as the invoking user with no sudo,
  forks the target, registers it with the daemon, and streams reports on
  fd 3. Exit code, signals, and environment are passed through untouched.
- fstrace-common: shared #[repr(C)] POD event structs and typed enums
  (Syscall/AccessType/FileType) used by both the eBPF and userspace sides.
- fstrace-ebpf: the eBPF programs (fexit per traced syscall + fork/exec/exit
  tracepoints writing into a ring buffer). The fork tracepoint's child_pid
  offset is read from tracefs at load time rather than hardcoded, tracking
  the ~6.16 __data_loc layout change.

Packaging & deployment
- systemd service + socket units (socket-activation friendly), a SysV
  init.d script, and man pages for both binaries.
- A FROM-scratch Dockerfile for the fully static (musl, static-PIE) daemon;
  bind-mount the socket dir + /sys/kernel/btf and run --privileged to trace
  host commands across namespaces. Rootful runtime required (rootless cannot
  create BPF maps).
- npm distribution package retained under node/fstrace.

Tooling & lifecycle (xtask)
- The entire repo lifecycle runs through `cargo xtask`: fmt, lint, test,
  check, build, clean, dist (cross-compile), docker-build/docker-test, and
  vm-test. All former shell scripts are ported to Rust.
- Cross-compilation for {x86_64, aarch64} x {gnu, musl} produces release
  tarballs.

Testing
- Host-side unit tests cover path normalization, filters, debounce,
  classification, and resolution.
- The privileged loader and full syscall coverage run end-to-end inside a
  throwaway QEMU VM so eBPF never loads on the host. The harness (all Rust)
  downloads prebuilt upstream kernels from the Ubuntu mainline archive,
  builds an initramfs from a Docker image rootfs (Ubuntu and Alpine/musl),
  and direct-boots QEMU, parsing a console result sentinel. A thin
  fstrace-scenario binary issues the raw syscalls under trace. Coverage
  includes 23 syscall/behavioural tests (incl. near-PATH_MAX paths,
  multi-client isolation, passthrough), namespace isolation with a
  containerized daemon, and systemd socket-activation.

Kernel support
- Verified across LTS {5.10, 5.15, 6.1, 6.6, 6.12, 6.18}, stable 7.1, and
  mainline 7.2-rc. Feature floor is the ring buffer (5.8); 5.4 and older
  lack it. Requirements and the support matrix are documented in
  docs/kernel-support.md.

Docs
- README plus focused docs/ pages: architecture, building, testing,
  deployment, reports-and-fd3, and kernel-support.

CI
- Three jobs, all driven by the cargo xtask alias: format/clippy/host tests,
  a vm-e2e matrix (8 kernels x {ubuntu, alpine}), and a cross-dist matrix
  (4 targets) uploading release tarballs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: bmiddha

.cargo/config.toml

@@ -0,0 +1,16 @@
+# Cross-compilation linkers for the supported release targets.
+#
+# aarch64 builds need a cross linker; install it with:
+#   apt-get install -y gcc-aarch64-linux-gnu
+#
+# x86_64-unknown-linux-musl links self-contained via rust-lld and needs no
+# extra toolchain. See `cargo xtask dist` and docs/building.md.
+
+[alias]
+xtask = "run --package xtask --"
+
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"
+
+[target.aarch64-unknown-linux-musl]
+linker = "aarch64-linux-gnu-gcc"

.clang-format

@@ -1,19 +1,17 @@
 {
-	"image": "mcr.microsoft.com/devcontainers/cpp:1-ubuntu-24.04",
+	"image": "mcr.microsoft.com/devcontainers/rust:1-bookworm",
 	"features": {
 		"ghcr.io/devcontainers/features/node:2": {
-			"nodeGypDependencies": true,
-			"version": "18",
-			"pnpmVersion": "latest",
-			"nvmVersion": "latest"
+			"version": "18"
 		}
 	},
+	"onCreateCommand": "rustup show && rustup component add rust-src clippy rustfmt && cargo install bpf-linker --locked",
 	"customizations": {
 		"vscode": {
 			"extensions": [
-				"ms-vscode.cmake-tools",
-				"ms-vscode.cpptools"
+				"rust-lang.rust-analyzer",
+				"vadimcn.vscode-lldb"
 			]
 		}
 	}
-}
+}

.devcontainer/devcontainer.json

@@ -3,28 +3,102 @@ name: ci
 on: [push, pull_request]
 
 jobs:
-  cmake-release:
-    name: CMake Build and Test
+  lint-and-unit:
+    name: Format, Clippy & Host Unit Tests
     runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v7
+
+      - name: 🦀 Install Rust toolchain
+        run: |
+          rustup show
+          rustup component add rustfmt clippy rust-src
+          cargo install bpf-linker --locked
+
+      - name: 💄 Format check
+        run: cargo xtask fmt --check
+
+      - name: 📎 Clippy
+        run: cargo xtask lint
+
+      - name: 🔨 Build (release)
+        run: cargo xtask build
+
+      - name: 🧪 Host unit tests
+        run: cargo xtask test
+
+  vm-e2e:
+    name: VM e2e (${{ matrix.userspace.name }} on ${{ matrix.release }})
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    strategy:
+      fail-fast: false
+      matrix:
+        release: ["5.10", "5.15", "6.1", "6.6", "6.12", "6.18", "7.1", "7.2-rc"]
+        userspace:
+          - name: ubuntu
+            image: docker.io/library/ubuntu:latest
+          - name: alpine
+            image: docker.io/library/alpine:latest
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v7
 
+      - name: 🦀 Install Rust toolchain
+        run: |
+          rustup show
+          rustup component add rust-src
+          rustup target add x86_64-unknown-linux-musl
+          cargo install bpf-linker --locked
+
+      - name: 💿 Install QEMU & tooling
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y qemu-system-x86 cpio binutils curl
+
+      - name: ⚡ Enable KVM (best effort)
+        run: sudo chmod 666 /dev/kvm || true
+
+      - name: 🖥️ Run VM e2e suite
+        env:
+          FSTRACE_VM_IMAGE: ${{ matrix.userspace.image }}
+        run: cargo xtask vm-test --release ${{ matrix.release }}
+
+  cross-dist:
+    name: Cross-Compile Release Artifacts
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - x86_64-unknown-linux-gnu
+          - x86_64-unknown-linux-musl
+          - aarch64-unknown-linux-gnu
+          - aarch64-unknown-linux-musl
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Build Project (Release)
-      uses: threeal/cmake-action@v2.1.0
-      with:
-        options: |
-          CMAKE_BUILD_TYPE=Release
-
-    - name: Test Project (Release)
-      uses: threeal/ctest-action@v1.1.0
-
-    - name: Build Project (Debug)
-      uses: threeal/cmake-action@v2.1.0
-      with:
-        options: |
-          CMAKE_BUILD_TYPE=Debug
-
-    - name: Test Project (Debug)
-      uses: threeal/ctest-action@v1.1.0
+      - name: 📥 Checkout code
+        uses: actions/checkout@v7
+
+      - name: 🦀 Install Rust toolchain
+        run: |
+          rustup show
+          rustup component add rust-src
+          rustup target add ${{ matrix.target }}
+          cargo install bpf-linker --locked
+
+      - name: 🔗 Install aarch64 cross linker
+        if: startsWith(matrix.target, 'aarch64')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu
+
+      - name: 📦 Build release tarball
+        run: cargo xtask dist --target ${{ matrix.target }}
+
+      - name: ⬆️ Upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: fstrace-${{ matrix.target }}
+          path: dist/*.tar.gz

.github/workflows/ci.yml

@@ -1 +1,3 @@
-build/
+/target
+/dist
+tests/vm/.cache/

.gitignore

@@ -2,71 +2,13 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "(gdb) fstrace",
-      "type": "cppdbg",
+      "name": "Debug fstrace (lldb)",
+      "type": "lldb",
       "request": "launch",
-      "program": "${workspaceFolder}/build/fstrace-debug",
+      "program": "${workspaceFolder}/target/release/fstrace",
       "args": ["/usr/bin/cat", "${workspaceFolder}/README.md"],
-      "stopAtEntry": false,
-      "cwd": "${fileDirname}",
-      "environment": [],
-      "externalConsole": false,
-      "MIMode": "gdb",
-      "setupCommands": [
-        {
-          "description": "Enable pretty-printing for gdb",
-          "text": "-enable-pretty-printing",
-          "ignoreFailures": true
-        },
-        {
-          "description": "Set Disassembly Flavor to Intel",
-          "text": "-gdb-set disassembly-flavor intel",
-          "ignoreFailures": true
-        }
-      ]
-    },
-    {
-      "name": "(gdb) Attach",
-      "type": "cppdbg",
-      "request": "attach",
-      "program": "${workspaceFolder}/build/fstrace",
-      "MIMode": "gdb",
-      "setupCommands": [
-        {
-          "description": "Enable pretty-printing for gdb",
-          "text": "-enable-pretty-printing",
-          "ignoreFailures": true
-        },
-        {
-          "description": "Set Disassembly Flavor to Intel",
-          "text": "-gdb-set disassembly-flavor intel",
-          "ignoreFailures": true
-        }
-      ]
-    },
-    {
-      "name": "(gdb) test_fstrace",
-      "type": "cppdbg",
-      "request": "launch",
-      "program": "${workspaceFolder}/build/test_fstrace",
-      "stopAtEntry": true,
-      "cwd": "${fileDirname}",
-      "environment": [],
-      "externalConsole": false,
-      "MIMode": "gdb",
-      "setupCommands": [
-        {
-          "description": "Enable pretty-printing for gdb",
-          "text": "-enable-pretty-printing",
-          "ignoreFailures": true
-        },
-        {
-          "description": "Set Disassembly Flavor to Intel",
-          "text": "-gdb-set disassembly-flavor intel",
-          "ignoreFailures": true
-        }
-      ],
-      "preLaunchTask": "CMake: clean rebuild"
+      "cwd": "${workspaceFolder}",
+      "env": { "RUST_LOG": "fstrace=debug" }
     }
   ]
 }