Ctrlk

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 ./mylogs.log -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /dev:/dev -v /home/ubuntu:/home/ubuntu --name sandbox_exec -- /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-04-02T09:19:00.088321982Z  INFO main acoustic::connector: acoustic/src/connector.rs:33: Using socket paths: "/run/bluerock/sensor.sock", None, None
2026-04-02T09:19:00.089577704Z  INFO main libgyro: /builds/bedrocksystems/bru/uc/services/libgyro/src/lib.rs:60: Creating libgyro engine with the following config:
{
  "rules": {
    "brace/exec": {
      "enabled": true,
      "content": "",
      "used_events": null
    }
  },
  "data": {
    "bluerock": {
      "brace": {
        "config": {
          "exec": {
            "remediate": true,
            "explicit_deny_list": true,
            "match_list": [
              "/usr/bin/date",
              "/usr/bin/whoami",
              "/usr/bin/uptime"
            ]
          }
        }
      }
    }
  }
}
2026-04-02T09:19:00.089761773Z  INFO main brace::runtime::common::opts: brace/src/runtime/common/opts.rs:126: Final opts after CLI overrides - user: None, pid_ns: true, user_ns: false, bind_mount: true allow privileged: true
2026-04-02T09:19:00.090386678Z  INFO main brace: brace/src/main.rs:674: Test: child pid=298632
2026-04-02T09:19:00.090812Z  WARN main brace: brace/src/main.rs:738: Running in ROOTLESS mode: Capabilities are namespaced. CAP_NET_RAW will NOT work for raw sockets (ping will fail).
2026-04-02T09:19:00.091287125Z  INFO main brace::capability: brace/src/capability.rs:127: Ambient capabilities (will survive exec): [CAP_SYS_ADMIN, CAP_NET_RAW]
2026-04-02T09:19:00.092571742Z  INFO main brace::capability: brace/src/capability.rs:174: Dropped CAP_SYS_ADMIN capability after mount operations
2026-04-02T09:19:00.092592104Z  INFO main brace::capability: brace/src/capability.rs:199: Dropped temporal capabilities: network=false, mount=true, setuid=false

Viewing Sandbox Logs

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

To view the entire log file:

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

Log entries are time-stamped and indicate whether an execution attempt was permitted or blocked based on the configured policy.

Example remediate: false:

Observe mode when execution is permitted with remediate: false is set, the log records a warning but allows the process to continue.

Example remediate: true:

Enforcement mode when execution is blocked with remediate: true is set, the log records an error and indicates the process was stopped.

OpenTelemetry (OTEL) Event Collection

The BlueRock Sandbox (brace) integrates with a local OTEL collector to export runtime telemetry, execution events, and policy violations (e.g., blocked execution attempts). When a sandbox is launched, events are routed through the BlueRock sensor socket to the local OTEL collector.

  1. Verify Local OTEL Services Before running the sandbox, ensure the OTEL Collector and BlueRock control plane are actively running on the host node.

    Expected output:

  2. Trigger Sandbox Telemetry Run a sandboxed application to generate runtime telemetry. For example, executing the MCP file server with the required BlueRock bind mounts will automatically stream startup and runtime events to the collector.

  3. View Sandbox Events in the Local Collector Check the local OTEL collector logs to verify that the sandbox execution events were successfully received and processed.

    Expected output:

Advanced OpenTelemetry (OTEL) Event Routing

Understanding the OTEL Data Flow

Standard sandbox execution logs reside locally in BRace_rCURRENT.log. The OpenTelemetry (OTEL) Collector does not store execution events locally. The local otel-collector container 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 docker logs otel-collector 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. Select the relevant deployment environment below for specific querying instructions:

Viewing Events in Google Cloud Platform (GCP)

During GCP deployments, the BlueRock OTEL collector uses the googlecloud exporter defined in /opt/bluerock/otel/otel-config.yaml.

  • Destination: Google Cloud Logging

  • Enrichment: The resourcedetection processor automatically tags events with the corresponding GCP Project ID, Zone, and Instance Name.

Querying the Logs in GCP:

  1. Access the Google Cloud Console.

  2. Navigate to Logging > Logs Explorer.

  3. Ensure the active project selected in the top navigation bar matches the deployment environment.

  4. By default, the Logs Explorer displays events for All log names. To filter exclusively for BlueRock telemetry, locate the LQL (Logging query language) text box.

  5. Enter the following query string, replacing the placeholder with the actual project ID:

  6. Click Run query to apply the filter and display the telemetry pipeline output.

Example of OTEL Event Payload (GCP)

Exported OpenTelemetry events use structured JSON payloads for straightforward SIEM ingestion. Below is an example of an enforced policy violation (a blocked execution attempt) found within Google Cloud Logging:

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 Debug 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. View the Local Events Trigger a sandboxed application event. The structured JSON payload will now print directly to the container's standard output. Use standard Docker logging commands to view the events:

    Expected output:

PreviousBlueRock SandboxNextUnderstanding BlueRock Sandbox Policies

Last updated