Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

BlueRock Sandbox Observability

The BlueRock Sandbox logs execution events and system activity to a local file. Reviewing these logs provides immediate visibility into authorized and unauthorized application behavior.

Specifying the Log File

By default, the sandbox writes all activity to a file named BRace.log (or sandbox.log depending on the alias) in the current working directory. To specify a custom location or filename, use the -l or --logfile parameter during execution.

$ brace -l ./custom_sandbox.log -v /usr:/usr:ro -v /lib:/lib:ro -v /lib64:/lib64:ro -- /usr/bin/bash

To stream logs directly to the terminal for real-time observation, specify stdout:

$ brace -l stdout -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /dev:/dev -v /home/ubuntu:/home/ubuntu --name sandbox_exec -- /usr/bin/bash

Expected output:

2026-07-06T07:40:51.382787732Z  INFO main acoustic::connector: acoustic/src/connector.rs:36: Using socket paths: "/run/bluerock/sensor.sock", None, None
2026-07-06T07:40:51.422742416Z  INFO main brace::runtime::common::opts: brace/src/runtime/common/opts.rs:167: Final opts after CLI overrides - pid_ns: true, user_ns: false
2026-07-06T07:40:51.424553402Z  INFO ThreadId(03) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:126: Starting seccomp monitoring for container PID 26068
2026-07-06T07:40:51.42484236Z  INFO main brace::capability: brace/src/capability.rs:113: Ambient capabilities (will survive exec): [CAP_NET_RAW, CAP_SYS_ADMIN]
2026-07-06T07:40:51.428134288Z  INFO main brace::capability: brace/src/capability.rs:160: Dropped CAP_SYS_ADMIN capability after mount operations
2026-07-06T07:40:51.42815227Z  INFO main brace::capability: brace/src/capability.rs:179: Dropped temporal capabilities: network=false, mount=true

Viewing Sandbox Logs

Standard Linux utilities can be used to monitor and review the generated log files.

To view the entire log file:

$ cat custom_sandbox_rCURRENT.log

Example output:

To monitor logs in real-time (follow mode):

Expected output:

notes-sticky

Note:

BlueRock Sandbox always creates a log file with <filename>_rCURRENT.log that always capture the current actions/logs happening in the sandbox. By default BRace_rCURRENT.log is present that monitors all the current logs.

Understanding Log Entries

Telemetry and monitoring logs are time-stamped entries indicating the initialization, process transitions, and structural state changes of a sandboxed instance.

When launching a workload via the standalone CLI interface, the engine utilizes a dynamic trailing format (e.g., custom_sandbox_rCURRENT.log) to record active system setups, namespace flags, and capability limits.

Runtime Logs

The stream below illustrates a focused snapshot of a successful sandbox boot sequence initialization phase:

Log Stream

  • Socket Binding (acoustic::connector): Confirms connection initialization over the host daemon path (/run/bluerock/sensor.sock) to dispatch active event tracking data blocks.

  • Namespace Overrides (brace::runtime::common::opts): Logs the final namespace configuration state (e.g., enabling isolated PID namespaces with pid_ns: true) applied to the sandbox layer after processing CLI input switches.

  • Seccomp Hook Initialization (seccomp_monitor): Indicates the runtime successfully spawned a dedicated monitoring thread (ThreadId(04)) to intercept and evaluate system calls for the container target (PID 25879).

OpenTelemetry (OTEL) Event Collection

  1. Restart the otelcol.service to load the OTEL Collector.

  2. To check the logs

Expected output:

Advanced OpenTelemetry (OTEL) Event Routing

Understanding the OTEL Data Flow

Standard sandbox execution logs reside locally in otel-events.log resides at /var/log/bluerockd. The OpenTelemetry (OTEL) Collector does not store execution events locally. The local otelcol.service acts as a telemetry pipeline. The pipeline receives raw data from the BlueRock sensor, enriches the data with cloud provider metadata, and immediately exports the data to a centralized cloud observability platform.

Checking sudo systemctl status otelcol.service only displays internal service logs, such as startup events and memory limiter configurations. Viewing actual sandbox policy violations and execution traces requires querying the configured export destination or enabling local debugging.

Viewing OTEL Events

The OTEL Collector exports telemetry data directly to the centralized observability platform of the active cloud provider.

Viewing Events in Amazon Web Services (AWS)

During AWS EC2 deployments, the BlueRock OTEL collector is configured to use the awscloudwatchlogs exporter. Successful telemetry routing requires assigning an appropriate IAM Instance Profile to the deployment node to authorize CloudWatch ingestion.

  • Destination: Amazon CloudWatch Logs

  • Enrichment: Events are automatically structured and tagged by the OpenTelemetry pipeline before ingestion.

Querying the Logs:

  1. Access the AWS Management Console.

  2. Navigate to CloudWatch > Logs > Log Management.

  3. Locate and select the log group created by the deployment (for example: bluerock-ec2-TelemetryLogGroup).

  4. Select the active log stream to view the live telemetry.

  5. Use the Filter events search bar to query for specific event types (e.g., type "process_guard_violation" to filter for blocked execution attempts).

Example OTEL Event Payload (AWS): Exported OpenTelemetry events use structured JSON payloads. Below is an example of a blocked execution attempt as it appears in CloudWatch:

Viewing Events Locally via OTEL Exporter

By default, the OTEL Collector routes telemetry data to external platforms and does not print event payloads to the local console. Viewing events directly within the otel-collector container logs requires enabling the debug exporter. The debug exporter is a built-in OTEL component designed specifically to print telemetry data directly to the local standard output. Enabling the debug exporter verifies data ingestion and allows inspection of raw JSON payloads before network transmission.

  1. Modify the OTEL Configuration Edit the configuration file located at /opt/bluerock/otel/otel-config.yaml to include the debug exporter. Add the debug exporter under the exporters section:

    Add the debug exporter to the logs pipeline under the service section:

  2. Apply the Configuration Restart the OpenTelemetry Collector container to apply the new pipeline configuration:

  3. To check the logs

Expected output:

Sandbox Telemetry Event Profiles

All acoustic telemetry events emitted by the brace-shim (io.containerd.bluerock.v2) or the standalone CLI sandbox are passed over the Unix domain socket (/run/bluerock/sensor.sock) to the host daemon for immediate policy evaluation and logging.

Event Catalog Summary

Event Name
Trigger Syscall(s)
Trigger Condition
Mode Support

brace_exec

execve, execveat

Any execution of a binary file inside the container sandbox.

CLI, Shim

brace_mmap_exec

mmap, execve, execveat

mmap called with PROT_EXEC or execution targeting an in-memory memfd.

CLI, Shim

brace_file_open

open, openat

Any file open operation (read-only opens can be filtered out via policy).

CLI, Shim

brace_socket

socket

Socket initialization inside the sandbox boundary.

CLI, Shim

brace_connect

connect

Network egress or internal Unix socket connection attempts.

CLI, Shim

brace_delete

unlink, unlinkat, rmdir

File or directory deletions inside the container sandbox.

CLI, Shim

brace_suspicious_syscall

unshare, ptrace

Blockable container-escape or process-injection attempts.

CLI, Shim

brace_process_terminate

exit, exit_group

Voluntary termination of a sandboxed process.

CLI, Shim

The Common Event Envelope

To prevent redundant indexing, all telemetry events (except sensor_startup and brace_process_terminate) share an identical foundational metadata wrapper created by runtime/common/mod.rs. Event-specific payloads are merged directly at the top level alongside these parameters:

Common Wrapper Field Dictionary

  • meta.source_event_id (integer): The seccomp notify request identifier (request ID % i64::MAX).

  • context.process.comm (string): Short executable name extracted directly from /proc/<pid>/comm.

  • context.process.file_path (string): Absolute host-resolved filesystem path extracted from /proc/<pid>/exe.

  • context.process.pid (integer): Process ID executing the intercepted syscall.

  • context.cwd (string): Current working directory extracted from /proc/<pid>/cwd.

brace_process_exec

Fired on container process spawning loops. Policy rules can explicitly flag exec.remediate = true to drop execution.

  • Payload Fields:

    • file_path (string): Target absolute path of the binary being executed inside the namespace.

    • args (array of strings): The argv parameter array (capped at a maximum of 32 entries).

    • env (array of strings): The envp context array expressed as standard KEY=VALUE pairs (capped at 32 entries).

brace_mmap_exec

Tracks executable mappings. Used specifically to catch JIT engines, dynamic shared object loads, or in-memory fileless executions targeting memory file descriptors.

  • Payload Fields:

    • file_path (string): Path mapped from the file descriptor (e.g., /memfd:payload or /usr/lib/libc.so.6). Returns an empty string for anonymous space mappings.

    • is_memfd (boolean): Evaluates to true if file_path initiates with a /memfd: prefix, signifying fileless injection.

    • prot (integer): Protection mask integer passed to mmap (defaults to 0 for pure memfd execution traps).

    • fd (integer): The integer file descriptor index being mapped (-1 indicates an anonymous segment).

brace_file_open

Tracks interaction with the filesystem. Read-only noise can be filtered early by toggling open.allow_read_only = true inside the active policy.

  • Payload Fields:

    • file_path (string): Absolute path of the targeted resource resolved inside the process namespace.

    • flags (integer): Raw O_* access mode bitmask flags passed directly to the kernel layer.

    • is_writeable (boolean): Evaluates to true if flags & O_ACCMODE resolves to write-access formats (e.g., O_WRONLY, O_RDWR).

    • is_link / is_dir / is_fifo / is_socket (boolean, nullable): Evaluates file node types from a fallback stat evaluation. Returns null if the underlying node check fails.

brace_socket

Fired when any low-level socket interface initialization occurs inside the sandbox parameters.

  • Payload Fields:

    • domain (integer): The numeric mapping for the AF_* address family (e.g., 1 = UNIX, 2 = INET, 10 = INET6, 16 = NETLINK).

    • socket_type (integer): The type constraints (1 = SOCK_STREAM, 2 = SOCK_DGRAM, 3 = SOCK_RAW).

    • protocol (integer): Target protocol assignments (0 handles standard domain/type automatic assignment).

brace_connect

Intercepts stream destination establishment. The raw sockaddr buffer is decoded directly from the container memory tracking maps.

  • Payload Fields:

    • sockfd (integer): The host file descriptor index mapped to the socket being connected.

    • addr_family (integer): Extracted sockaddr family enum (1 = Unix pathing, 2 = IPv4, 10 = IPv6).

    • addr (string): Formatted target destination address (e.g., 1.2.3.4:443, [::1]:80, or unix:/run/bluerock/sensor.sock).

brace_delete

Tracks file removals. This event acts strictly in observation mode and cannot be mathematically blocked at the seccomp layer.

  • Payload Fields:

    • file_path (string): Target absolute path being unlinked or removed.

    • is_dir (boolean): Resolves to true if initiated via an rmdir syscall or an unlinkat execution carrying the AT_REMOVEDIR parameter flag.

brace_suspicious_syscall

Triggers immediately when operations linked to container escape vectors or low-level process memory modifications are caught. Controlled directly via suspicious_syscalls.allow_unshare and suspicious_syscalls.allow_ptrace.

  • Payload Fields:

    • syscall (string): The string identification of the trapped call (explicitly restricts "unshare" or "ptrace").

brace_process_terminate

Fired on standard clean process termination flows. Because it intercepts the process before it completes its cleanup via seccomp sync points, process names remain entirely readable.

notes-sticky

Note:

This event purposefully omits the common context object block. Its flat structure directly mimics the native kernel-level process_terminate schema, allowing uniform parsing logic to ingest exits identically, regardless of whether they originate from the host kernel sensor or the container runtime shim.

  • Payload Fields:

    • pid (integer): The process identifier exiting the sandbox environment.

    • comm (string): The short process text identifier captured from /proc/<pid>/comm.

    • exit_code (integer): Numeric status return value passed to the exit() / exit_group() routine.

    • exit_signal (integer): Always returns 0. Workloads explicitly terminated by unhandled kernel signals (e.g., SIGKILL) bypass seccomp and will not record a termination metric here.

Running Hardened Containers via Native containerd CLI

If your environment interacts directly with the lower-level containerd engine layer bypassing the Docker engine wrapper, utilize the native ctr tool formatting:

PreviousBlueRock Sandbox
NextUnderstanding BlueRock Sandbox Policies

Last updated