filetrace files: list files sent over the network

Reference for filetrace files: the columns it prints, how to read BYTES and CONFIDENCE, every option with its values, examples with real output, and exit codes.

filetrace files lists the files that processes have sent over the network, most recently active first: which process sent each file, to which address, how many bytes and by which method. Every row carries the confidence of the association between the file and the socket.

​

Usage

filetrace files [options]

​

What it shows

sudo filetrace files

FILE                                   PROCESS      DESTINATION    BYTES  METHOD      CONFIDENCE
/srv/export/media/files/stream.bin     file-server  127.0.0.1    15.5 MB  sendfile    EXACT
/srv/export/media/files/customers.csv  file-server  127.0.0.1    11.4 MB  read-write  INFERRED
/srv/export/media/files/backup.tar.gz  file-server  ::1          7.63 MB  sendfile    EXACT
/srv/export/media/files/video.mp4      file-server  127.0.0.1    47.7 MB  sendfile    EXACT

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.

Each row is one transfer record: one file sent by one process on one socket.

Column	Meaning
FILE	The file’s path, followed by (deleted) for a file that no longer has a directory entry. A file whose path is not known shows as (device <n> inode <n>).
PROCESS	The name of the process that sent it
DESTINATION	The remote address of the socket, without the port
BYTES	What the socket accepted from this file
METHOD	sendfile or read-write
CONFIDENCE	EXACT or INFERRED; a * after it marks a transfer during which events were lost

BYTES is neither the size of the file nor the bytes read from it. Machine-readable formats carry all three numbers, as file.size, transfer.bytes_read and transfer.bytes_sent. Byte counts are what the local socket accepted, not bytes on the wire or acknowledged by the remote end.

The confidence levels:

Level	Meaning
EXACT	The kernel moved the file’s data to the socket itself (sendfile).
INFERRED	A thread read the file and then sent on the socket. The payload cannot be proven to come only from this file.
UNKNOWN	Bytes sent with no file that could be associated with them. Listed only with --include-unknown or --confidence unknown, with FILE showing unknown.

File attribution and confidence explains the evidence behind each level. To see the bytes no file accounts for, use transfers; to see everything about one file, use inspect file.

​

Options

--deleted · boolean

Only files that no longer have a directory entry.

--include-unknown · boolean

Also list sent bytes with no associated file, as rows with FILE unknown and CONFIDENCE UNKNOWN.

--pid · number

Only this process.

--process · string

Only processes with this name. * matches any run of characters. Alias: --name.

--user · string

Only processes of this user, by name or numeric ID.

--cgroup · string

Only processes in this cgroup, by numeric ID or cgroup directory.

--namespace · number

Only processes in this network, PID or mount namespace, given as the inode number that ls -Li /proc/<pid>/ns shows.

--path · string

Only this file. * matches any run of characters, / included. Alias: --file.

--path-regex · string

Only files whose path matches this POSIX extended regular expression.

--min-size · string

Only files at least this large, such as 100MB.

--remote · string

Only this remote address or CIDR network.

--local · string

Only this local address or CIDR network.

--port · number

Only this local or remote port.

--protocol · string · default: "all"

Only this protocol: tcp, udp or all.

--method · string

sendfile or read-write. splice, mmap and io_uring are accepted but not observed by this build; with them the command exits with 5 instead of printing an empty list.

--confidence · string

exact, strong, inferred, unknown or all.

--min-bytes · string

At least this many bytes sent, such as 1KB, 100MB or 1GB.

--active · boolean

Only records still in progress: updated within the last 5 seconds.

--completed · boolean

Only records that are no longer in progress.

--since · string

Only records active at or after this time: a duration such as 10m, 1h or 7d, or an RFC 3339 timestamp.

--until · string

Only records that started at or before this time.

--sort · string

bytes, time, pid, rate, duration, process or file. Without it, the most recently active come first.

--resolve-hostnames · boolean

Show remote addresses by host name where a reverse DNS lookup finds one. The lookups tell the DNS resolver which addresses are being looked at.

--limit · number

Show at most this many rows.

--format · string · default: "table"

table, json, jsonl, csv or quiet. Quiet prints one file path per row.

--json · boolean

Short for --format json.

--jsonl · boolean

Short for --format jsonl.

--output · string

Write to this file instead of standard output.

Byte counts cover a record’s whole observed lifetime; --since and --until select which records are listed. Filters describes the value syntax, and output formats the formats.

​

Examples

filetrace files --active
filetrace files --path /data/report.csv
filetrace files --path '/data/*' --since 1h
filetrace files --confidence exact --min-bytes 100MB
filetrace files --jsonl

Files sent to a network with EXACT confidence:

sudo filetrace files --remote 127.0.0.0/8 --confidence exact

FILE                                PROCESS      DESTINATION    BYTES  METHOD    CONFIDENCE
/srv/export/media/files/stream.bin  file-server  127.0.0.1    15.5 MB  sendfile  EXACT
/srv/export/media/files/video.mp4   file-server  127.0.0.1    47.7 MB  sendfile  EXACT

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.

The three largest transfers:

sudo filetrace files --sort bytes --limit 3

FILE                                   PROCESS      DESTINATION    BYTES  METHOD      CONFIDENCE
/srv/export/media/files/video.mp4      file-server  127.0.0.1    47.7 MB  sendfile    EXACT
/srv/export/media/files/stream.bin     file-server  127.0.0.1    15.5 MB  sendfile    EXACT
/srv/export/media/files/customers.csv  file-server  127.0.0.1    11.4 MB  read-write  INFERRED

One file as JSON:

sudo filetrace files --path /srv/export/media/files/video.mp4 --json

[
 {"event":"file_transfer","transfer_id":"tr_1","timestamp":"2026-11-11T20:07:56.063Z","host":"web-01","platform":"linux","process":{"pid":1014,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/video.mp4","inode":626324,"device":63,"size":50000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":3,"local_ip":"127.0.0.1","local_port":43090,"remote_ip":"127.0.0.1","remote_port":34477},"transfer":{"method":"sendfile","bytes_sent":50000000,"bytes_per_second":0,"operations":1,"started":"2026-11-11T20:07:56.063Z","duration_ms":0,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
]

JSON output schema describes every field.

​

Exit codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments, including an invalid --path-regex
3	Permission denied: the agent socket is not accessible to this user
4	No agent is running
5	Unsupported platform, or a --method this build does not observe
6	The configuration file cannot be read or is invalid
9	Partial results: events were lost in the queried time range