maf-sandbox-otel

Experimental. The API may change without notice. Importing the package emits MafSandboxOtelExperimentalWarning.

Record sandbox activity with OpenTelemetry logs, spans and metrics. The observer reports acquisition, host-tool calls, file transfers, process observations, network decisions and cleanup.

The package depends on maf-sandbox and the OpenTelemetry API. The application configures the SDK, exporters and retention. Without an SDK provider, the API uses its no-op implementation.

pip install maf-sandbox-otel

Wiring

Register the observer on both the router and host-tool registry. Each registration covers a different set of events.

from maf_sandbox import HostToolRegistry, SandboxRouter
from maf_sandbox_otel import OpenTelemetrySandboxObserver

observer = OpenTelemetrySandboxObserver()

router = SandboxRouter([backend], observer=observer)
registry = HostToolRegistry(observer=observer)

Kinds using collect_outputs pass observer= and key= to that function. The observer records existing events; it does not change tool policy or the labels on returned content.

Provider arguments default to the application's global providers. Supply a separate provider to route a signal elsewhere:

observer = OpenTelemetrySandboxObserver(
    logger_provider=security_logs,   # a SIEM pipeline, its own exporter and retention
    tracer_provider=None,            # spans stay with the application's traces
)

logger_provider, tracer_provider and meter_provider are independent. A separate audit logger can retain records even when the application samples out traces. Log export still depends on that provider's own configuration and delivery.

Recorded signals

Each row emits a log and a span. Store reads use an instant span. Process snapshots also emit one sandbox.process.observed log per process, without a per-process span or metric label.

Attributes use the maf_sandbox.* namespace, with process.* fields for process details. The event guide describes each event and its limits.

Sensitive data

record_sensitive_data=False is the default. Configuration, counts, sizes, outcomes and integrity labels are recorded. Model- or guest-chosen text and identifying host strings are omitted.

Hashes are not secrets. Small identifier spaces can be recovered by hashing candidates. The host must choose a telemetry destination and retention policy suitable for the data it permits.

The exported attributes are a selection from each event. They do not include every SandboxSpec field or ToolCallEnded.fed. A custom observer can read those fields directly.

Correlation and trace shape

Use maf_sandbox.call.id to join events from one tool call. A conversation-scoped sandbox key can be shared by several concurrent calls.

maf_sandbox.sandbox.call_id normally comes from a call-scoped key. On an output-collection record, it carries the collector's artifact call ID instead. Use maf_sandbox.call.id to identify the call that performed that collection.

Purge records join through maf_sandbox.sandbox.conversation, since they describe a conversation and a backend's count, not individual keys. A tool-call record touching several keys uses aligned lists for their attributes.

Observation limits

Docker and WSLC report attributable proxy windows after removal confirms the proxy is gone. ACAS and Hyperlight report no egress decisions. Even an observing backend can have missing, unreadable, truncated or undrained windows. No egress record does not mean no traffic.

Process snapshots are bounded observations made inside the guest. Collection errors and truncation are explicit. They do not prove complete cleanup. See process observations.

Cost and failures

Callbacks run synchronously on the caller's event loop or worker thread. The observer keeps no per-call state and hands records to the OpenTelemetry API. Blocking export can still delay the sandbox call.

Use batch span and log processors when latency matters. Simple processors invoke exporters synchronously. Each signal is attempted independently, so an ordinary span-export failure does not prevent log or metric attempts.

Core contains and logs ordinary observer failures, including observer cancellation. SystemExit and KeyboardInterrupt remain host control flow and escape. The observer's return value cannot change the tool result.