Keep an audit trail for compliance

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.

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

Get started

Concepts

Guides

Use cases

Keep an audit trail for compliance

Decide what may leave the host

Send the records to a collector

The questions the trail answers

Integrity and access

Sizing the trail

Where the trail can mislead

​Decide what may leave the host

​Send the records to a collector

​The questions the trail answers

​Integrity and access

​Sizing the trail

​Where the trail can mislead

​Related pages

Decide what may leave the host

Send the records to a collector

The questions the trail answers

Integrity and access

Sizing the trail

Where the trail can mislead

Related pages