> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.eorlov.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[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:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://filetrace.eorlov.org/integrations/telemetry-reference.md#log-record-attributes).

## The questions the trail answers

```logql theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](https://filetrace.eorlov.org/use-cases/overview.md).

## 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](https://filetrace.eorlov.org/reference/security.md).
* **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](https://filetrace.eorlov.org/integrations/opentelemetry.md) — settings, delivery and retries.
* [Metrics and attributes reference](https://filetrace.eorlov.org/integrations/telemetry-reference.md) — every record field.
* [Security model](https://filetrace.eorlov.org/reference/security.md)
* [Observability recipes](https://filetrace.eorlov.org/integrations/observability-recipes.md) — collector routing and joins.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.