Filetrace: see which files leave your machine

Filetrace is a Linux eBPF tool that shows which files a machine sends over the network, which process sends them, where they go, and how sure each answer is.

Filetrace shows which files a machine sends over the network, which process sends them, and where they go. It observes the Linux kernel through eBPF, so no application has to be changed or restarted, and every answer carries a confidence level that says how it was established.

$ sudo filetrace files
FILE                    PROCESS  DESTINATION   BYTES    METHOD      CONFIDENCE
/var/www/video.mp4      nginx    198.51.100.4  1.20 GB  sendfile    EXACT
/data/export/users.csv  python   192.0.2.10    85.2 MB  read-write  INFERRED

​

Questions it answers

Filetrace links files, processes and network endpoints in both directions, so you can start an investigation from whichever side you know.

You know	You want	Command
A file	Who sends it, and to whom	filetrace inspect file /data/report.pdf
An address	The files sent to it	filetrace files --remote 203.0.113.25
A process	What it is sending now	filetrace inspect process 1245
The network	The processes behind the traffic	filetrace processes

​

How it works

Filetrace is two programs. filetrace-agent loads BPF programs into the kernel, keeps what they report in bounded memory, and answers queries on a local socket. filetrace is the command-line interface: it asks the agent and prints the answer as a table, JSON, JSON Lines or CSV.

The agent attributes a send to a file in two ways. When the kernel moves a file to a socket itself, as sendfile(2) does, the attribution is EXACT. When a thread reads a regular file and then sends on a socket, the attribution is INFERRED, because the payload cannot be proven to come only from that file. Bytes that no file accounts for are still counted, as UNKNOWN.

The same state is available to other tools: a Prometheus metrics page, OpenTelemetry events and metrics over OTLP, and a gRPC API that lists and streams transfers.

​

Requirements

Collection needs Linux 6.1 or later with BTF. Filetrace is tested on Linux 6.1, 6.12 and 7.0 on arm64, and continuous integration builds and tests x86-64 and arm64. On macOS the command-line interface builds and reports diagnostics, but nothing is collected.

​

Next steps

Quickstart

Install Filetrace, start the agent and find your first file transfer.

Installation

Package repositories, Homebrew, release archives, versions and channels.

File attribution

How a send is tied to a file, and what EXACT and INFERRED mean.

CLI reference

Every command, option, filter and output format.

Integrations

Prometheus metrics, OpenTelemetry export and the gRPC API.

Configuration

Every setting of the agent’s configuration file.