Osprey is a host-side eBPF probe written in Rust with aya:
it captures application-layer messages at the syscall boundary, reassembles them
into transaction-level records in user space, and emits them through a
pluggable Sink. It serves as a blind-spot data source alongside wire-side tap
collection (SPAN/TAP), filling in the dimensions a physical mirror can never
reach — TLS/mTLS plaintext (planned), process/container/Pod identity semantics,
K8s east-west and same-host loopback traffic — and performs dual-vantage
reconciliation against the wire side via recon-diff.
Status: Phase 0 skeleton. Current capabilities = capturing
connect/accept4/close/read/write/sendto/recvfrom/vectored-I/O and similar syscall events, kernel-side local address capture, process allowlist filtering, jsonl output + recon-diff reconciliation. The Connection Tracker that reassembles byte streams into HTTP transactions is still evolving. Use--syntheticto validate the output path end to end.
| Path | Contents |
|---|---|
osprey-ebpf/ |
Kernel-side BPF programs (aya-ebpf, pure Rust; zero protocol parsing in the kernel) |
osprey-common/ |
Shared kernel/user-space event ABI (no_std, repr(C)) |
osprey-agent/ |
User-space agent: load/attach, ringbuf consumption; the Connection Tracker and parsing evolve here |
osprey-record/ |
Message-level record model (MsgRecord) + output layer (Sink: jsonl) |
recon-diff/ |
Dual-vantage reconciliation tool (field-level diff between wire side and eBPF side) |
contrib/lima/ |
macOS local development VMs (Ubuntu 24.04 / 22.04) |
tests/smoke/ |
End-to-end smoke test (shared by local and CI) |
tests/recon/ |
Reconciliation replay samples |
docs/ |
Architecture notes and downstream integration recipes |
- Install / run / troubleshoot: INSTALL.md
- Architecture and design constraints: docs/architecture.md
- Integrating with a transaction-analysis backend (e.g. Netis BPC): docs/integration/bpc-recipe.md
eBPF can only be built and run on Linux. Day-to-day development happens inside a Lima VM, with the source code shared in via virtiofs:
brew install lima
limactl create --name=osprey-2404 contrib/lima/osprey-2404.yaml
limactl start osprey-2404
limactl shell osprey-2404
# Inside the VM:
cd ~/code/Osprey
cargo build # also builds the BPF bytecode via build.rs/aya-build
RUST_LOG=info cargo run # watch the event output (.cargo/config.toml sets up a sudo -E runner)Compatibility check (kernel 5.15): limactl create --name=osprey-2204 contrib/lima/osprey-2204.yaml.
Toolchain: stable for user space; the BPF side is built by aya-build using nightly
(VM provisioning has already installed nightly + rust-src and bpf-linker).
On Apple Silicon the VM is aarch64, while the target deployment environment and
CI are x86_64 — let CI be the source of truth before you submit.
./tests/smoke/smoke.shBuild → verify the tracepoint layout assumptions → load as root → trigger a
connect with curl → assert the event → unload. CI (.github/workflows/ci.yml)
runs the same script on ubuntu-latest.
The whole aya family is pinned to a single git rev (see the comment in the root
Cargo.toml): the November 2025 release batch on crates.io was yanked, so it's
impossible to assemble a consistent set of published versions. To upgrade, update
the rev and run the full-matrix regression.
GPL-3.0-or-later. See LICENSE for details.