Understanding BlueRock Sandbox Policies

The BlueRock Sandbox operates based on a structured JSON policy file. This configuration file acts as the central source of truth for the sandbox environment, dictating exactly what applications can execute, how file systems are mounted, what privileges are granted, and how network traffic is routed.

The policy file resides at /opt/bluerock/trex with filename bru_policy.json .

Policy Structure Overview

A standard sandbox policy is divided into three primary blocks:

1. exec: Controls binary execution permissions and remediation logic.

2. options: Defines runtime environments, user privileges, and namespace isolation.

3. network: Governs internal routing and firewall configurations.

Below is a reference template of a foundational policy configuration:

bru_policy.json

{
  "brace": {
    "exec": {
      "enable": false,
      "remediate": false,
      "explicit_deny_list": false,
      "match_list": []
    },
    "options": {
      "bind_mount": {
        "enable": false,
        "mount_proc": true,
        "mounts": []
      },
      "user": "",
      "pid_ns": true,
      "user_ns": false,
      "allow_privileged": false
    },
    "network": {
      "enable": false,
      "general": {
        "bridge": "<bridge-name>",
        "gateway": "<gateway-address>"
      },
      "firewall": {}
    }
  }
}

Execution Control (exec)

The exec block is responsible for the Allow/Deny logic of binary execution within the container.

Parameter	Type	Description
enable	Boolean	Toggles the execution control feature on or off.
remediate	Boolean	Determines the response to a violation. false logs a warning (Observe Mode); true blocks the execution (Enforcement Mode).
explicit_deny_list	Boolean	Changes the interpretation of the match_list between an allow-list (false) and a deny-list (true).
match_list	Array	A list of file paths (supports wildcards) used to evaluate execution permissions.

Policy Execution

Executing policy is governed by a true/false logic within the BlueRock Sandbox policy. Toggling the explicit_deny_list setting determines how the match_list is interpreted.

Mode	explicit_deny_list	match_list Content	Resulting Behavior
Strict Allow-List	false	["<dir_path>/**"]	Only programs in the given path are allowed.
Block All	false	[] (Empty)	Nothing is allowed to run.
Selective Deny-List	true	["**/<cmd>"]	Everything runs except the specified command.
Permissive	true	[] (Empty)	Everything is allowed to run.

Note:

The match_list supports wildcards. For example, ["**/wh*"] matches both the whoami and which commands.

Runtime Options (options)

The options block manages system-level isolation, file system access, and user privileges.

Parameter	Type	Description
bind_mount	Object	Controls host-to-container directory mapping. Contains sub-parameters to enable mounts, control /proc visibility (mount_proc), and define specific volume paths (mounts).
user	String	Specifies the default user context under which the containerized application runs.
pid_ns	Boolean	Enables (true) or disables (false) PID namespace isolation, creating a private process tree for the sandbox.
user_ns	Boolean	Toggles Linux user namespace mapping for enhanced privilege isolation.
allow_privileged	Boolean	Grants extended system capabilities to the root user within the sandbox when set to true.

Network Configuration (network)

The network block defines how the sandbox interacts with internal and external networks.

Parameter	Type	Description
enable	Boolean	Activates or deactivates custom network isolation.
general	Object	Defines foundational network routing, including the virtual bridge interface (e.g., bru0) and the default gateway IP address.
firewall	Object	Contains the detailed ingress, egress, and protocol rules defining allowed traffic.

Policy-Driven Configuration Examples

Centralizing security logic within the policy file reduces manual input errors and ensures consistent enforcement across environments.

Binary Execution: Allow and Deny Lists

The exec block controls which binaries can run inside the sandbox.

• Allow List Strategy (Whitelist) This is the recommended configuration for high-security environments. It ensures that only trusted system paths can execute. Any binary located outside these paths (e.g., in /tmp or /home) will be blocked by default. Configuration: explicit_deny_list: Set to false.

bru_policy.json

"exec": {
    "enable": true,
    "remediate": true,
    "explicit_deny_list": false,
    "match_list": [
        "/usr/bin/printenv"
        "/usr/bin/sudo",
        "/usr/bin/su",
        "/usr/bin/mount",
    ]
}

Executing a command which is not part of match list:

$ brace --name Sandbox -- /usr/bin/bash
ubuntu@Sandbox:/$ /usr/bin/whoami

Expected Output (if remediate: true):

bash: /usr/bin/whoami: Operation not permitted

Executing a match list command:

$ brace --name Sandbox -- /usr/bin/bash
ubuntu@Sandbox:/$ /usr/bin/mount

Expected Output (if remediate: true):

/dev/sda1 on / type ext4 (rw,relatime,discard,errors=remount-ro,commit=30)
/dev/sda1 on /etc/passwd type ext4 (ro,relatime,discard,errors=remount-ro,commit=30)
/dev/sda1 on /etc/group type ext4 (ro,relatime,discard,errors=remount-ro,commit=30)

Executing a command which is not part of match list:

$ brace --name Sandbox -- /usr/bin/bash
ubuntu@Sandbox:/$ /usr/bin/whoami

Expected Output (if remediate: false):

ubuntu

Deny List Strategy (Blacklist) This configuration allows for broader execution but targets specific dangerous binaries for exclusion. This is useful when the application requires access to various libraries but must be prevented from using tools that could lead to privilege escalation. Configuration:

• • explicit_deny_list: Set to true.

bru_policy.json

"exec": {
    "enable": true,
    "remediate": false,
    "explicit_deny_list": true,
    "match_list": [
        "/usr/bin/printenv"
        "/usr/bin/sudo",
        "/usr/bin/su",
        "/usr/bin/mount",
        "/usr/bin/umount"
    ]
}

Execution:

$ brace --name Sandbox -- /usr/bin/bash
$ /usr/bin/printenv

Expected Output (if remediate: true):

bash: /usr/bin/printenv: Operation not permitted

Expected Output (if remediate: false):

SHELL=/bin/bash
BRU_COMPONENT_ID=<id-string>
PWD=/
LOGNAME=ubuntu
XDG_SESSION_TYPE=tty
_=/usr/bin/printenv
HOME=/home/ubuntu
LANG=C.UTF-8
LS_COLORS=rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:or=40;31;01:mi=00:su=37;41:sg=30;43:ca=00:tw=30;42:ow=34;42:st=37;44:ex=01;32:*.tar=01;31:*.tgz=01;31:*.arc=01;31:*.arj=01;31:*.taz=01;31:*.lha=01;31:*.lz4=01;31:*.lzh=01;31:*.lzma=01;31:*.tlz=01;31:*.txz=01;31:*.tzo=01;31:*.t7z=01;31:*.zip=01;31:*.z=01;31:*.dz=01;31:*.gz=01;31:*.lrz=01;31:*.lz=01;31:*.lzo=01;31:*.xz=01;31:*.zst=01;31:*.tzst=01;31:*.bz2=01;31:*.bz=01;31:*.tbz=01;31:*.tbz2=01;31:*.tz=01;31:*.deb=01;31:*.rpm=01;31:*.jar=01;31:*.war=01;31:*.ear=01;31:*.sar=01;31:*.rar=01;31:*.alz=01;31:*.ace=01;31:*.zoo=01;31:*.cpio=01;31:*.7z=01;31:*.rz=01;31:*.cab=01;31:*.wim=01;31:*.swm=01;31:*.dwm=01;31:*.esd=01;31:*.avif=01;35:*.jpg=01;35:*.jpeg=01;35:*.mjpg=01;35:*.mjpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:*.mkv=01;35:*.webm=01;35:*.webp=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:*.cgm=01;35:*.emf=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=00;36:*.au=00;36:*.flac=00;36:*.m4a=00;36:*.mid=00;36:*.midi=00;36:*.mka=00;36:*.mp3=00;36:*.mpc=00;36:*.ogg=00;36:*.ra=00;36:*.wav=00;36:*.oga=00;36:*.opus=00;36:*.spx=00;36:*.xspf=00;36:*~=00;90:*#=00;90:*.bak=00;90:*.crdownload=00;90:*.dpkg-dist=00;90:*.dpkg-new=00;90:*.dpkg-old=00;90:*.dpkg-tmp=00;90:*.old=00;90:*.orig=00;90:*.part=00;90:*.rej=00;90:*.rpmnew=00;90:*.rpmorig=00;90:*.rpmsave=00;90:*.swp=00;90:*.tmp=00;90:*.ucf-dist=00;90:*.ucf-new=00;90:*.ucf-old=00;90:

Running Python MCP Server and MCP Client

To run Python MCP Server and MCP Client in BlueRock Sandbox an MCP setup is required:

1. Install uv :

$ curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Project Directory Create a new project directory for the MCP applications and navigate into it:

$ cd ~
$ uv init mcp-observability
$ cd mcp-observability

3. Install Required Dependencies Create an isolated Python environment using uv, then install the MCP framework, BlueRock sensor, and BlueRock runtime required for generating and exporting telemetry:

# Create virtual environment
$ uv venv --python python3.12

# Activate virtual environment
$ source .venv/bin/activate

# Install MCP framework
$ uv pip install fastmcp

# Install BlueRock runtime
$ uv pip install /opt/bluerock/python-dist/bluepython-0.0.1-py3-none-any.whl

# Initialize BlueRock sensor
$ python -m bluepython --install

4. Add MCP Application Files Create the MCP client and server scripts in the project directory using the sample code provided in the Appendix section. Ensure the following files are present in the mcp-observability directory:

• mcp_client.py

• mcp_fileserver.py

• mcp_fileserver_stdio.py

Defining Mounts to run the MCP Server and Client

Defining mount points directly within the bru_policy.json file under the options.bind_mount block eliminates the requirement for extensive -v arguments in the Command Line Interface (CLI).

bru_policy.json

{
  "brace": {
    "options": {
      "bind_mount": {
        "enable": true,
        "mounts": [
          {"host": "/usr", "sandbox": "/usr", "read_only": true},
          {"host": "/lib", "sandbox": "/lib", "read_only": true},
          {"host": "/lib64", "sandbox": "/lib64", "read_only": true},
          {"host": "/etc/resolv.conf", "sandbox": "/etc/resolv.conf", "read_only": true},
          {"host": "/dev", "sandbox": "/dev", "read_only": false},
          {"host": "/home/ubuntu", "sandbox": "/home/ubuntu", "read_only": false}
        ]
      }
    }
  }
}

Important:

Modifications to bru_policy.json require a complete policy update to take effect. This process involves extracting the tarball, generating a new signature via trex.py, and uploading the repackaged files. Refer to the Understanding BlueRock Sandbox Policies for detailed instructions.

With file mounts pre-configured in the policy, the system allows for the direct execution of the MCP client or server without additional volume flags.

Terminal 1:

Starting the MCP Server Launch the sandbox and execute the Python server script:

$ brace --name mcp_server -- /home/ubuntu/.local/bin/uv run mcp_fileserver.py

Expected Output:

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│                                                                              │
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                                                              │
│                                                                              │
│                                FastMCP 3.1.0                                 │
│                            https://gofastmcp.com                             │
│                                                                              │
│                   🖥  Server:      Linux File Server, 3.1.0                   │
│                   🚀 Deploy free: https://fastmcp.cloud                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯
[03/12/26 04:42:11] INFO     Starting MCP server 'Linux File    transport.py:273
                             Server' with transport 'http' on                   
                             http://0.0.0.0:8001/mcp                            
INFO:     Started server process [9]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Terminal 2:

Starting the MCP Client Open a separate terminal and launch a second sandbox to execute the client script:

$ brace --name mcp_client -- /home/ubuntu/.local/bin/uv run mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-test-token tools --list

Running an Imported Container Image

Once the image is imported, you can launch it using the --image flag alongside standard BlueRock Sandbox execution controls. This execution method provides a fully isolated application layer. Following is example to update in the policy to run the imported image.

bru_policy.json

{
  "brace": {
    "options": {
      "bind_mount": {
        "enable": true,
        "mounts": [
          {"host": "/var/log/myapp", "sandbox": "/app/logs", "read_only": false}
        ]
      }
    }
  }
}

Important:

Modifications to bru_policy.json require a complete policy update to take effect. This process involves extracting the tarball, generating a new signature via trex.py, and uploading the repackaged files. Refer to the Understanding BlueRock Sandbox Policies for detailed instructions.

For execution:

$ sudo brace --image docker.io/library/langchain-mcp-server:v1 --name test-langchain -- python3 /app/main.py

Network Control: Ingress and Egress

Network profile define how a program running inside the sandbox connects to external network services. These are referenced via the --network-config flag but configured within the policy.

• Egress (Outbound): Allows programs in sandbox to reach external network service.

  parameters - IP, Port Protocol

  For example: An agent program running inside sandbox is restricted to access specific LLM provider.

• Ingress (Inbound): Allows in bound connections from specific host to the server program running inside the sandbox on specific port and protocol

  For example: Allows an MCP client program from specific source address to connect to MCP server program running on specific port

bru_policy.json

"network": {
    "enable": true,
    "general": { "bridge": "bru0", "gateway": "10.0.0.1", "dns": ["8.8.8.8"] },
    "firewall": {
        "config1": {
            "options": { "allow_icmp": true, "log_drops": true },
            "ingress": {
                "allow_from": ["172.17.0.0/24"],
                "published_ports": [{ "container_port": "8002", "host_bindings": [{ "host_ip": "127.0.0.1", "host_port": "8002" }] }]
            },
            "egress": {
                "allow_to": [
                    { "addr": "127.0.0.1/32", "ports": [53], "proto": ["tcp", "udp"] },
                    { "addr": "10.0.0.0/24", "ports": [53], "proto": ["tcp", "udp"] },
                    { "addr": "8.8.8.8", "ports": [], "proto": ["tcp", "udp"] },
                    { "addr": "www.google.com", "ports": [], "proto": [] },
                ]
            }
        },        
    }
}

Important:

Modifications to bru_policy.json require a complete policy update to take effect. This process involves extracting the tarball, generating a new signature via trex.py, and uploading the repackaged files. Refer to the Understanding BlueRock Sandbox Policies for detailed instructions.

Note:

Any changes to the network policy in BlueRock Sandbox require restarting the uc-docker.service.

$ sudo systemctl restart uc-docker.service

For execution:

$ brace --name test-egress --network-config config1 -- /usr/bin/curl -k --resolve www.google.com:443:142.251.157.119 -I https://www.google.com

Expected Output:

HTTP/2 200 
content-type: text/html; charset=ISO-8859-1
content-security-policy-report-only: object-src 'none';base-uri 'self';script-src 'nonce-K-RT81bShypKUTDgFRqscQ' 'strict-dynamic' 'report-sample' 'unsafe-eval' 'unsafe-inline' https: http:;report-uri https://csp.withgoogle.com/csp/gws/other-hp
accept-ch: Sec-CH-Prefers-Color-Scheme
p3p: CP="This is not a P3P policy! See g.co/p3phelp for more info."
date: Fri, 24 Apr 2026 10:49:59 GMT
server: gws
x-xss-protection: 0
x-frame-options: SAMEORIGIN
expires: Fri, 24 Apr 2026 10:49:59 GMT
cache-control: private
set-cookie: AEC=AaJma5sPiBdhvD-1LpNfg1VZ3xoB9Ke1tbTx_U-Zw6VD-IEzZy3BHkdXuA; expires=Wed, 21-Oct-2026 10:49:59 GMT; path=/; domain=.google.com; Secure; HttpOnly; SameSite=lax
set-cookie: NID=530=M0IpCekEdD_Pcqy3MuF5YtWH6P4TenQ7CgzJuzYTVe6hZ_NDXE1EQEuZFkqCagX7E0zQtsR1EzDVN-b2eh8S2U_gwuvHHa1ZgsdrIonYpRPnLyyjY6UF1miCeDBXO9e9yMZfzPgVvYOsKbe0eIKJRruTU5rdbGA8WRs8jUs_CrRlY-fDiJ7DuhmZki5PmXbNWngfwJGVZla6I9WYP-SnZBPyEtrOj80; expires=Sat, 24-Oct-2026 10:49:59 GMT; path=/; domain=.google.com; HttpOnly
set-cookie: __Secure-BUCKET=CPIF; expires=Wed, 21-Oct-2026 10:49:59 GMT; path=/; domain=.google.com; Secure; HttpOnly
cross-origin-opener-policy-report-only: same-origin; report-to="gfe-default_product_name"
report-to: {"group":"gfe-default_product_name","max_age":2592000,"endpoints":[{"url":"https://csp.withgoogle.com/csp/report-to/default_product_name"}]}

Policy Deployment Lifecycle

Applying policy changes requires a manual sign-and-upload cycle. The Sandbox uses a signed manifest to ensure security integrity; local edits to bru_policy.json will effect with the following steps:

1. Activate the signing environment:

   $ source /opt/bluerock/trex/py312/bin/activate

2. Generate the signed cryptographic archive:

   $ python trex.py bru_policy.json

3. Extract the signed policy and signature:

   $ tar xvf bru_policy.tar

4. Upload the signature to the cloud repository:

   # For AWS:
   $ aws s3 cp policy.json.sig s3://<bucket-path>/
     
   # For GCP:
   $ gcloud storage cp policy.json.sig gs://<bucket-path>/

5. Upload the policy manifest to the cloud repository:

   # For AWS:
   $ aws s3 cp policy.json s3://<bucket-path>/
   
   # For GCP
   $ gcloud storage cp policy.json gs://<bucket-path>/

6. Policy updates are applied automatically within 300 seconds (5 minutes). To enforce the new policy immediately, restart the service:

   $ sudo systemctl restart uc-docker.service

Note:

The sandbox operates on a Fail-Closed security model. If the .sig file is missing or does not match the policy.json content during the service restart, uc-docker.service will fail to initialize to prevent unverified configurations.