> ## 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. # filetrace inspect: a file, process, socket, flow or address > Reference for filetrace inspect: reports on a file, process, socket, flow or IP address, with a real sample of each, the options, JSON output and exit codes. `filetrace inspect` gathers everything the agent knows about one thing into a single report, from whichever side you approach it: a file, a process, a socket, a flow or a remote address. Each report ends with the time from which the agent's history reaches. ## Usage ```bash theme={null} filetrace inspect file filetrace inspect process filetrace inspect socket filetrace inspect flow filetrace inspect ip ``` | Target | Answers | | - | - | | `file` | Who sent this file, to whom, how much and by which method | | `process` | What this process is sending now, where to, and which files | | `socket` | One socket: its ends, owner, traffic and the files sent on it | | `flow` | One process's traffic with one remote endpoint on a socket | | `ip` | Which processes talk to this address or network, and which files were sent to it | Socket and flow IDs are the SOCKET and FLOW columns of [`connections`](https://filetrace.mintlify.site/cli/connections) and [`flows`](https://filetrace.mintlify.site/cli/flows), and the `socket_id` and `flow_id` fields of their machine-readable output. ## Options **--since** `string` Only what was active at or after this time: a duration such as `10m`, `1h` or `7d`, or an RFC 3339 timestamp. **--limit** `number` (default: 20) Rows per list. A list that is cut short ends with a line that says how many rows were left out. **--resolve-hostnames** `boolean` Show remote addresses by host name where a reverse DNS lookup finds one. **--format** `string` (default: table) `table` or `json`. **--json** `boolean` Short for `--format json`. **--output** `string` Write to this file instead of standard output. History begins when the agent starts and is kept in memory only; every report says from when it reaches. ## file `inspect file` takes a path. The path may contain `*` wildcards if they match a single file; a pattern that matches several files is an error, and the command lists the matching transfers on standard error and exits with 2. ```bash theme={null} sudo filetrace inspect file /srv/export/media/files/video.mp4 ``` ```text theme={null} FILE ──────────────────────────────────── Path: /srv/export/media/files/video.mp4 Device: 0:63 Inode: 626324 Size: 47.7 MB Owner: root Filesystem: overlay Deleted: no TRANSFER HISTORY ──────────────────────────────────── TIME PROCESS PID REMOTE BYTES METHOD CONFIDENCE 2026-11-11 20:07:56 file-server 1014 127.0.0.1:34477 47.7 MB sendfile EXACT TOTALS ──────────────────────────────────── Total sent: 47.7 MB Destinations: 1 Processes: 1 Transfers: 1 Active transfers: 1 PROVENANCE ──────────────────────────────────── sendfile: 1 transfer Exact: 1 History starts at 2026-11-11 20:07:55, when the agent started. Nothing earlier is kept. ``` * **FILE** gives the file's identity: device as major and minor number, inode, size, owner and filesystem as read when the file was first seen, and whether it has been deleted. * **TRANSFER HISTORY** lists the most recent transfers, oldest first, with the time each started. * **TOTALS** adds up the bytes sent and counts the distinct destinations and processes, the transfers and those still in progress. * **PROVENANCE** counts the transfers by method and by [confidence](https://filetrace.mintlify.site/concepts/attribution.md). A file sent by a read-write loop shows the same report with that method and INFERRED confidence: ```text theme={null} TRANSFER HISTORY ──────────────────────────────────── TIME PROCESS PID REMOTE BYTES METHOD CONFIDENCE 2026-11-11 20:07:56 file-server 1018 127.0.0.1:52535 11.4 MB read-write INFERRED TOTALS ──────────────────────────────────── Total sent: 11.4 MB Destinations: 1 Processes: 1 Transfers: 1 Active transfers: 1 PROVENANCE ──────────────────────────────────── read-write: 1 transfer Inferred: 1 ``` If the file has not been sent since the agent started, the report says so instead. ## process `inspect process` takes a process ID. It combines what the agent observed with what the system knows about a process that is still running: its cgroup and the number of files it has open. ```bash theme={null} sudo filetrace inspect process 1024 ``` ```text theme={null} PROCESS ──────────────────────────────────── Name: file-server PID: 1024 PPID: 772 User: root Executable: /usr/local/bin/file-server Cgroup: / Network ns: 4026532561 Started: 2026-11-11 20:07:56 Status: running NETWORK ──────────────────────────────────── Connections: 2 open Outbound: 3.98 MB/s (15.5 MB sent) Inbound: 0 B/s (0 B received) FILES ──────────────────────────────────── Open files: 5 Active transfers: 1 Unique files: 1 Transfers: 1 TOP DESTINATIONS ──────────────────────────────────── DESTINATION OUTBOUND SENT RECEIVED 127.0.0.1 3.98 MB/s 15.5 MB 0 B FILES SENT ──────────────────────────────────── FILE PROCESS REMOTE BYTES METHOD CONFIDENCE /srv/export/media/files/stream.bin file-server 127.0.0.1:51871 15.5 MB sendfile EXACT History starts at 2026-11-11 20:07:55, when the agent started. Nothing earlier is kept. ``` * **PROCESS** identifies the process. For a process that has exited, Status gives its exit code or the signal that ended it, with the time; Cgroup then shows the cgroup ID, and Open files is left out, because the PID may by now belong to another process. * **NETWORK** gives its open connections and its current rates with the totals. * **FILES** counts its open files, its transfers in progress, the distinct files it sent and its transfers. * **TOP DESTINATIONS** lists its remote addresses by current rate, then by bytes sent. * **FILES SENT** lists its transfers, most recent first. ## socket `inspect socket` takes a socket ID from the SOCKET column of [`connections`](https://filetrace.mintlify.site/cli/connections). ```bash theme={null} sudo filetrace inspect socket 17 ``` ```text theme={null} SOCKET ──────────────────────────────────── ID: 17 Protocol: TCP Local: 127.0.0.1:51871 Remote: 127.0.0.1:41814 State: established Process: file-server (PID 1026) First seen: 2026-11-11 20:07:56 Last active: 2026-11-11 20:07:59 Sent: 0 B (0 B/s) Received: 15.5 MB (3.97 MB/s) FLOWS ──────────────────────────────────── FLOW PID PROCESS REMOTE SENT RECEIVED OUTBOUND 11 1026 file-server 127.0.0.1:41814 0 B 15.5 MB 0 B/s FILES SENT ──────────────────────────────────── No file has been associated with what it sent. History starts at 2026-11-11 20:07:55, when the agent started. Nothing earlier is kept. ``` The socket above is the receiving end of a transfer, so no file is associated with what it sent. A closed socket also shows when it closed. Process reads `not yet known` for an accepted connection whose owner has not sent or received yet. FLOWS lists the flows on the socket, one per process and remote endpoint. ## flow `inspect flow` takes a flow ID from the FLOW column of [`flows`](https://filetrace.mintlify.site/cli/flows). ```bash theme={null} sudo filetrace inspect flow 12 ``` ```text theme={null} FLOW ──────────────────────────────────── ID: 12 Socket: 3 Protocol: TCP Local: 127.0.0.1:43090 Remote: 127.0.0.1:34477 Process: file-server (PID 1014) First seen: 2026-11-11 20:07:56 Last active: 2026-11-11 20:07:56 Sent: 47.7 MB (0 B/s) Received: 0 B (0 B/s) Operations: 763 sends, 0 receives FILES SENT ──────────────────────────────────── FILE PROCESS REMOTE BYTES METHOD CONFIDENCE /srv/export/media/files/video.mp4 file-server 127.0.0.1:34477 47.7 MB sendfile EXACT History starts at 2026-11-11 20:07:55, when the agent started. Nothing earlier is kept. ``` Operations gives the number of send and receive operations counted for the flow. FILES SENT lists the transfers of this process on this socket. ## ip `inspect ip` takes an IPv4 or IPv6 address, or a network in CIDR notation. The first section is titled ADDRESS for a single address and NETWORK for a network. ```bash theme={null} sudo filetrace inspect ip 127.0.0.1 ``` ```text theme={null} ADDRESS ──────────────────────────────────── Remote: 127.0.0.1 Sent to it: 74.9 MB (3.98 MB/s) Received from it: 73.4 MB Flows: 9 Processes: 9 File transfers: 3 PROCESSES ──────────────────────────────────── PID PROCESS OUTBOUND SENT RECEIVED 1014 file-server 0 B/s 47.7 MB 0 B 1024 file-server 3.98 MB/s 15.5 MB 0 B 1018 file-server 0 B/s 11.4 MB 0 B 1020 file-server 0 B/s 195 KB 6 B 1022 file-server 0 B/s 48.8 KB 0 B 1021 file-server 0 B/s 6 B 195 KB 1015 file-server 0 B/s 0 B 46.3 MB 1019 file-server 0 B/s 0 B 11.4 MB 1026 file-server 0 B/s 0 B 15.5 MB FILES SENT TO IT ──────────────────────────────────── FILE PROCESS REMOTE BYTES METHOD CONFIDENCE /srv/export/media/files/stream.bin file-server 127.0.0.1:51871 15.5 MB sendfile EXACT /srv/export/media/files/customers.csv file-server 127.0.0.1:52535 11.4 MB read-write INFERRED /srv/export/media/files/video.mp4 file-server 127.0.0.1:34477 47.7 MB sendfile EXACT History starts at 2026-11-11 20:07:55, when the agent started. Nothing earlier is kept. ``` PROCESSES lists the processes with traffic to or from the address, largest sender first. [Investigate a remote address](https://filetrace.mintlify.site/guides/investigate-a-destination.md) walks through this report. ## JSON output `--json` prints one object. Its `kind` names the target, its lists hold the same records as the listing commands, and `observed_since` and `events_lost` close it: ```bash theme={null} sudo filetrace inspect file /srv/export/media/files/video.mp4 --json ``` ```json theme={null} {"kind":"file","path":"/srv/export/media/files/video.mp4","totals":{"bytes_sent":50000000,"transfers":1,"active_transfers":1,"destinations":1,"processes":1},"provenance":{"methods":{"sendfile":1,"read-write":0},"confidence":{"exact":1,"strong":0,"inferred":0,"unknown":0}},"transfers":[ {"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}} ],"observed_since":"2026-11-11T20:07:55.984Z","events_lost":0} ``` | `kind` | Fields | | - | - | | `file` | `path`, `totals`, `provenance`, `transfers` | | `process` | `pid`, `process` (a record of [`processes`](https://filetrace.mintlify.site/cli/processes)), `cgroup` and `open_files` while it runs, `destinations`, `transfers` | | `socket` | `socket_id`, `connection` (a record of [`connections`](https://filetrace.mintlify.site/cli/connections)), `flows`, `transfers` | | `flow` | `flow_id`, `flow` (a record of [`flows`](https://filetrace.mintlify.site/cli/flows)), `transfers` | | `ip` | `network`, `totals`, `processes`, `transfers` | The JSON lists are not cut by `--limit`. [JSON output schema](https://filetrace.mintlify.site/reference/json-output.md) describes every field. ## Examples ```bash theme={null} filetrace inspect file /data/backup.tar.gz filetrace inspect process 1245 filetrace inspect ip 203.0.113.0/24 --since 1h filetrace inspect socket 928374 --json ``` ## Exit codes | Code | Meaning | | - | - | | 0 | Success, including a report that nothing was observed | | 1 | General error | | 2 | Invalid arguments, such as a malformed ID or address, or a path pattern that matches several files | | 3 | Permission denied: the agent socket is not accessible to this user | | 4 | No agent is running | | 5 | Unsupported platform or capability | | 6 | The configuration file cannot be read or is invalid | | 9 | Partial results: events were lost in the queried time range | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.