> ## Documentation Index > Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Security of Filetrace > Verify downloads and signing keys, see the agent's privileges and systemd hardening, control access to its sockets and exporters, report vulnerabilities. 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](https://github.com/OrlovEvgeny/filetrace/releases), also served under `https://filetrace.eorlov.org/dist//`. **1. Download the file and the checksums** ```bash theme={null} curl -fsSLO https://filetrace.eorlov.org/dist/v26.11.1.80-stable/filetrace-26.11.1.80-linux-amd64.tar.gz curl -fsSLO https://filetrace.eorlov.org/dist/v26.11.1.80-stable/SHA256SUMS ``` **2. Check the checksum** ```bash theme={null} sha256sum --check --ignore-missing SHA256SUMS ``` **3. Verify the build attestation** With the [GitHub CLI](https://cli.github.com): ```bash theme={null} gh attestation verify filetrace-26.11.1.80-linux-amd64.tar.gz --repo OrlovEvgeny/filetrace ``` 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](https://github.com/OrlovEvgeny/filetrace/blob/master/SECURITY.md): | Key | Command | Result | | - | - | - | | `gpg.key` | `gpg --show-keys --with-fingerprint gpg.key` | `5FCD 0A02 2A41 BCEE 7414 20B3 E90D D49D 7DE3 637F` | | `filetrace.rsa.pub` | `sha256sum filetrace.rsa.pub` | `d70013971038c848339485dbb15baef6afb42bad11019f4352dd5434c1e0adfb` | ```bash theme={null} curl -fsSLO https://filetrace.eorlov.org/gpg.key gpg --show-keys --with-fingerprint gpg.key curl -fsSLO https://filetrace.eorlov.org/apk/filetrace.rsa.pub sha256sum filetrace.rsa.pub ``` The repository definitions in [Installation](https://filetrace.mintlify.site/installation.md) 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: | Setting | Effect | | - | - | | `CapabilityBoundingSet=CAP_BPF CAP_PERFMON CAP_SYS_ADMIN CAP_SYS_PTRACE` | The only capabilities the agent can hold. `CAP_SYS_PTRACE` reads `/proc//exe` and the namespaces of other users' processes. | | `NoNewPrivileges=yes` | The agent and its children cannot gain privileges. | | `ProtectSystem=strict` | The file system is read-only to the agent, apart from its runtime directory. | | `ProtectHome=yes` | Home directories are inaccessible to the agent. | | `PrivateTmp=yes` | The agent has a `/tmp` of its own. | | `PrivateDevices=yes` | No access to physical devices. | | `ProtectKernelModules=yes`, `ProtectKernelLogs=yes`, `ProtectControlGroups=yes`, `ProtectClock=yes`, `ProtectHostname=yes` | No loading of kernel modules, no kernel log, no changes to cgroups, the clock or the host name. | | `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6` | Unix, IPv4 and IPv6 sockets only. | | `RestrictNamespaces=yes`, `RestrictRealtime=yes`, `RestrictSUIDSGID=yes` | No new namespaces, no realtime scheduling, no set-user-ID or set-group-ID files. | | `LockPersonality=yes`, `MemoryDenyWriteExecute=yes`, `SystemCallArchitectures=native` | No change of execution domain, no memory both writable and executable, native system calls only. | | `RuntimeDirectory=filetrace`, `RuntimeDirectoryMode=0755` | `/run/filetrace`, where the agent's sockets live. | > [!WARNING] > > 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](https://filetrace.mintlify.site/integrations/grpc-api.md). ### 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](https://filetrace.mintlify.site/integrations/prometheus.md). ### 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: ```toml theme={null} [otlp] enabled = true endpoint = "127.0.0.1:4317" file_paths = false ``` `[otlp] events` limits which event types leave the host. See [OpenTelemetry (OTLP)](https://filetrace.mintlify.site/integrations/opentelemetry.md). ## 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](https://github.com/OrlovEvgeny/filetrace/security/advisories/new), 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](https://filetrace.mintlify.site/reference/versioning.md) explains how to tell them apart. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.