Skip to main content
Filetrace runs a privileged agent that sees file paths, process names and network peers across the whole machine, so where it comes from and who can read what it records both matter. This page shows how to verify a download and the signing keys, which privileges the agent holds and how its systemd unit confines it, who can reach its query socket and its exporters, and how to report a vulnerability.

​
Verifying a download

Every release lists the SHA-256 checksum of its files in SHA256SUMS and carries a build attestation that ties each file to the workflow run and the commit it came from. The files are the assets of the GitHub release, also served under https://filetrace.eorlov.org/dist/<tag>/.
1

Download the file and the checksums

2

Check the checksum

3

Verify the build attestation

With the GitHub CLI:
When the installer script installs from an archive, it downloads the release’s SHA256SUMS and refuses an archive that does not match. When it installs a package, the package manager checks the repository’s signature. The installer itself is a release file too (install.sh), listed in SHA256SUMS. To read it before running it, download it with curl -fsSLO https://filetrace.eorlov.org/install.sh and run it with sudo sh install.sh.

​
Signing keys

The apt and yum repositories and the rpm packages are signed with the OpenPGP key at https://filetrace.eorlov.org/gpg.key; the apk repository and packages with the RSA key at https://filetrace.eorlov.org/apk/filetrace.rsa.pub. Compare a downloaded key with the values the repository records in SECURITY.md:
The repository definitions in Installation make the package manager enforce the signatures: Signed-By for apt, gpgcheck=1 and repo_gpgcheck=1 for dnf and yum, and the key in /etc/apk/keys for apk. If a key is ever replaced, the repositories are signed again and serve the new public key; fetch gpg.key or filetrace.rsa.pub again and compare it with SECURITY.md.

​
The agent’s privileges

Only filetrace-agent needs privileges: loading BPF programs needs root, or CAP_BPF with CAP_PERFMON. The filetrace command asks the agent over a local socket and needs no privileges of its own beyond access to that socket. filetrace watch and filetrace events --follow collect in the foreground when no agent is running, and then need the agent’s privileges themselves, as does filetrace doctor, which loads and attaches every probe for its check. The packaged systemd unit runs the agent as root and confines it:
Under this unit, keep [agent] socket and a unix: [grpc] listen path inside /run/filetrace. ProtectSystem=strict leaves the agent no other place to create a socket, and PrivateTmp=yes hides a socket under /tmp from the commands.
The configuration file /etc/filetrace/config.toml is installed with mode 0644. It holds no credentials.

​
Who can reach the agent

​
Query socket

The agent creates its query socket, /run/filetrace/agent.sock by default, with mode 0600, and checks the credentials of every process that connects: only root and the user the agent runs as are admitted. Anyone else is turned away and the agent logs a warning. With the agent running as root, the commands that query it need sudo; without it they exit with code 3. A client admitted to the socket reads everything the agent recorded, and can stop the agent with filetrace agent stop.

​
gRPC API

The API is off by default. With [grpc] listen set to a unix: socket, as by default, it is created with mode 0600 and admits only root and the agent’s user, like the query socket. With an address and port, such as 127.0.0.1:9500, it admits whoever can connect, and the agent logs a warning saying so when it starts. The server speaks gRPC over HTTP/2 without TLS and without authentication, and returns transfers with file paths and remote addresses. See gRPC API guide.

​
Prometheus page

The metrics page is off by default and, when on, listens on 127.0.0.1:9464. It has no authentication: setting [prometheus] listen to another address makes the metrics readable by anyone who can reach that address and port. No metric is labelled with a file path or an address; metrics carry process names, transfer methods, confidence levels and byte counts. See Prometheus.

​
OTLP exporter

The agent sends OTLP over gRPC without TLS and does not resolve host names. Point [otlp] endpoint at a collector on the same host, by numeric address or unix: socket, and let that collector forward with credentials and encryption of its own. The log records carry file paths, process names and executables, user IDs and network addresses. To keep paths out of them, set file_paths = false; device and inode remain:
[otlp] events limits which event types leave the host. See OpenTelemetry (OTLP).

​
Data at rest and lookups

  • The agent keeps what it records in memory only, in bounded tables and a bounded event log. Persistent history is not included in this build, so nothing it records is written to disk. Its own log goes to standard error, which systemd keeps in its journal and the OpenRC and SysV init scripts write to /var/log/filetrace-agent.log.
  • --resolve-hostnames makes the command look up remote addresses by reverse DNS through the system’s resolver. The lookups tell the DNS resolver which addresses are being looked at. The option is off unless given.

​
Reporting a vulnerability

Report a vulnerability privately through a security advisory, not in a public issue. Expect an answer within a week. Fixes go into the newest release line and into the lts lines; Versions and release channels explains how to tell them apart.