Keep an audit trail for compliance

Send file-transfer records to a collector for a durable audit trail, control whether paths and arguments leave the host, and understand what the trail can and cannot prove.

The question: can we show, months later, which files a host sent, by which process, and to where?

The live commands answer for the current session, but the agent’s history is in memory and starts when the agent starts. A durable audit trail comes from exporting the records to a system that keeps them, and from deciding what may leave the host.

​

Decide what may leave the host

Three settings control the content of every exported record:

Setting	Default	Effect
[otlp] file_paths	true	false leaves full paths out; records keep the device and inode. Also drops the working directory and a script that is a path; module: and pool: remain.
[otlp] command_line	false	true adds process arguments, which can hold passwords and tokens.
[otlp] events	["file_transfer", "event_loss"]	Which event types leave. Add process_exec for a process-start trail.

A conservative posture for a regulated environment:

[otlp]
enabled = true
endpoint = "127.0.0.1:4317"
logs = true
metrics = true
events = ["file_transfer", "event_loss"]
file_paths = false    # device and inode instead of paths
command_line = false  # arguments stay on the host

An investigator with host access can still resolve a device and inode to a path while the file exists, and the inode plus the process is enough to prove what was sent.

​

Send the records to a collector

The agent speaks OTLP/gRPC without TLS to a collector on the same host; the collector adds TLS, credentials and retention. Route the audit trail to a store with the retention your policy requires and to your SIEM:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
processors:
  batch:
    timeout: 10s
exporters:
  otlphttp/audit:
    endpoint: https://audit.example.com/otlp
    headers:
      Authorization: "Bearer ${env:AUDIT_TOKEN}"
  otlphttp/siem:
    endpoint: https://siem.example.com/otlp
    headers:
      Authorization: "Bearer ${env:SIEM_TOKEN}"
service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/audit, otlphttp/siem]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/audit]

Each file_transfer record carries the time, the process, the script, the file identity, the peer address and the byte count. The full attribute list is in the metrics and attributes reference.

​

The questions the trail answers

# Everything one process sent, over any time the store keeps
{service_name="filetrace"} | json
  | filetrace_event_type = "file_transfer"
  | process_executable_name = "python3"
  | line_format "{{.timestamp}} {{.filetrace_process_script}} -> {{.network_peer_address}}"

# Every file sent to a network under investigation
{service_name="filetrace"} | json
  | filetrace_event_type = "file_transfer"
  | network_peer_address =~ `203\\.0\\.113\\..*`

# Files sent from a sensitive directory, by device and inode when paths are off
{service_name="filetrace"} | json
  | filetrace_event_type = "file_transfer"
  | filetrace_file_device = "64768"

The same questions against the live agent use the use-case pages.

​

Integrity and access

• The trail is only as good as the store. Use a backend with append-only or object-lock retention if the trail must be tamper-evident. Filetrace sends records; it does not sign them.
• The agent needs root. Only the agent loads BPF programs; the query commands need the agent’s socket. Restrict who can read it. See security.
• The metrics are not the trail. Counters survive an agent restart only as a reset; use the log records for per-file proof.
• Loss is recorded, not hidden. An event_loss record with filetrace.loss.kind says when and where records were lost, so a gap in the trail is visible.

​

Sizing the trail

file_transfer records are emitted per transfer, not per byte, but a busy server can produce many. Batch in the collector and choose retention from policy, not from volume alone. If volume is a concern, export only file_transfer and event_loss, not network_send and network_receive, which are the numerous per-interval records.

​

Where the trail can mislead

• The agent’s history is in memory. A restart is a gap in the live view, but not in an exported trail.
• INFERRED records are associations. The record says a thread read the file and then sent on the socket; it is evidence, not a signed statement of payload.
• Device and inode identify a file for as long as it exists and has not been replaced. On a copy-on-write or overlay filesystem, the same path can have different inodes over time.
• Clock and ordering. Records carry the event time; use it, not arrival time, for the timeline.

​

Related pages

• OpenTelemetry export — settings, delivery and retries.
• Metrics and attributes reference — every record field.
• Security model
• Observability recipes — collector routing and joins.