Use cases

What Filetrace is for: security and data-loss work, web-server audits, incident response, container attribution, egress accounting and compliance, with the commands and metrics for each.

Filetrace answers one family of questions from every angle: which files left this machine, who sent them, where they went, and how sure that is. Each page below starts from a real question, gives the commands that answer it, and shows what the output means and where the answer can mislead.

​

Pick a scenario

Scenario	The question	Start with
Detect sensitive files leaving a host	Did any file under /data/sensitive go off the machine, and to whom?	files, inspect file, an alert
Audit what a web server sends	What does nginx or PHP actually serve, and from which script?	files --process nginx, --script
Reconstruct an incident	What was sent during the window, in order?	events --since --until, inspect process
Attribute transfers to containers	Which container sent this file?	--cgroup, --namespace
Understand egress cost and capacity	Which processes and destinations drive egress?	flows --group-by remote, top destinations
Keep an audit trail for compliance	Can we prove who sent a file last month?	OTLP to a SIEM, retention

​

A method that works for all of them

1. Frame the question as a filter. Start from the file, the process, the destination or the time. The filters page gives the value syntax; the flags reference lists every option.
2. Read the confidence. EXACT means the kernel moved the file to the socket itself; INFERRED means a thread read the file and then sent on the socket. Treat INFERRED as strong evidence, not proof. See attribution.
3. Check for loss. A * next to a confidence level, a WARNING on standard error, or a non-zero filetrace_events_dropped_total means attribution is degraded for that window. filetrace stats shows where the loss happened.
4. Go one level deeper with inspect. Once a name or an address looks interesting, inspect shows every side of it at once.
5. Export what you need to keep. The agent’s history is in memory and starts when it starts. For anything you must keep, send the OTLP log records to a collector, or scrape the metrics.

​

The same answer, three ways

The scenarios use whatever fits at the time: a command for a one-off question, a metric for a dashboard, a log record for a system that outlives the agent.

# One-off: the files, now.
sudo filetrace files --path '/data/sensitive/*' --since 24h

# Dashboard: is the rate of file egress unusual?
sum by (process_executable_name) (rate(filetrace_file_sent_bytes_total[5m]))

# Audit: every file sent to one address, for the SIEM.
{service_name="filetrace"} | json | filetrace_event_type = "file_transfer" | network_peer_address = `203.0.113.25`

The observability recipes wire the metric and log forms to Prometheus, Grafana and an OpenTelemetry Collector.

​

Related pages

• Flags reference — every option by command.
• Filters — value syntax and how filters combine.
• File attribution and confidence — what the levels rest on.
• Observability recipes — alerts, dashboards, collector routing.