> For the complete documentation index, see [llms.txt](https://docs.bluerock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bluerock.io/bluerock-sandbox/understanding-bluerock-sandbox-policies.md). # 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`](#execution-control-exec): Controls binary execution permissions and remediation logic. 2. [`options`](#runtime-options-options): Defines runtime environments, user privileges, and namespace isolation. 3. [`network`](#network-configuration-network): Governs internal routing and firewall configurations. Below is a reference template of a foundational policy configuration: {% code title="bru\_policy.json" overflow="wrap" lineNumbers="true" %} ```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": "", "gateway": "" }, "firewall": {} } } } ``` {% endcode %} #### 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` | `["/**"]` | Only programs in the given path are allowed. | | Block All | `false` | `[]` (Empty) | Nothing is allowed to run. | | Selective Deny-List | `true` | `["**/"]` | Everything runs except the specified command. | | Permissive | `true` | `[]` (Empty) | Everything is allowed to run. | {% hint style="info" icon="notes-sticky" %} **Note:** The `match_list` supports wildcards. For example, `["**/wh*"]` matches both the `whoami` and `which` commands. {% endhint %} #### 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`. {% code title="bru\_policy.json" lineNumbers="true" %} ```json "exec": { "enable": true, "remediate": true, "explicit_deny_list": false, "match_list": [ "/usr/bin/printenv" "/usr/bin/sudo", "/usr/bin/su", "/usr/bin/mount", ] } ``` {% endcode %} 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`): ```shellscript bash: /usr/bin/whoami: Operation not permitted ``` Executing a match list command: ```shellscript $ brace --name Sandbox -- /usr/bin/bash ubuntu@Sandbox:/$ /usr/bin/mount ``` Expected Output (if `remediate: true`): ```shellscript /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`. {% code title="bru\_policy.json" overflow="wrap" lineNumbers="true" %} ```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" ] } ``` {% endcode %} Execution: ```shellscript $ brace --name Sandbox -- /usr/bin/bash $ /usr/bin/printenv ``` Expected Output (if `remediate: true`): ```shellscript bash: /usr/bin/printenv: Operation not permitted ``` Expected Output (if `remediate: false`): ```shellscript SHELL=/bin/bash BRU_COMPONENT_ID= 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` : ```shellscript $ 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: ```shellscript $ 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: ```shellscript # 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](/glossary/appendix.md). Ensure the following files are present in the `mcp-observability` directory: * [`mcp_client.py`](/glossary/appendix.md#mcp-client-script-python) * [`mcp_fileserver.py`](/glossary/appendix.md#mcp-file-server-http-python) * [`mcp_fileserver_stdio.py`](/glossary/appendix.md#mcp-file-server-stdio-python) **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). {% code title="bru\_policy.json" overflow="wrap" lineNumbers="true" %} ```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} ] } } } } ``` {% endcode %} {% hint style="success" icon="lightbulb-exclamation-on" %} **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](/bluerock-sandbox/understanding-bluerock-sandbox-policies.md#policy-deployment-lifecycle) for detailed instructions. {% endhint %} 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: {% code overflow="wrap" %} ```shellscript $ brace --name mcp_server -- /home/ubuntu/.local/bin/uv run mcp_fileserver.py ``` {% endcode %} Expected Output: ```shellscript ╭──────────────────────────────────────────────────────────────────────────────╮ │ │ │ │ │ ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█ │ │ █▀ █▀█ ▄▄█ █ █ ▀ █ █▄▄ █▀▀ │ │ │ │ │ │ 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: {% code overflow="wrap" %} ```shellscript $ 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 ``` {% endcode %} #### 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. {% code title="bru\_policy.json" overflow="wrap" lineNumbers="true" %} ```json { "brace": { "options": { "bind_mount": { "enable": true, "mounts": [ {"host": "/var/log/myapp", "sandbox": "/app/logs", "read_only": false} ] } } } } ``` {% endcode %} {% hint style="success" icon="lightbulb-exclamation-on" %} **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](/bluerock-sandbox/understanding-bluerock-sandbox-policies.md#policy-deployment-lifecycle) for detailed instructions. {% endhint %} For execution: {% code overflow="wrap" %} ```shellscript $ sudo brace --image docker.io/library/langchain-mcp-server:v1 --name test-langchain -- python3 /app/main.py ``` {% endcode %} #### **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 {% code title="bru\_policy.json" overflow="wrap" lineNumbers="true" %} ```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": [] }, ] } }, } } ``` {% endcode %} {% hint style="success" icon="lightbulb-exclamation-on" %} **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](/bluerock-sandbox/understanding-bluerock-sandbox-policies.md#policy-deployment-lifecycle) for detailed instructions. {% endhint %} {% hint style="info" icon="notes-sticky" %} **Note:** Any changes to the network policy in BlueRock Sandbox require restarting the `uc-docker.service`. ```shellscript $ sudo systemctl restart uc-docker.service ``` {% endhint %} For execution: ```shellscript $ 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: ```shellscript 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: ```shellscript $ source /opt/bluerock/trex/py312/bin/activate ``` 2. Generate the signed cryptographic archive: ```shellscript $ python trex.py bru_policy.json ``` 3. Extract the signed policy and signature: ```shellscript $ tar xvf bru_policy.tar ``` 4. Upload the signature to the cloud repository: ```shellscript # For AWS: $ aws s3 cp policy.json.sig s3:/// # For GCP: $ gcloud storage cp policy.json.sig gs:/// ``` 5. Upload the policy manifest to the cloud repository: ```shellscript # For AWS: $ aws s3 cp policy.json s3:/// # For GCP $ gcloud storage cp policy.json gs:/// ``` 6. Policy updates are applied automatically within **300 seconds (5 minutes)**. To enforce the new policy immediately, restart the service: ```shellscript $ sudo systemctl restart uc-docker.service ``` {% hint style="info" icon="notes-sticky" %} **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. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bluerock.io/bluerock-sandbox/understanding-bluerock-sandbox-policies.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.