# Introduction to BlueRock AI agents don't just respond to prompts. They call tools, access data, execute code, and interact with MCP servers. Most organizations have no visibility into what those agents actually do at runtime. And no way to stop a dangerous action before it executes. We scanned over 7,000 MCP servers. 36.7% have potential SSRF exposure. 42% expose credentials insecurely. The pattern is familiar. Adoption outpaces security. We've seen it before with containers, APIs, and open source dependencies. Now it's happening with agentic infrastructure. The difference is these MCP servers don't just store data. They define the tools your agent can use and how those tools behave. If the server is compromised or misconfigured, your API keys, your data, and your tool permissions can all be exposed. BlueRock solves this at the execution layer. Not at the prompt. Not at the network edge. At runtime, where agents actually take action. This guide will walk you through both sides of what BlueRock provides: **Observability:** Runtime visibility that shows you exactly what your agents are doing and why. You'll trace the full lifecycle of MCP interactions in CloudWatch, from the initial server-client handshake through tool discovery, individual tool calls, and server responses. Every MCP action is logged and searchable. You'll see exactly which tools were available, which ones were called, and whether the call succeeded or failed. **Guardrails:** Pre-execution controls that govern what your agents are allowed to do. You'll use the MCP Trust Registry to review the security posture of an MCP server, then generate and deploy a policy using BlueRock's policy tooling. You'll see what happens when an agent calls a tool that violates that policy, first as a WARN alert, then in full remediate mode where the action gets blocked. You'll also see BlueRock's Brace sandbox, an isolated execution environment with its own set of controls for commands and file operations. Because you can't trust what you can't see. And you can't secure what you can't observe.The BlueRock Agent Sandbox – BRACE (BlueRock Agent Control Environment) – is an isolated execution runtime designed to contain autonomous AI agents. Unlike traditional containers, BRACE provides process and filesystem level isolation with deep Model Context Protocol (MCP) visibility. ### Introduction to the Agentic Observability Sandbox The BRACE sandbox is designed to provide visibility of all agent process executions, filesystem accesses and pythonic MCP events to give developers observability into their agent execution. Any agent can run inside the sandbox, but MCP events are currently supported for Python only (support for Typescript and JavaScript is coming soon). \ \ BRACE is offered as a free product for observability of agent events and tool calls and process isolation. The product also offers guardrail control capabilities for the MCP tool calls and filesystem access via a paid license. **Key Capabilities:** * **Observability:** Provides event tracing for agent and associated process activity * **Process Isolation:** Runs agents in separate process ID (PID) namespaces. * **Filesystem Isolation:** Restricts host directory access via granular bind mounts. * **Network Isolation:** Blocks or limits outgoing connections to trusted CIDRs using nftables. * **Zero-Change Deployment:** Works with most agent frameworks with a single CLI command. This documentation guide provides details on steps to deploy and configure the sandbox for agentic building and deployment. # Quick Start Access the BlueRock Secure MCP Server on AWS using the Full BlueRock AMI. This environment establishes a secure baseline for executing applications within the BlueRock Sandbox. Unlike the Free tier, the Full deployment supports custom security configurations via the TREX tool, enabling notifications of active attack and inline blocking. The Full AMI comes preloaded with a working Weather Forecast MCP server to help establish a secure connection and test functionality immediately. Follow these steps to access the environment and execute the example process: 1. [Connect to the BlueRock Instance](https://www.google.com/search?q=%23connect-to-the-bluerock-instance) 2. [Launch the Weather MCP Server](https://www.google.com/search?q=%23launch-the-weather-mcp-server) 3. [Connect the Weather MCP Client](https://www.google.com/search?q=%23connect-the-weather-mcp-client) 4. [Test the Weather MCP](https://www.google.com/search?q=%23test-the-weather-mcp) *** ### Connect to the BlueRock Instance With the AWS EC2 instance running the Full BlueRock AMI, establish a connection to access the environment. Log in using the default `ec2-user` username and the SSH key specified during the instance launch: ```shellscript ssh -i .pem ec2-user@ ``` ### Launch the Weather MCP Server Once logged in, the BlueRock Sandbox binary is pre-installed at `/opt/bluerock/bin/brace`. In the Full tier, the Sandbox actively enforces custom security policies defined through the TREX policy manager to provide inline blocking against unauthorized actions. Navigate to the preloaded Weather MCP directory, activate the Python virtual environment, and use the sandbox to launch the server: ```shellscript cd /opt/bluerock/mcp/weatherMCP source .venv/bin/activate # Launch the server securely inside the BlueRock Sandbox /opt/bluerock/bin/brace -l server.log -- uv run server-weatherMCP.py ``` * `-l`: Specifies the path to create the local log file for sandbox execution data. * `--`: Separates the sandbox configurations from the target application's execution command. ### Connect the Weather MCP Client Open a new, separate terminal window on the local machine and log into the EC2 instance again using the same SSH command from the first step. Once connected, navigate to the Weather MCP directory, activate the virtual environment, and start the interactive client: ```shellscript cd /opt/bluerock/mcp/weatherMCP source .venv/bin/activate # Launch the interactive client uv run client-weatherMCP.py ``` Upon successful connection, the console will display a `weather>` prompt and a list of available tools. ### Test the Weather MCP With the interactive client running, execute commands to retrieve real-time weather data from the sandboxed server. For example, to fetch active weather alerts for California, enter the following at the prompt: ```shellscript weather> alerts CA ``` Expected Output Snippet: ```shellscript [10/31/25 15:49:46] INFO Processing request of type CallToolRequest server.py:674 ============================================================ WEATHER ALERTS ============================================================ Event: Beach Hazards Statement Area: San Francisco; Coastal North Bay Including Point Reyes National Seashore... Severity: Moderate Description: * WHAT...A long period northwesterly swell will result in an increased risk for sneaker waves... ``` To view all available commands, type `help`. To exit the client, type `quit`. # BlueRock Secure MCP ## Overview BlueRock provides runtime observability and policy evaluation for applications built using the Model Context Protocol (MCP). Instead of acting as an MCP server, BlueRock integrates with MCP applications through embedded sensors that operate within the application runtime. When enabled, these sensors capture MCP interactions between clients and servers, providing visibility into how tools, resources, and prompts are used during execution. This enables: * visibility into MCP interactions (tools, resources, prompts) * runtime policy evaluation * detection of sensitive data patterns * control over tool execution and resource access * generation of telemetry events These capabilities apply to MCP applications implemented in: * **Python** * **JavaScript / TypeScript** Policies are evaluated at runtime by the sensors, and resulting events are exported using OpenTelemetry (OTLP) to external observability systems such as CloudWatch. *** ## MCP Architecture #### Architecture Overview BlueRock integrates with MCP applications at runtime using sensors. MCP applications run inside a BlueRock instance along with the BlueRock kernel and sensors. These sensors capture interactions such as tool calls, resource access, and prompt invocation. Policies are distributed from the control plane and evaluated during execution, and resulting events are exported using OpenTelemetry (OTLP) to external systems such as CloudWatch. The diagram below illustrates how MCP applications, BlueRock sensors, and the control plane interact to enable runtime observability:
*** ## Policy Configuration BlueRock policies define how MCP interactions are evaluated during application runtime. Policies are evaluated by the BlueRock sensors embedded within MCP applications. As the application executes, sensors evaluate interactions such as tool calls, resource access, and prompt usage against the configured policies. Based on the evaluation, policies can: * allow the interaction * generate a violation event * restrict or block specific behavior Policy evaluation happens in real time, and all resulting events are exported using OpenTelemetry (OTLP) for monitoring. Policies can be configured using JSON-based templates or CLI tools. Example: ```json { "python_sensor": { "mcp": { "enable": true, "remediate": false } }, "js_sensor": { "mcp": { "enable": true, "remediate": false } } } ``` # MCP Sensor Observability ### **Overview** This section demonstrates how MCP-based applications generate observability events when interacting with tools, resources, and prompts. Python and TypeScript clients interact with an MCP server that is integrated with the BlueRock sensor for observability. These interactions emit structured events that are captured and visualized in CloudWatch. The following operations are validated: * Tool discovery and execution * Resource listing and access * Prompt discovery and execution *** ### Deploying Python MCP Applications with BlueRock Sensor *** ### **Prerequisites** ```shellscript # Connect to the BlueRock EC2 instance ssh -i bluerock-ec2-key.pem ec2-user@ ``` ```shellscript # Verify Python version python3 --version ``` Python 3.10 or higher is required for FastMCP. #### Setup 1. **Install uv** ```shellscript curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Create Project Directory** Create a new project directory for MCP observability and navigate into it. ```shellscript cd ~ uv init mcp-observability cd mcp-observability ``` *** 3. **Install Required Dependencies** Install MCP framework, BlueRock sensor, and BlueRock runtime required for generating and exporting observability events. ```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 python -m bluepython --install ``` *** 4. **Add MCP Application File** Create the MCP client and server scripts in the project directory using the sample code provided in the [Appendix](broken://pages/8ytQ3cH4YpkmoAsFXnix) section. ```shellscript vi mcp_client.py vi mcp_fileserver_stdio.py vi mcp_fileserver.py ``` *** 5. **Verify Project Files** Ensure the required files are present in the directory. ```shellscript ls ``` **Expected Output:** ```shellscript mcp_client.py mcp_fileserver_stdio.py mcp_fileserver.py ``` *** 6. **Start MCP Server** Run the MCP server to start accepting client requests. ```shellscript uv run mcp_fileserver.py ``` ### **Observability** *** #### Tool Events **Tool Listing & Execution** **Command** ```shellscript python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --list python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --tool_cmd write_file \ --tool_args '{"filename":"test.txt","content":"hello"}' ``` **Output**
Tool interactions are captured in AWS CloudWatch telemetry logs. These logs include: * MCP client request activity * MCP server request handling * Tool name and arguments * Runtime metadata *** #### Resource Events **Resource Listing & Access** **Command** ```shellscript python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ resources --list python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ resources --resource_uri folder://explorer ``` **Output**
Resource interactions are captured in CloudWatch telemetry logs and include: * resource name * resource type * resource URI *** #### Prompt Events **Prompt Listing & Execution** **Command** ```shellscript python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts --list python3 mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts --prompt_name useful_helper_prompt ``` **Output**
Prompt interactions are captured in CloudWatch telemetry logs and include: * prompt name * input arguments * request flow *** ### Deploying JS/TS MCP Applications with BlueRock Sensor *** ### **Prerequisites** **Install Node.js (using NVM)** ```shellscript # Install NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # Install Node.js nvm install 20 # Verify installation node -v npm -v ``` #### Setup **1.** **Create Project Directory** Create a new project directory for the MCP JavaScript/TypeScript application and navigate into it. ```shellscript cd ~ mkdir mcp-observability cd mcp-observability ``` **2.Install Dependencies** Install the required Node.js dependencies before executing the MCP scripts. ```shellscript # Install BlueRock JS runtime npm install /opt/bluerock/bluejs-dist/bluejs-0.0.1.tgz ``` **3. Add MCP Application Files** Create the MCP client and server scripts directly on the EC2 instance using the sample code provided in the [Appendix](broken://pages/8ytQ3cH4YpkmoAsFXnix) section. ```shellscript mkdir tests && cd tests vi mcp_client.js vi mcp_fileserver.js vi mcp_fileserver_stdio.js vi package.json npm install ``` **4. Verify Project Files** Verify that the required files are present. ```shellscript ls ``` **Expected output:** ```shellscript mcp_client.js mcp_fileserver.js mcp_fileserver_stdio.js node_modules package-lock.json package.json ``` *** ## **Observability** To view MCP observability events in AWS CloudWatch, start the MCP server and then run the MCP client to list and execute tools. #### Tool Events **Tool Listing & Execution** ```shellscript # Starting the MCP file server (JavaScript/TypeScript) # Run the MCP server to start accepting client requests. node --import bluejs tests/mcp_fileserver.js node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --list node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools \ --tool_cmd write_file \ --tool_args '{"filename":"event-final.txt","content":"check"}' ``` **Output**
Tool interactions are captured in AWS CloudWatch telemetry logs. These logs include: * MCP client request activity * MCP server request handling * Tool name and arguments * Runtime metadata *** #### Resource Events **Resource Listing & Access** ```shellscript cd ~/mcp-observability node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ resources --list node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ resources \ --resource_uri folder://explorer ``` **Output**
Resource interactions are captured in AWS CloudWatch telemetry logs. These logs include: * MCP client request activity * MCP server request handling * Resource name and type * Resource URI * Runtime metadata *** #### Prompt Events **Prompt Listing & Execution** ```shellscript cd ~/mcp-observability node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts --list node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts \ --prompt_name useful_helper_prompt \ --prompt_args '{"lang":"java"}' ``` **Output**
Prompt interactions are captured in AWS CloudWatch telemetry logs. These logs include: * MCP client request activity * MCP server request handling * Prompt name * Input arguments * Runtime metadata # Understanding MCP Policies ### Overview BlueRock Secure MCP Server enforces runtime security controls through configurable MCP Protection Policies. Policies are evaluated at runtime for both MCP client requests and MCP server responses. They operate as an enforcement layer and do not require infrastructure redeployment. When remediation is enabled (`remediate: true`), the MCP client or server program execution is terminated upon a policy violation. When remediation is disabled (`remediate: false`), BlueRock Secure MCP Server operates in observe mode and logs policy violations while allowing execution to continue. MCP policies can be applied to MCP servers implemented in: • Python MCP servers\ • JavaScript / TypeScript MCP servers Policies regulate: * MCP client-server connections * Transport protocols (HTTP, SSE, stdio) * Authentication requirements * Tool execution behavior * Resource access controls * Prompt invocation restrictions * Pattern-based detection in arguments and responses *** ### Policy Categories MCP policies are logically grouped based on the type of control they enforce. #### 1. Connection Control Policies Control how MCP clients connect to MCP servers. Capabilities include: * Restricting stdio, HTTP, or SSE transports * Enforcing authentication for HTTP/SSE connections * Configuring exception lists for specific MCP server programs or URLs *** #### 2. Tool Execution Policies Control how MCP clients invoke tools exposed by MCP servers. Capabilities include: * Restricting execution of specific tools * Detecting forbidden patterns in tool arguments * Inspecting tool responses for unsafe content *** #### 3. Resource Access Policies Control access to MCP-exposed resources. Capabilities include: * Denying specific resource URIs * Applying server-specific resource rules *** #### 4. Prompt Execution Policies Control prompt execution behavior within MCP interactions. Capabilities include: * Denying specific prompts from specific MCP server * Detecting unsafe prompt arguments * Inspecting prompt responses for restricted patterns *** #### 5. Built-in MCP request/response message audit policies Provide predefined detection for common risky patterns such as: * Dangerous shell commands * Privilege escalation attempts * Sensitive file paths * Suspicious network commands * Potential data exfiltration behavior These apply across tool calls, prompt execution, and resource interactions. *** ## MCP Protection Policies – Use Cases This section demonstrates runtime enforcement behavior for MCP client-server interactions in 26.08.0 Release. #### Prerequisites: This section assumes the following setup is completed: • Create an MCP project directory\ • Create a Python virtual environment\ • Create FastMCP client and FastMCP server programs\ • Install the fastmcp package\ • Install the bluepython package\ • Load the bluepython package before executing the client or server program *** ## MCP Connection Control *** ### Deny Client Connection to stdio Server #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "stdio": { "deny_stdio": true, "exception_list": [] }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "stdio": { "deny_stdio": true, "exception_list": [] }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP stdio Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server mcp_fileserver_stdio.py tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server tests/mcp_fileserver_stdio.js \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior | Policy Configuration | Result | | -------------------- | ----------------------------------------------------------------- | | remediate: false | Connection allowed, violation logged (WARN) | | remediate: true | Connection blocked, violation logged as ERROR, program terminated | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} {% code expandable="true" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: deny_stdio | Type: MCP stdio server not allowed | Description: Command python mcp_fileserver_stdio.py is not permitted | Location: message.command message.args | Detected Content: python mcp_fileserver_stdio.py", "origin": "uc-gyro", "type": "log" } } ``` {% endcode %} {% endtab %} {% tab title="JS/TS" %} {% code expandable="true" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: deny_stdio | Type: MCP stdio server not allowed | Description: Command python mcp_fileserver_stdio.py is not permitted | Location: message.command message.args | Detected Content: python mcp_fileserver_stdio.py", "origin": "uc-gyro", "type": "log" } } ``` {% endcode %} {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: deny_stdio | Type: MCP stdio server not allowed | Description: Command python mcp_fileserver_stdio.py is not permitted | Location: message.command message.args | Detected Content: python mcp_fileserver_stdio.py", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 8961, "source_event_id": 1, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: deny_stdio | Command node --import bluejs tests/mcp_fileserver_stdio.js is not permitted", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-8-12", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 5717, "source_event_id": 2, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Deny stdio with Exception #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "stdio": { "deny_stdio": true, "exception_list": [{"command": "python", "args": "mcp_fileserver_stdio.py"}] }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "stdio": { "deny_stdio": true, "exception_list": [ { "command": "node", "args": "--import bluejs tests/mcp_fileserver_stdio.js" } ] }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP stdio Server
{% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server mcp_fileserver_stdio.py tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server tests/mcp_fileserver_stdio.js \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior Matching command in exception list is allowed.\ No policy violation event is generated.\ A source event for the stdio connection is emitted. **Source Event** {% code expandable="true" %} ```shellscript { "body": { "context": { "process": { "pid": 57817 } }, "entity_id": "ced0a915-a2a0-4e0c-b7eb-29c2497209e7", "server": { "args": [ "--import", "bluejs", "tests/mcp_fileserver_stdio.js" ], "command": "node", "type": "stdio" } }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "js_mcp_client_connect", "hostid": "ip-172-31-8-12", "origin": "bluejs", "sensor_id": 5717, "source_event_id": 2, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} *** ### Deny Client Connection to HTTP Server #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "http_servers": { "deny_http": true, "deny_sse": false, "exception_list": [], "force_authentication": false }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "http_servers": { "deny_http": true, "deny_sse": false, "exception_list": [], "force_authentication": false }, ``` {% endtab %} {% endtabs %} #### **Running MCP Client with MCP HTTP Server** {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | -------------------------------- | | remediate: false | Connection succeeds, WARN logged | | remediate: true | Connection blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_allowed_http_servers | Type: HTTP (no ssl/tls) connections not allowed | Description: HTTP server URL 'http://127.0.0.1:8001/mcp' is not permitted | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro" "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_allowed_http_servers | Type: HTTP (no ssl/tls) connections not allowed | Description: HTTP server URL 'http://127.0.0.1:8001/mcp' is not permitted | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro" "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_allowed_http_servers | Type: HTTP (no ssl/tls) connections not allowed | Description: HTTP server URL 'http://127.0.0.1:8001/mcp' is not permitted | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 2692, "source_event_id": 1, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_allowed_http_servers | Type: HTTP (no ssl/tls) connections not allowed | Description: HTTP server URL 'http://127.0.0.1:8001/mcp' is not permitted | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 2692, "source_event_id": 1, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Deny HTTP Server with Exception #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "http_servers": { "deny_http": true, "deny_sse": false, "exception_list": [" http://0.0.0.0:8001/mcp"], "force_authentication": false }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "http_servers": { "deny_http": true, "deny_sse": false, "exception_list": [ "http://0.0.0.0:8001/mcp" ], "force_authentication": false }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server
{% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior HTTP connections blocked by default.\ URL in exception list is allowed. No violation event generated. **Example Source Event** {% code expandable="true" %} ```shellscript { "body": { "context": { "process": { "pid": 58843 } }, "entity_id": "8ec00313-5e83-4d60-be2f-f90297f0f451", "server": { "auth": true, "type": "http", "url": "http://127.0.0.1:8001/mcp" } }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "js_mcp_client_connect", "hostid": "ip-172-31-8-12", "origin": "bluejs", "sensor_id": 5722, "source_event_id": 2, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } ``` {% endcode %} *** ### Deny any mcp server connection without authentication #### **Policy Configuration** {% tabs %} {% tab title="Python" %} ```shellscript "http_servers": { "deny_http": false, "deny_sse": false, "exception_list": [], "force_authentication": true }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "http_servers": { "deny_http": false, "deny_sse": false, "exception_list": [], "force_authentication": true }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server
{% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | ----------------------------------------------- | | remediate: false | Unauthenticated connection allowed, WARN logged | | remediate: true | Unauthenticated connection blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_allowed_http_servers | Type: Unauthenticated HTTP request are not permited | Description: Unauthenticated HTTP request to http://127.0.0.1:8001/mcp | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_allowed_http_servers | Type: Unauthenticated HTTP request are not permited | Description: Unauthenticated HTTP request to http://127.0.0.1:8001/mcp | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_allowed_http_servers | Type: Unauthenticated HTTP request not permitted | Description: Unauthenticated HTTP request to http://127.0.0.1:8001/mcp | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp" "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 2692, "source_event_id": 1, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_allowed_http_servers | Type: HTTP (no ssl/tls) connections not allowed | Description: HTTP server URL 'http://127.0.0.1:8001/mcp' is not permitted | Location: message.url | Detected Content: http://127.0.0.1:8001/mcp", "origin": "acoustic JavaScript sensor", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-8-12", "remediation_kind": "block", "sensor_id": 5722, "source_event_id": 2, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ## MCP Tool Execution Control *** ### Tool Overwrite - Denied tools are excluded from the tool/list #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript { "server": { "enable": true, "remediate": true, "tools": {"FileServer": {"deny_list": ["remove_file"]}}, "prompts": {}, "resources": {} } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "server": { "enable": true, "remediate": true, "tools": { "FileServer": { "deny_list": ["remove_file"] }}, "prompts": {}, "resources": {} } ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --list ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --list ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | ---------------------------------------- | | remediate: false | Tool is listed and violation logged | | remediate: true | Tool is excluded from the list of tools. | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Tools stripped from tool discovery result from server 'FileServer'. Blocked tools: remove_file", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Tools stripped from tool discovery result from server 'FileServer'. Blocked tools: remove_file", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_resp | Type: pattern detection | Description: Tools stripped from tool discovery result from server 'FileServer' due to forbidden patterns | Location: tools.response | Detected Content: N/A" "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 9873, "source_event_id": 6, "type": "remediation" }, "scope": { "name": "bluerock" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_resp | Type: pattern detection | Description: Tools stripped from tool discovery result from server 'FileServer' due to forbidden patterns | Location: tools.response | Detected Content: N/A" "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 2692, "source_event_id": 1, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Deny Specific Tool from Specific MCP Server #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {"FileServer": {"deny_list": ["remove_file"]}}, "prompts": {}, "resources": {} } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {"FileServer": {"deny_list": ["remove_file"]}}, "prompts": {}, "resources": {} } ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --tool_cmd remove_file --tool_args '{"filename" : "testfile.tmp"}' ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools --tool_cmd remove_file --tool_args '{"filename" : "testfile.tmp"}' ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | ------------------------------- | | remediate: false | Tool executes, violation logged | | remediate: true | Tool call blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_client_request_allowed | Type: Client Tools Request Denied | Description: Tool requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Tool: '\"list_files\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_client_request_allowed | Type: Client Tools Request Denied | Description: Tool requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Tool: '\"list_files\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### **OTEL Violation (Enforce)** {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_client_request_allowed | Type: Client Tools Request Denied | Description: Tool requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Tool: '\"list_files\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 9197, "source_event_id": 10, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_client_request_allowed | Type: Client Tools Request Denied | Description: Tool requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Tool: '\"list_files\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 9197, "source_event_id": 10, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Tool Argument Pattern Detection #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "forbidden_tool_argument_patterns": [ "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b" ] ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "forbidden_tool_argument_patterns": [ "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b" ] ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools \ --tool_cmd read_file \ --tool_args '{"filename":"test_script.bash"}' ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools \ --tool_cmd read_file \ --tool_args '{"filename":"test_script.bash"}' ``` {% endtab %} {% endtabs %} If the tool argument contains commands matching the built-in forbidden patterns (for example `cat`, `rm`, `grep`, etc.), the request triggers the built-in MCP audit policy. #### Expected Behavior | Mode | Result | | ---------------- | -------------------------- | | remediate: false | Tool executes, WARN logged | | remediate: true | Tool blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### **OTEL Violation (Enforce)** {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 7345, "source_event_id": 16, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-8-12", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 5722, "source_event_id": 2, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Tool Response Pattern Detection #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "forbidden_tool_response_patterns": [ "\\b(?:bash|sh|curl|wget|nc)\\b"] ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "forbidden_tool_response_patterns": [ "\\b(?:bash|sh|curl|wget|nc)\\b"] ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} {% code expandable="true" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --tool_cmd read_file --tool_args '{"filename":"unsafetext.txt"}' ``` {% endcode %} {% endtab %} {% tab title="JS/TS" %} {% code expandable="true" %} ```shellscript node --import bluejs tests/mcp_client.js --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token tools --tool_cmd read_file --tool_args '{"filename":"unsafetext.txt"}' ``` {% endcode %} {% endtab %} {% endtabs %} #### **Expected Behavior** If tool output contains forbidden patterns: | Mode | Result | | ---------------- | ---------------------------------- | | remediate: false | Response allowed, violation logged | | remediate: true | Response blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_tool_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (0..2)' | Location: content[0].[\"text\"] | Detected Content: nc -lnvp 1234\n", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_tool_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (0..2)' | Location: content[0].[\"text\"] | Detected Content: nc -lnvp 1234\n", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "origin": "acoustic Python sensor", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 9874, "source_event_id": 6, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tools_arguments | Type: pattern detection | Description: \\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b: '\"cat\" (0..3)' | Location: arguments.command | Detected Content: cat test_script.bash", "origin": "acoustic JavaScript sensor", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 9874, "source_event_id": 6, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ## MCP Resource Access Control *** ### Deny Specific Resource #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {}, "prompts": {}, "resources": {"FileServer": {"deny_list": ["config://app-settings"]}} }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {}, "prompts": {}, "resources": { "FileServer": { "deny_list": ["config://app-settings"] } } }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server Run the MCP client with a resource URI that matches the `deny_list`. {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token resources --resource_uri config://app-settings ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ resources \ --resource_uri config://app-settings ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | ---------------------------------- | | remediate: false | Resource allowed, violation logged | | remediate: true | Resource access denied | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Resources Request Denied | Description: Resource requested is not allowed | Location: message.params.uri | Detected Content: Server: '\"FileServer\"', Resource: '\"config://app-settings\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Resources Request Denied | Description: Resource requested is not allowed | Location: message.params.uri | Detected Content: Server: '\"FileServer\"', Resource: '\"config://app-settings\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Resources Request Denied | Description: Resource requested is not allowed | Location: message.params.uri | Detected Content: Server: '\"FileServer\"', Resource: '\"config://app-settings\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 7345, "source_event_id": 11, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_tool_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (0..2)' | Location: content[0].[\"text\"] | Detected Content: nc -lnvp 1234\n", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 9873, "source_event_id": 6, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } ``` {% endtab %} {% endtabs %} *** ## MCP Prompt Execution Control *** ### Deny Specific Prompt #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {}, "prompts": {"FileServer": {"deny_list": ["useful_helper_prompt"]}}, "resources": {} }, ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "server": { "enable": true, "remediate": true, "tools": {], "prompts": {"FileServer": {"deny_list": ["useful_helper_prompt"]}}, "resources": {} }, ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token prompts --prompt_name useful_helper_prompt --prompt_args '{"lang": "java"}' ``` {% endtab %} {% tab title="JS/TS " %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts \ --prompt_name useful_helper_prompt \ --prompt_args '{"lang":"java"}' ``` {% endtab %} {% endtabs %} #### Expected Behavior | Mode | Result | | ---------------- | ------------------------------------------------------------------------ | | remediate: false | Prompt execution proceeds, but a violation event is generated. | | remediate: true | Prompt invocation is blocked and the MCP client execution is terminated. | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Prompts Request Denied | Description: Prompt requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Prompt: '\"useful_helper_prompt\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Prompts Request Denied | Description: Prompt requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Prompt: '\"useful_helper_prompt\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Resources Request Denied | Description: Resource requested is not allowed | Location: message.params.uri | Detected Content: Server: '\"FileServer\"', Resource: '\"config://app-settings\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 7345, "source_event_id": 16, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_server_request_allowed | Type: Server Prompts Request Denied | Description: Prompt requested is not allowed | Location: message.params.name | Detected Content: Server: '\"FileServer\"', Prompt: '\"useful_helper_prompt\"'", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-8-12", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 5722, "source_event_id": 2, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Prompt Argument Pattern Detection #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "forbidden_prompt_arg_patterns": [ "\\b(?:bash|sh|curl|wget|nc|sudo)\\b" ] ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "forbidden_prompt_arg_patterns": [ "\\b(?:bash|sh|curl|wget|nc|sudo)\\b" ] ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token prompts --prompt_name useful_helper_prompt --prompt_args '{"lang": "bash"}' ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ prompts \ --prompt_name useful_helper_prompt \ --prompt_args '{"lang":"bash"}' ``` {% endtab %} {% endtabs %} #### Expected Behavior
| Mode | Result | | ---------------- | ------------------------------------------------------------------------ | | remediate: false | Prompt execution proceeds, but a violation event is generated. | | remediate: true | Prompt invocation is blocked and the MCP client execution is terminated. | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_prompt_arguments | Type: pattern detection | Description: \\b(?:bash|sh|zsh|fish|csh|tcsh)\\b: '\"bash\" (0..4)' | Location: arguments.lang | Detected Content: bash", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_prompt_arguments | Type: pattern detection | Description: \\b(?:bash|sh|zsh|fish|csh|tcsh)\\b: '\"bash\" (0..4)' | Location: arguments.lang | Detected Content: bash", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_prompt_arguments | Type: pattern detection | Description: \\b(?:bash|sh|zsh|fish|csh|tcsh)\\b: '\"bash\" (0..4)' | Location: arguments.lang | Detected Content: bash", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 9858, "source_event_id": 8, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_prompt_arguments | Prompt invocation blocked due to forbidden content: bash", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-8-12", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 5722, "source_event_id": 2, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endtab %} {% endtabs %} *** ### Prompt Response Pattern Detection #### Policy Configuration {% tabs %} {% tab title="Python" %} ```shellscript "forbidden_prompt_response_patterns": [ "\\b(?:curl|wget|nc|ssh)\\b"] ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "forbidden_prompt_response_patterns": [ "\\b(?:curl|wget|nc|ssh)\\b"] ``` {% endtab %} {% endtabs %} #### Running MCP Client with MCP HTTP Server {% tabs %} {% tab title="Python" %} {% code expandable="true" %} ```shellscript python mcp_client.py --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token prompts --prompt_name useful_helper_prompt --prompt_args '{ "lang": "java" }' ``` {% endcode %} {% endtab %} {% tab title="JS/TS" %} {% code expandable="true" %} ```shellscript node --import bluejs tests/mcp_client.js --mcp_server http://0.0.0.0:8001/mcp --mcp_auth_token dev-token prompts --prompt_name useful_helper_prompt --prompt_args '{ "lang": "java" }' ``` {% endcode %} {% endtab %} {% endtabs %} #### Expected Behavior If response contains `nc`, `curl`, etc: | Mode | Result | | ---------------- | ---------------------------------- | | remediate: false | Response allowed, violation logged | | remediate: true | Response blocked | #### OTEL Violation (Observe) {% tabs %} {% tab title="Python" %} {% code expandable="true" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_prompt_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (76..78)' | Location: messages[0].[\"content\", \"text\"] | Detected Content: You are an expert in java. create or update file using java code that uses nc.", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endcode %} {% endtab %} {% tab title="JS/TS" %} {% code expandable="true" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_patterns_in_prompt_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (76..78)' | Location: messages[0].[\"content\", \"text\"] | Detected Content: You are an expert in java. create or update file using java code that uses nc.", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endcode %} {% endtab %} {% endtabs %} #### OTEL Violation (Enforce) {% tabs %} {% tab title="Python" %} {% code expandable="true" %} ```shellscript Please remove existing and add: { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_prompt_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (53..55)' | Location: messages[0].[\"content\", \"text\"] | Detected Content: You are an expert in java. write java code that uses nc.", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 9859, "source_event_id": 8, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} {% endtab %} {% tab title="JS/TS" %} {% code expandable="true" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "Policy: check_patterns_in_prompt_resp | Type: pattern detection | Description: \\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b: '\"nc\" (53..55)' | Location: messages[0].[\"content\", \"text\"] | Detected Content: You are an expert in java. write java code that uses nc.", "domain": "gyro", "event_name": "mcp_policy_violation", "hostid": "ip-172-31-22-6", "origin": "acoustic JavaScript sensor", "remediation_kind": "block", "sensor_id": 9859, "source_event_id": 8, "type": "remediation" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} {% endtab %} {% endtabs %} *** ### Message Size Violation #### **Policy Configuration** {% tabs %} {% tab title="Python" %} ```shellscript "message_threshold": { "enable": true, "remediate": true, "threshold": 256 } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript "message_threshold": { "enable": true, "remediate": true, "threshold": 256 } ``` {% endtab %} {% endtabs %} *** #### **Running MCP Client with MCP HTTP Server** {% tabs %} {% tab title="Python" %} ```shellscript python mcp_client.py \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools \ --tool_cmd write_file \ --tool_args '{"filename":"test.txt","content":""}' ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript node --import bluejs tests/mcp_client.js \ --mcp_server http://0.0.0.0:8001/mcp \ --mcp_auth_token dev-token \ tools \ --tool_cmd write_file \ --tool_args '{"filename":"test.txt","content":""}' ``` {% endtab %} {% endtabs %} *** #### **Expected Behavior** | Mode | Behavior | | ---------------- | ----------------------------------------- | | remediate: false | Request proceeds; violation logged (WARN) | | remediate: true | Request proceeds; violation logged (WARN) | #### **OTEL Violation (Observe)** {% tabs %} {% tab title="Python" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_message_size | Type: Message size limit exceeded | Description: Message size of 272 bytes exceeds threshold of 256 bytes, sent by the Client | Location: message | Detected Content: N/A", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% tab title="JS/TS" %} ```shellscript { "body": "mcp_policy_violation", "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "Policy: check_message_size | Type: Message size limit exceeded | Description: Message size of 272 bytes exceeds threshold of 256 bytes, sent by the Client | Location: message | Detected Content: N/A", "domain": "gyro", "event_name": "mcp_policy_violation", "origin": "uc-gyro", "type": "log" } } ``` {% endtab %} {% endtabs %} *** ## Summary | Mode | Behavior | | ---------------- | ------------------------------------------- | | remediate: false | Observe mode – Action allowed, WARN logged | | remediate: true | Enforce mode – Action blocked, ERROR logged | All violations are emitted as OTEL events and sent to external collector such as AWS CloudWatch based on the configurations. * `event_name: mcp_policy_violation` * `severity_text: WARN or ERROR` * `type:` * `"log" (observe events)` * `"remediation" (enforce events)` * `remediation_kind: "block" (enforce mode only)` *** # BlueRock Sandbox The BlueRock Sandbox uses containerd to operate as a policy-driven container runtime. It shares foundational features with standard Docker environments, including process isolation, namespaces, and volume mounting. The architecture prioritizes execution control and integrated telemetry rather than general application deployment. The runtime enforces security policies that explicitly permit or deny specific binaries to ensure that compromised AI agents execute only authorized tools. Running containerized workloads requires using the `brace` command to import OCI-compliant images from the local Docker daemon into the isolated runtime registry. ### Package The BlueRock Sandbox utility comes pre-installed on the BlueRock Linux distribution, cloud images for AWS and GCP. The BlueRock Sandbox binary is present at `/opt/bluerock/bin/brace` with a symlink at `/usr/bin/brace`. ### CLI Command Reference The `brace` command is the primary interface for launching applications in isolated environments. Usage: `brace` `[OPTIONS] [-- ...]` **Primary Options**
OptionDescription
--socket <SOCKET>Path to the sensor socket. (Default: /run/bluerock/sensor.sock)
--name <NAME>Assigns a unique name to the BlueRock Sandbox instance. (Default: sandbox)
-l, --logfile <LOGFILE>Path to the log file. (Default: ./brace.log)
-K, --clear-envClears all host environment variables for a "clean slate."
-e, --env <ENV>Passes environment variables into the BlueRock Sandbox.
--pid <PID>PID namespace mode: 'host' to share host PID namespace, or 'isolated' for a separate namespace (overrides config).
--mount-proc <MOUNT_PROC>

Mounts /proc inside the sandbox (overrides config).


Possible values: true, false

-v, --volume <VOLUME>Bind-mounts host directories: HOST_PATH:CONTAINER_PATH. Append :ro for read-only access (overrides config mounts).
--user-ns <USER_NS>

Runs the sandbox with an enabled user namespace.


Possible values: true, false

--tmpfs <TMPFS>Mounts a temporary file system (tmpfs) at the specified PATH inside the sandbox.
--skip-mntsSkips all policy-configured mounts; only CLI --volume mounts will be used.
--disable-networkDisables the network namespace setup.
--nestedRuns nested inside another brace container (disables the seccomp listener).
-h, --helpPrints help information.
-V, --versionPrints version information.
**Architectural Workflow**
### BlueRock Sandbox Use Cases The BlueRock Sandbox provides a highly secure, isolated execution environment for workloads. The primary use cases and execution methods are detailed below. #### Running Shell Commands To securely explore, test, or execute commands within an isolated environment, run a direct shell command. {% hint style="info" icon="notes-sticky" %} **Note**: BlueRock Sandbox provides an isolated execution environment; the system is distinct from standard container runtimes. {% endhint %} To test the environment using the host's binaries, mount the standard system directories and run a simple command: {% code overflow="wrap" %} ```shellscript $ brace -- /usr/bin/echo "Hello! Welcome to the BlueRock Sandbox" ``` {% endcode %} Expected output: ```shellscript Hello! Welcome to the BlueRock Sandbox ``` #### Running a Python Application To execute applications directly using the host file system, map system directories (`/usr`, `/lib`) and the user directory (e.g., `/home/ubuntu`) to provide the necessary tools and permissions. This execution runs under the current user identity and does not require `sudo`. #### Running Python MCP Server and MCP Client Programs To execute Python applications directly using the host file system, you must map the required system directories (`/usr`, `/lib`, `/lib64`), BlueRock sensor directories (`/opt/bluerock`, `/run/bluerock`), and the user workspace (e.g., `/home/ubuntu`) to provide the necessary tools and telemetry permissions to the sandbox. This execution runs under the current user identity and does not require `sudo`. **Setup** 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). Ensure the following files are present in the `mcp-observability` directory: * [`mcp_client.py`](/glossary/appendix#mcp-client-script-python) * [`mcp_fileserver.py`](/glossary/appendix#mcp-file-server-http-python) * [`mcp_fileserver_stdio.py`](/glossary/appendix#mcp-file-server-stdio-python) **Using Mount Points in Command Line Arguments** Pass the required volume mounts (`-v`) directly in the execution command. The `/home/ubuntu:/home/ubuntu` mapping provides access to your newly created project folder, while the system and `bluerock` mounts ensure the Python binary and security sensors function correctly. {% hint style="info" icon="notes-sticky" %} **Note:** Adjust this path based on the active host user. For example, on AL2023, the default path is `/home/ec2-user`. For a test user, the path could be `/home/test`. {% endhint %} **Terminal 1:** Starting the MCP Server Launch the sandbox with the required bind mounts: {% code overflow="wrap" %} ```shellscript $ brace -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /home/ubuntu:/home/ubuntu -v /etc/resolv.conf:/etc/resolv.conf -v /dev:/dev --name sandbox_mcpserver -- /home/ubuntu/.local/bin/uv run mcp_fileserver.py ``` {% endcode %} **Expected Output**: FastMCP Server starts on {% code overflow="wrap" lineNumbers="true" %} ```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) ``` {% endcode %} **Terminal 2:** Starting the MCP Client: \ Open a separate terminal and launch a second sandbox using identical Operating System (OS) mounts to execute the client script. {% code overflow="wrap" %} ```shellscript $ brace -v /usr:/usr -v /lib:/lib -v /lib64:/lib64 -v /home/ubuntu:/home/ubuntu -v /etc/resolv.conf:/etc/resolv.conf -v /dev:/dev --name sandbox_mcpclient -- /home/ubuntu/.local/bin/uv run mcp_client.py ``` {% endcode %} Expected output: {% code overflow="wrap" %} ```shellscript Available Tools: [Tool(name='list_files_important', title=None, description='List files in directory. check file size. ', inputSchema={'additionalProperties': False, 'properties': {'directory': {'default': '.', 'type': 'string'}, 'pattern': {'default': '*', 'type': 'string'}}, 'type': 'object'}, outputSchema={'properties': {'result': {'items': {'type': 'string'}, 'type': 'array'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None), Tool(name='list_files', title=None, description='List files in directory', inputSchema={'additionalProperties': False, 'properties': {'directory': {'default': '.', 'type': 'string'}, 'pattern': {'default': '*', 'type': 'string'}}, 'type': 'object'}, outputSchema={'properties': {'result': {'items': {'type': 'string'}, 'type': 'array'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None), Tool(name='create_file', title=None, description='create a text file.', inputSchema={'additionalProperties': False, 'properties': {'file_path': {'type': 'string'}, 'text': {'type': 'string'}}, 'required': ['file_path', 'text'], 'type': 'object'}, outputSchema={'properties': {'result': {'type': 'string'}}, 'required': ['result'], 'type': 'object', 'x-fastmcp-wrap-result': True}, icons=None, annotations=None, meta={'fastmcp': {'tags': []}}, execution=None)] ``` {% endcode %} #### BlueRock Sandbox Container #### Using Mount Points in Command Line Arguments Mount local host directories into the container application to share data, configurations, or output logs. ```shellscript $ docker run -it --runtime io.containerd.bluerock.v2 \ -v /home/ubuntu/langchain-data:/app/data:ro \ -v /run/bluerock:/run/bluerock \ --name test-langchain \ docker.io/library/langchain-mcp-server:v1 /usr/bin/python3 /app/server.py ``` Expected output: ```shellscript LangChain MCP Server Started... ``` #### Passing Environment Variables at Runtime Container applications often require runtime configuration such as API keys, environment toggles, or port definitions. Pass these variables securely at execution using the environment (`-e`) flag. {% code overflow="wrap" %} ```shellscript $ docker run -it --runtime io.containerd.bluerock.v2 \ -e OPENAI_API_KEY="sk-..." \ -e ENV="production" \ -v /home/ubuntu/langchain-data:/app/data:ro \ -v /run/bluerock:/run/bluerock \ --name test-langchain \ docker.io/library/langchain-mcp-server:v1 /usr/bin/python3 /app/server.py ``` {% endcode %} ### Run BlueRock Sandbox Container using Docker Image Execute OCI-compliant Docker images within the BlueRock Sandbox environment. The `brace` and `docker` command facilitates the process and manages the subsequent container lifecycle. When launching containers, specifying `--runtime io.containerd.bluerock.v2` forces the workload through a secure abstraction layer. ### Containerd Shim Mode The `brace-shim` natively implements the containerd shim v2 (`io.containerd.bluerock.v2`) to wrap `runc` and attach acoustic monitoring at the boundary of every container. For example: 
$ docker run -it --runtime io.containerd.bluerock.v2 ubuntu:latest bash
Terminal changes to: ```shellscript root@4bc05f087a5b:/# ``` #### Native OCI Annotations When orchestrating container deployments via standard engine runtimes, you can pass custom Open Container Initiative (OCI) annotations directly through the command line, or deployment manifests to modify runtime behavior. | Annotation | Default Value | Purpose / Behavior | | ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `io.bluerock.socket` | `/run/bluerock/sensor.sock` | Overrides the target acoustic sensor Unix domain socket path for this specific container. | | `io.bluerock.principal` | *(None)* | Specifies the principal identifier. This is written to `/etc/bluerock.env` inside the container rootfs so nested runtime sensors (e.g., `bluepython`) automatically inherit it. | | `io.bluerock.policy-hint` | *(None)* | Provides a policy selection hint passed directly to `bluerockd` to determine which access policy applies to the workload. | **Example Invocation with OCI Annotations:** ```bash docker run --runtime io.containerd.bluerock.v2 \ --annotation io.bluerock.socket=/run/bluerock/sensor.sock \ --annotation io.bluerock.principal=myuser \ ubuntu:22.04 bash ``` # 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. {% code overflow="wrap" %} ```shellscript $ brace -l ./custom_sandbox.log -v /usr:/usr:ro -v /lib:/lib:ro -v /lib64:/lib64:ro -- /usr/bin/bash ``` {% endcode %} To stream logs directly to the terminal for real-time observation, specify `stdout`: {% code overflow="wrap" %} ```shellscript $ 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 ``` {% endcode %} Expected output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript 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 ``` {% endcode %} ### Viewing Sandbox Logs Standard Linux utilities can be used to monitor and review the generated log files. To view the entire log file: {% code overflow="wrap" %} ```shellscript $ cat custom_sandbox_rCURRENT.log ``` {% endcode %} Example output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript 2026-07-06T07:10:32.897809038Z INFO main acoustic::connector: acoustic/src/connector.rs:36: Using socket paths: "/run/bluerock/sensor.sock", None, None 2026-07-06T07:10:32.943514108Z 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:10:32.945115444Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:126: Starting seccomp monitoring for container PID 25879 2026-07-06T07:10:32.94562813Z INFO main brace::capability: brace/src/capability.rs:113: Ambient capabilities (will survive exec): [CAP_SYS_ADMIN, CAP_NET_RAW] 2026-07-06T07:10:32.948816335Z INFO main brace::capability: brace/src/capability.rs:160: Dropped CAP_SYS_ADMIN capability after mount operations 2026-07-06T07:10:32.948830821Z INFO main brace::capability: brace/src/capability.rs:179: Dropped temporal capabilities: network=false, mount=true 2026-07-06T07:10:59.896610887Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:141: Seccomp monitor: all container processes (init PID 25879) exited 2026-07-06T07:10:59.896647653Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:465: Seccomp monitoring stopped for container PID 25879 ``` {% endcode %} To monitor logs in real-time (follow mode): ```shellscript $ tail -f custom_sandbox_rCURRENT.log ``` Expected output: {% code overflow="wrap" lineNumbers="true" %} ```shellscript 2026-07-06T07:10:32.897809038Z INFO main acoustic::connector: acoustic/src/connector.rs:36: Using socket paths: "/run/bluerock/sensor.sock", None, None 2026-07-06T07:10:32.943514108Z 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:10:32.945115444Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:126: Starting seccomp monitoring for container PID 25879 2026-07-06T07:10:32.94562813Z INFO main brace::capability: brace/src/capability.rs:113: Ambient capabilities (will survive exec): [CAP_SYS_ADMIN, CAP_NET_RAW] 2026-07-06T07:10:32.948816335Z INFO main brace::capability: brace/src/capability.rs:160: Dropped CAP_SYS_ADMIN capability after mount operations 2026-07-06T07:10:32.948830821Z INFO main brace::capability: brace/src/capability.rs:179: Dropped temporal capabilities: network=false, mount=true 2026-07-06T07:10:59.896610887Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:141: Seccomp monitor: all container processes (init PID 25879) exited 2026-07-06T07:10:59.896647653Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: brace/src/runtime/common/seccomp_monitor.rs:465: Seccomp monitoring stopped for container PID 25879 ``` {% endcode %} {% hint style="info" icon="notes-sticky" %} **Note:** BlueRock Sandbox always creates a log file with `_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. {% endhint %} ### 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: ```shellscript 2026-07-06T07:10:32.897809038Z INFO main acoustic::connector: Using socket paths: "/run/bluerock/sensor.sock", None, None 2026-07-06T07:10:32.943514108Z INFO main brace::runtime::common::opts: Final opts after CLI overrides - pid_ns: true, user_ns: false 2026-07-06T07:10:32.945115444Z INFO ThreadId(04) brace::runtime::common::seccomp_monitor: Starting seccomp monitoring for container PID 25879 ``` #### 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. ```shell ## To restart the otelcol.service $ sudo systemctl restart otelcol.service ## To check the status of otelcol.service $ sudo systemctl status otelcol.service ``` 2. To check the logs 
$ journalctl -u otelcol.service
Expected output: ```shellscript Jul 05 19:33:45 ip-172-31-25-81 systemd[1]: Started otelcol.service - OpenTelemetry Collector (Bluerock). Jul 05 19:33:45 ip-172-31-25-81 run-otelcol.sh[2628]: 2026/07/05 19:33:45 ADOT Collector version: v0.44.0 Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026/07/05 19:33:46 attn: users of the `datadog`, `logzio`, `sapm`, `signalfx` exporter components. please refer to https://github.com/> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.311Z info service@v0.130.0/service.go:197 Setting up own telemetry... {"resource": {"se> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.318Z info builders/builders.go:26 Development component. May change in the future. {"re> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.325Z info builders/builders.go:26 Unmaintained component. Actively looking for contributors. C> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.325Z debug awsutil@v0.130.0/conn.go:26 Using proxy address: {"resource": {"service.ins> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.326Z debug awsutil@v0.130.0/conn.go:98 Fetch region from commandline/config file {"reso> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Beta component. May change in the future. {"resource> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug Logger core does not support injecting component attributes {"resource": {"service.> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug otlpreceiver@v0.130.0/otlp.go:58 created signal-agnostic logger {"resource":> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Beta component. May change in the future. {"resource> ``` *** ### 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).\ ![](/files/Ugh0f4hzfFZtXElptvbU) **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: ```json { "body": { "source_event": { "args": "wget --timeout xx -U wget/x.xx.x-xxxxxxxxxx Ubuntu/xx.xx.x/LTS GNU/Linux/x.xx.xx-bluerock-bru-release-xx-xx-x-xxxxxxxxxxxx/x86_64 Intel(R)/Xeon(R)/Platinum/xxxxxx/CPU/@/xxxxGHz cloud_id/xxx -O- --content-on-error https://motd.ubuntu.com", "context": { "cgroup": { "cgroup_id": 00000, "cgroup_name": "/system.slice/motd-news.service" }, "namespace": { "cgroup_ns_inum": 0000000000, "ipc_ns_inum": 0000000000, "mnt_ns_inum": 0000000000, "net_ns_inum": 0000000000, "pid_for_children_ns_inum": 0000000000, "pid_ns_inum": 0000000000, "time_for_children_ns_inum": 0000000000, "time_ns_inum": 0000000000, "user_ns_inum": 0000000000, "uts_ns_inum": 0000000000 }, "parent_process": { "comm": "50-motd-news", "pid": 00000 }, "process": { "comm": "50-motd-news", "cwd": "/", "effective_capability": 2199023255551, "egid": 0, "euid": 0, "file_path": "/usr/bin/dash", "gid": 0, "permitted_capability": 2199023255551, "pid": 00000, "sys_daemon": true, "uid": 0 } }, "env": "USER=root SYSTEMD_EXEC_PID=00000 TRIGGER_TIMER_REALTIME_USEC=0000000000000000 JOURNAL_STREAM=x:xxxxx MEMORY_PRESSURE_WATCH=/sys/fs/cgroup/system.slice/motd-news.service/memory.pressure PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/snap/bin INVOCA", "fd0": "CHARDEV: /dev/null", "fd1": "UNKNOWN: /tmp/tmp.xxxxxxxxxx", "fd2": "UNKNOWN: /tmp/tmp.xxxxxxxxxx", "file_path": "/usr/bin/wget", "meta": { "name": "process_exec", "origin": "kernel", "sensor_id": 0000, "source_event_id": 0000000, "type": "event" }, "newfile": false, "newfile_arg": false } }, "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "'/usr/bin/dash' attemping to execute '/usr/bin/wget'. '/usr/bin/dash' is not allowed to execute.", "domain": "gyro", "event_name": "process_guard_violation", "hostid": "ip-xxx-xx-xx-xxx", "origin": "uc-gyro", "sensor_id": 0000, "source_event_id": 0000000, "type": "log" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` *** #### **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: 
exporters:
     awscloudwatchlogs:
       log_group_name: bluerock-ec2-TelemetryLogGroup
     debug:
       verbosity: detailed
\ Add the `debug` exporter to the logs pipeline under the `service` section: 
service:
     pipelines:
       logs:
         receivers: [otlp]
         processors: [resourcedetection, memory_limiter, batch]
         exporters: [awscloudwatchlogs, debug]
2. **Apply the Configuration**\ Restart the OpenTelemetry Collector container to apply the new pipeline configuration: 
$ sudo systemctl status otelcol.service
3. To check the logs 
$ journalctl -u otelcol.service
Expected output: ```shellscript Jul 05 19:33:45 ip-172-31-25-81 systemd[1]: Started otelcol.service - OpenTelemetry Collector (Bluerock). Jul 05 19:33:45 ip-172-31-25-81 run-otelcol.sh[2628]: 2026/07/05 19:33:45 ADOT Collector version: v0.44.0 Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026/07/05 19:33:46 attn: users of the `datadog`, `logzio`, `sapm`, `signalfx` exporter components. please refer to https://github.com/> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.311Z info service@v0.130.0/service.go:197 Setting up own telemetry... {"resource": {"se> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.318Z info builders/builders.go:26 Development component. May change in the future. {"re> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.325Z info builders/builders.go:26 Unmaintained component. Actively looking for contributors. C> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.325Z debug awsutil@v0.130.0/conn.go:26 Using proxy address: {"resource": {"service.ins> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.326Z debug awsutil@v0.130.0/conn.go:98 Fetch region from commandline/config file {"reso> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Beta component. May change in the future. {"resource> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug Logger core does not support injecting component attributes {"resource": {"service.> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug otlpreceiver@v0.130.0/otlp.go:58 created signal-agnostic logger {"resource":> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Beta component. May change in the future. {"resource> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.329Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.331Z info service@v0.130.0/service.go:257 Starting aws-otel-collector... {"resource": {> Jul 05 19:33:46 ip-172-31-25-81 run-otelcol.sh[2628]: 2026-07-05T19:33:46.331Z info extensions/extensions.go:41 Starting extensions... {"resource": {"service.ins> ``` ### 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 NameTrigger Syscall(s)Trigger ConditionMode Support
brace_execexecve, execveatAny execution of a binary file inside the container sandbox.CLI, Shim
brace_mmap_execmmap, execve, execveatmmap called with PROT_EXEC or execution targeting an in-memory memfd.CLI, Shim
brace_file_openopen, openatAny file open operation (read-only opens can be filtered out via policy).CLI, Shim
brace_socketsocketSocket initialization inside the sandbox boundary.CLI, Shim
brace_connectconnectNetwork egress or internal Unix socket connection attempts.CLI, Shim
brace_deleteunlink, unlinkat, rmdirFile or directory deletions inside the container sandbox.CLI, Shim
brace_suspicious_syscallunshare, ptraceBlockable container-escape or process-injection attempts.CLI, Shim
brace_process_terminateexit, exit_groupVoluntary 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: ```json { "meta": { "name": "", "type": "event", "domain": "sensor", "origin": "brace", "source_event_id": 0000xxx }, "context": { "process": { "comm": "", "file_path": "", "pid": 1234 }, "cwd": "" } // Event-specific data block merges here } ``` **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//comm`. * `context.process.file_path` *(string)*: Absolute host-resolved filesystem path extracted from `/proc//exe`. * `context.process.pid` *(integer)*: Process ID executing the intercepted syscall. * `context.cwd` *(string)*: Current working directory extracted from `/proc//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). ```json { "body": { "args": [ "rm", "-rf", "/tmp/xxxxxxxxxxxxxxxxxxxx" ], "context": { "parent_process": { "comm": "python3.12", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "env": [ "SHELL=/bin/bash", "PWD=/home/xxxxxx", "LOGNAME=xxxxxx", "XDG_SESSION_TYPE=tty", "HOME=/home/xxxxxx", "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:", "SSH_USER_AUTH=/tmp/xxxxxxxxxxxxxxxxxxxxxxxxxxxx", "SSH_CONNECTION=xx.xxx.xxx.xxx xxxxx xx.xxx.xxx.xxx xx", "LESSCLOSE=/usr/bin/lesspipe %s %s", "XDG_SESSION_CLASS=user", "TERM=xterm-256color", "LESSOPEN=| /usr/bin/lesspipe %s", "USER=xxxxxx", "SHLVL=2", "XDG_SESSION_ID=1", "XDG_RUNTIME_DIR=/run/user/0000", "SSH_CLIENT=xx.xxx.xxx.xxx xxxxx xx", "XDG_DATA_DIRS=/usr/local/share:/usr/share:/var/lib/snapd/desktop", "PATH=/home/xxxxxx/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0000/bus", "SSH_TTY=/dev/pts/0", "_=/usr/bin/python3.12" ], "file_path": "/usr/bin/rm" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "brace_process_exec", "hostid": "ip-xxx-xx-xx-xxx", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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). ```json { "body": { "source_event": { "context": { "parent_process": { "comm": "python3.12", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "fd": 3, "file_path": "/memfd: (deleted)", "is_memfd": true, "meta": { "domain": "sensor", "name": "brace_mmap_exec", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "prot": 0 } }, "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "brace mmap exec: process '/usr/bin/python3.12' (00000) executing from memfd '/memfd: (deleted)'", "domain": "gyro", "event_name": "brace_mmap_exec_violation", "hostid": "ip-xxx-xx-xx-xxx", "origin": "acoustic BRace sensor", "remediation_kind": "log", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "log" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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. ```json { "body": { "context": { "parent_process": { "comm": "bash", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "file_path": "/tmp/xxxxxxxxxxxxxxxxx/f", "flags": 524865, "is_dir": "null", "is_fifo": "null", "is_link": "null", "is_socket": "null", "is_writeable": true }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "brace_file_open", "hostid": "ip-xxx-xx-xx-xxx", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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). ```json { "body": { "context": { "parent_process": { "comm": "bash", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "domain": 10, "protocol": 0, "socket_type": 524289 }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "brace_socket", "hostid": "ip-xxx-xx-xx-xxx", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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`). ```json { "body": { "addr": "xxx.x.x.x:xx", "addr_family": 2, "context": { "parent_process": { "comm": "bash", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "sockfd": 3 }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "brace_connect", "hostid": "ip-xxx-xx-xx-xxx", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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. ```json { "body": { "context": { "parent_process": { "comm": "bash", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/xxxxxx", "effective_capability": 9216, "egid": 0000, "euid": 0000, "file_path": "/usr/bin/python3.12", "gid": 0000, "permitted_capability": 9216, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "file_path": "/tmp/xxxxxxxxxxxxxxxxxxxxxxxxx", "is_dir": false }, "severity_number": 9, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "brace_delete", "hostid": "ip-xxx-xx-xx-xxx", "origin": "brace", "sensor_id": 0000, "source_event_id": 0000000000000000000, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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"`). ```json { "body": { "source_event": { "context": { "parent_process": { "comm": "bash", "pid": 00000 }, "process": { "comm": "python3.12", "cwd": "/home/ubuntu", "effective_capability": 0000, "egid": 1000, "euid": 1000, "file_path": "/usr/bin/python3.12", "gid": 1000, "permitted_capability": 0000, "pid": 00000, "sys_daemon": false, "uid": 0000 } }, "meta": { "domain": "sensor", "name": "brace_suspicious_syscall", "origin": "brace", "sensor_id": 1111, "source_event_id": 00000000000000, "type": "event" }, "syscall": "unshare" } }, "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "brace suspicious syscall: process '/usr/bin/python3.12' (23724) attempted 'unshare'", "domain": "gyro", "event_name": "brace_suspicious_syscall_violation", "hostid": "", "origin": "acoustic BRace sensor", "remediation_kind": "log", "sensor_id": 0000, "source_event_id": 000000000000000, "type": "log" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### **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. {% hint style="info" icon="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. {% endhint %} * Payload Fields: * `pid` *(integer)*: The process identifier exiting the sandbox environment. * `comm` *(string)*: The short process text identifier captured from `/proc//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. ```json { "meta": { "name": "brace_process_terminate", "type": "event", "domain": "sensor", "origin": "brace", "source_event_id": 0000111 }, "pid": 1234, "comm": "python3", "exit_code": 0, "exit_signal": 0 } ``` #### 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: ```bash sudo ctr run --runtime io.containerd.bluerock.v2 docker.io/library/ubuntu:22.04 my-container bash ``` # 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 template file resides at `/opt/bluerock/trex` with filename `bru_policy.json.template`. Rename or copy it with filename `bru_policy.json` and make the relevant changes. #### Policy Structure Overview A standard sandbox policy is divided into three primary blocks: 1. [`options`](#runtime-options-options): Defines runtime environments, user privileges, and namespace isolation. 2. [`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": { "options": { "bind_mount": { "mount_proc": true, "mounts": [] }, "pid_ns": true, "user_ns": false }, "network": { "enable": false, "general": { "bridge": "bru0", "gateway": "10.0.0.1" }, "firewall": null }, } ``` {% endcode %} #### Runtime Options (`options`) The `options` block manages system-level isolation, file system access, and user privileges. | **Parameter** | **Type** | **Description** | | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bind_mount.mount_proc` | Boolean | Procfs Mount Control: Automatically mounts a separate, isolated `/proc` filesystem inside the sandbox container for process status tracing. *(Defaults to `true`)*. | | `bind_mount.mounts` | Array | Host Volume Mappings: An array defining directories or files mapped from the host filesystem into the sandbox. *(Empty `[]` in this profile)*. | | `pid_ns` | Boolean | PID Namespace Isolation: Restricts process visibility. When enabled, processes running inside the sandbox cannot see or interact with processes on the host system. *(Defaults to `true`)*. | | `user_ns` | Boolean | User Namespace Mapping: Determines if root operations are mapped to an unprivileged host user. *(Defaults to `false`)*. | #### Network Configuration (`network`) The `network` block defines how the sandbox interacts with internal and external networks. | **Parameter** | **Type** | **Description** | | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enable` | Boolean | Network Sandbox Enforcement: When disabled, the network namespace isolation layer is bypassed, blocking or overriding dynamic interface generation for the instance. *(Defaults to `false`)*. | | `general.bridge` | String | Virtual Bridge Interface: The designated virtual network bridge identifier used for container network binding when networking is active. *(Defaults to `"bru0"`)*. | | `general.gateway` | String | Default Gateway: The IPv4 target destination routing address for network packets escaping the sandbox interface. *(Defaults to `"10.0.0.1"`)*. | | `firewall` | Null / Object | Firewall Access Control List: Granular firewall filters, iptables, or routing rules applied to this specific profile. *(Defaults to `null`)*. | ### Policy-Driven Configuration Examples Centralizing security logic within the policy file reduces manual input errors and ensures consistent enforcement across environments. #### 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/bluerock-0.0.1-py3-none-any.whl # Initialize BlueRock sensor $ python -m bluerock --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). Ensure the following files are present in the `mcp-observability` directory: * [`mcp_client.py`](/glossary/appendix#mcp-client-script-python) * [`mcp_fileserver.py`](/glossary/appendix#mcp-file-server-http-python) * [`mcp_fileserver_stdio.py`](/glossary/appendix#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 [BlueRock Policy Builder](/policy-configuration/policy-builder#step-1-create-signing-key-and-certificate) 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 %} ### **Network Firewall Configuration** Network profile defines how a program running inside the sandbox connects to external network services. {% hint style="info" icon="notes-sticky" %} Only one network firewall can be configured for the Sandbox policy. {% endhint %} * **Egress (*****Outbound*****)**: Allows programs in the sandbox to reach external network services. Parameters - IP, port, protocol *For example*: An agent program running inside the sandbox is restricted to access a specific LLM provider. * **Ingress (*****Inbound*****)**: Allows inbound connections from a specific host to the server program running inside the sandbox on a specific port and protocol *For example:* Allows an MCP client program from a specific source address to connect to the MCP server program running on a specific port {% code title="bru\_policy.json" lineNumbers="true" %} ```json "network": { "enable": true, "general": { "bridge": "bru0", "gateway": "10.0.0.1" }, "firewall": {"options": {"allow_icmp": true, "log_drops": true}, "ingress": {"published_ports": [{"container_port":8001, "host_bindings": [{"host_ip": "0.0.0.0", "host_port": 8001}]}]}, "egress": {"allow_to": [{"addr": "8.8.8.8", "ports": [], "proto": ["tcp", "udp"]}, {"addr": "api.openai.com", "ports": [], "proto": ["tcp", "udp"]}, {"addr": "api..com", "ports": [], "proto": ["tcp", "udp"]}]}} } ``` {% endcode %} | **Parameter** | **Type** | **Description** | | ------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `network.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) the network configuration. | | `network.general.bridge` | String | The name of the virtual bridge interface designated for this network (e.g., `bru0`). | | `network.general.gateway` | String | The IPv4 address assigned as the network gateway (e.g., `10.0.0.1`). | | `network.firewall.options.allow_icmp` | Boolean | Determines whether ICMP traffic (such as ping requests) is permitted through the firewall. | | `network.firewall.options.log_drops` | Boolean | When enabled, logs all network packets that are dropped by the firewall rules. | | `network.firewall.ingress.published_ports` | Array of Objects | A list of port mapping definitions for inbound traffic to the container. | | `...published_ports[].container_port` | Integer | The specific port number inside the container that will receive the routed traffic. | | `...published_ports[].host_bindings` | Array of Objects | Specifies how the internal `container_port` maps to the host's external network interfaces. | | `...host_bindings[].host_ip` | String | The host IP address to bind the port to. Use `0.0.0.0` to bind to all available IPv4 interfaces. | | `...host_bindings[].host_port` | Integer | The external port number exposed on the host machine. | | `network.firewall.egress.allow_to` | Array of Objects | A list of strict outbound rules defining permitted external destinations for container traffic. | | `...allow_to[].addr` | String | The destination IPv4 address (e.g., `8.8.8.8`) or Fully Qualified Domain Name (FQDN) (e.g., `api.openai.com`) permitted for egress. | | `...allow_to[].ports` | Array of Integers | An array of specific destination ports allowed for the defined address. An empty array typically implies no port restrictions for the specified protocols. | | `...allow_to[].proto` | Array of Strings | The network protocols permitted for this egress rule (e.g., `["tcp", "udp"]`). | {% 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 using `trex.py`, and uploading the repackaged files. Refer to the [BlueRock Policy Builder](/policy-configuration/policy-builder#step-1-create-signing-key-and-certificate) for detailed instructions. {% endhint %} ### Seccomp Interception Rules & Monitor Constraints When `syscalls.enable = true` is set in your configuration profile, the engine actively injects custom seccomp filters into the container sandbox initialization routine using `SCMP_ACT_NOTIFY` vectors. The parent engine runs an isolated asynchronous loop that monitors matching system hooks, intercepts process namespaces, reads the context block, and emits the structured telemetry. **Policy Reference Configurations** Use these minimal structures to enforce active tracking for audited domains: **Suspicious Syscalls Tracker (**`suspicious_syscalls`**)**\ Intercepts unauthorized privilege escalation or host namespace jailbreak vectors. ```json "suspicious_syscalls": { "enable": true, "remediate": false, "allow_unshare": false, "allow_ptrace": false } ``` | **Parameter** | **Type** | **Description** | | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `suspicious_syscalls.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) the monitoring and evaluation of suspicious system calls. | | `suspicious_syscalls.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking or terminating the process) when a suspicious syscall is detected. | | `suspicious_syscalls.allow_unshare` | Boolean | Controls whether the `unshare` system call is permitted. When disabled, it prevents processes from detaching namespaces (often restricted for security isolation). | | `suspicious_syscalls.allow_ptrace` | Boolean | Controls whether the `ptrace` system call is permitted. When disabled, it prevents unauthorized process tracing, debugging, or memory inspection. | **Process Execution (**`execve` or `execveat`**)** Generates telemetry indicators whenever `execve` or `execveat` are handled inside the container. ```json "exec": { "enable": true, "track_clone": false } ``` | **Parameter** | **Type** | **Description** | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `exec.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) execution monitoring and related policies. | | `exec.track_clone` | Boolean | Controls whether the system tracks process creation events (such as `clone` or `fork` system calls) as part of the execution policy. | **Filesystem Interface Tracker (**`allow_read_only`**)** Tracks namespace interactions. Toggling `"allow_read_only": true` reduces metric noise by omitting read operations. ```json "open": { "enable": true, "remediate": false, "allow_read_only": true } ``` | **Parameter** | **Type** | **Description** | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for file open operations. | | `open.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the operation) when an unauthorized file open request is detected. | | `open.allow_read_only` | Boolean | Controls whether read-only file access is permitted by default. When enabled, it allows processes to open files strictly for reading, even if broader access restrictions are in place. | **Staging Memory Execution Tracker (`mmap_exec`)**\ Tracks fileless execution strategies and dynamic memory allocations inside the container sandbox space. ```json "mmap_exec": { "enable": true, "remediate": false } ``` | **Parameter** | **Type** | **Description** | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mmap_exec.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) the monitoring and policy evaluation of memory regions mapped with execution permissions (e.g., `PROT_EXEC`). | | `mmap_exec.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the mapping request) when an unauthorized executable memory mapping is detected. | 1. **Operational Impact:** \ Generates a `brace_mmap_exec` telemetry signature whenever a process requests an `mmap` allocation flagged with `PROT_EXEC` modifications, or attempts to `execve` target an anonymous memory descriptor (`/memfd:`). 2. **Enforcement Behavior:** \ Structural prevention blocks are unique to high-risk traps. If a fileless execution mechanism violates the staging policy, remediation flags can be enabled to block the memory allocation lifecycle. **Network Socket Tracking Interface (`socket`)**\ Captures raw endpoint instantiation handles at the container namespace boundary. ```json "socket": { "enable": true, "remediate": false } ``` | **Parameter** | **Type** | **Description** | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `socket.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for network socket creation and operations. | | `socket.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the operation) when an unauthorized socket request is detected. | 1. **Operational Impact:** \ Dispatches a `brace_socket` data block immediately when the `socket()` system call is processed inside the sandbox. 2. **Observe-Only Baseline:** \ This hook functions in an observe-only validation scope. The configuration captures the underlying protocol arrays (such as `AF_INET` or `SOCK_STREAM`) for audit baselines without introducing runtime structural latency. **Network Connection Tracker (`connect`)**\ Monitors bi-directional outbound connectivity and tracking state handshakes. ```json "connect": { "enable": true, "remediate": false } ``` | **Parameter** | **Type** | **Description** | | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connect.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for outbound network connection attempts (e.g., the `connect` system call). | | `connect.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the connection attempt) when an unauthorized network connection is detected. | 1. **Operational Impact:** \ Evaluates the container's raw process memory directly on a `connect()` execution request. The interface translates destination headers into human-readable IP or Unix socket address strings (such as `1.2.3.4:port` or `unix:/path/to/sock`) inside the `brace_connect` log output. 2. **Observe-Only Baseline:** \ Operates under an observe-only posture. This hook does not drop traffic directly; enforcement is entirely delegated to host-level egress network firewall rules to minimize path friction. **Filesystem Deletion Tracker (`delete`)**\ Maintains an accurate audit trail of structural file and directory purging actions. ```json "delete": { "enable": true } ``` | **Parameter** | **Type** | **Description** | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `delete.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for file or resource deletion operations (e.g., `unlink` or `rmdir` system calls). | 1. **Operational Impact:** \ Triggers a `brace_delete` tracking log upon any valid call to `unlink`, `unlinkat`, or `rmdir` system commands. 2. **Metadata Structure:** \ Emits absolute resolved paths along with a boolean `is_dir` flag to distinguish regular file drops from full directory removals within the security metrics stream. This trap is always permitted through for observation. ### Sensitive File Access (`sensitive_file_access`) Monitors real-time interactions with critical system configurations, credential storage locations, and environmental identity blocks. ```json "sensitive_file_access": { "enable": true, "remediate": false, "paths": [ { "path": "/etc/shadow", "write_only": false }, { "path": "/etc/sudoers", "write_only": false }, { "path": "/etc/passwd", "write_only": true } ], "exceptions": [ { "program": "/usr/sbin/sshd", "file": "**/*" } ] } ``` | **Parameter** | **Type** | **Description** | | ---------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sensitive_file_access.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for interactions with designated sensitive files. | | `sensitive_file_access.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the access attempt) when an unauthorized interaction with a sensitive file is detected. | | `sensitive_file_access.paths` | Array of Objects | A list of specific file paths designated as sensitive, along with their access evaluation criteria. | | `...paths[].path` | String | The absolute directory or file path to be monitored (e.g., `/etc/shadow`). | | `...paths[].write_only` | Boolean | Controls the scope of monitoring for the specific path. When `true`, alerts or remediation only trigger upon modification (write) attempts. When `false`, any access (read or write) triggers the policy. | | `sensitive_file_access.exceptions` | Array of Objects | A list of rules defining trusted processes permitted to bypass the sensitive file access restrictions. | | `...exceptions[].program` | String | The absolute path to the executable program authorized for the exception (e.g., `/usr/sbin/sshd`). | | `...exceptions[].file` | String | The specific file path or glob pattern (e.g., `**/*`) that the authorized program is permitted to access without triggering a violation. | 1. **Operational Impact:** \ Evaluates standard file open requests against a predefined file-path array to detect unauthorized access to system configurations, tracking operations through the `sensitive_file_access_violation` observability signature. 2. **Granular Read/Write Mechanics:** \ Adjusts alert tracking structures by matching paths with a declarative boolean flag. Setting `write_only: false` enables bi-directional audit logging to catch both read actions (such as a `cat` command) and write modifications on target paths. Setting `write_only: true` suppresses read notifications to isolate alerts strictly to modification attempts on asset stores (such as user group files or network resolution configurations). 3. **Automated Exceptions Mapping:** \ Processes fine-grained exemptions to eliminate false positive noise from validated system utilities. Whitelisted operations (such as authentication lookups from the `sshd` daemon or privilege changes via `sudo`) bypass violation filters, matching entries without dispatching security logging events. ### Process Guard (`process_guard`) Manages binary execution parameters inside the container space to prevent post-exploit tool execution and remote script injections. ```shellscript "process_guard": { "enable": true, "remediate": false, "allow": [ "/bin/**", "/usr/bin/**" ], "deny": [ "**/nc", "**/wget", "**/curl" ], "deny_exceptions": [ { "path_pattern": "**/bin/bash", "comm_list": ["setup-policy-ro"] } ] } ``` | **Parameter** | **Type** | **Description** | | ----------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `process_guard.enable` | Boolean | Master toggle to enable (`true`) or disable (`false`) monitoring and policy evaluation for process execution based on allow/deny lists. | | `process_guard.remediate` | Boolean | Determines whether the system should take automatic enforcement action (such as blocking the process creation) when an unauthorized process execution is detected. | | `process_guard.allow` | Array of Strings | A list of explicit file paths or glob patterns (e.g., `/bin/**`) designating executables that are permitted to run. | | `process_guard.deny` | Array of Strings | A list of explicit file paths or glob patterns (e.g., `**/wget`) designating executables that are strictly prohibited from running. | | `process_guard.deny_exceptions` | Array of Objects | A list of granular rules defining specific exceptions to the broader deny list. | | `...deny_exceptions[].path_pattern` | String | The path or glob pattern of the executable (e.g., `**/bin/bash`) that is granted an exception under specific conditions. | | `...deny_exceptions[].comm_list` | Array of Strings | A list of permitted command names (typically mapped to the Linux `comm` value) that are authorized to execute the file matched by the `path_pattern`, bypassing the deny rule. | 1. **Operational Impact:** \ Validates process execution calls (`execve`, `execveat`) against declarative directories, triggering an automated `process_guard_violation` event whenever a disallowed binary or unlisted path structure matches active block restrictions. 2. **Intrusion Isolation Blocklists:** \ Enforces a persistent deny matrix to target binaries frequently abused during payload deployment stages. Execution attempts matching ingestion or scripting tools (such as `curl`, `wget`, or Netcat) are systematically blocked and reported to telemetry pools. 3. **Contextual Deny Overrides:** \ Evaluates targeted exceptions based on explicit execution contexts to permit safe administration actions. Regulated binaries (such as a standard `bash` shell) are permitted to run only if the execution sequence maps directly to a trusted system initialization wrapper (such as `setup-policy-ro`). # Policy Builder The BlueRock Secure MCP Server consumes a signed policy blob generated using the TREX tool. The TREX tool performs the following operations: 1. Generate a policy template 2. Manually edit the generated policy template JSON file to define the required policy rules 3. Sign the policy and generate a signed policy blob (.tar) After the signed policy blob is generated, the following manual steps are required: 4. Extract the signed policy blob to obtain the policy file (policy.json) and signature file (policy.json.sig) 5. Upload the extracted policy files to the configured cloud storage bucket for UC retrieval UC verifies the policy signature during startup before loading it. *** ### TREX Tool Location On BlueRock Node AMI (Amazon Linux 2023 and Ubuntu 24.04): ```shellscript /opt/bluerock/trex ``` *** ### Step 1: Create Signing Key and Certificate Navigate to the TREX tool directory: ```shellscript cd /opt/bluerock/trex ``` Generate a private key and self-signed certificate: ```shellscript openssl req -x509 -newkey rsa:4096 \ -keyout dynpol_key.pem \ -out dynpol_cert.pem \ -sha256 -days 3650 -nodes \ -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" ``` Extract the public key from the certificate: ```shellscript openssl x509 -pubkey -noout -in dynpol_cert.pem > dynpol_pubkey.pem ``` *** ### Step 2: Configure trex.toml Create a `trex.toml` file under `/opt/bluerock/trex` with the following configuration: ```yaml [incoming] sig_required = false sig_hash = "sha256" public_key_pem = "dynpol_cert.pem" [outgoing] sig_required = true sig_hash = "sha256" private_key_pem = "dynpol_key.pem" private_key_passphrase = "" ``` This enables TREX tool to sign outgoing policies using SHA256. *** ### Step 3: Activate TREX Python Environment The TREX Python virtual environment is pre-created on the BlueRock node: ```shellscript source /opt/bluerock/trex/py312/bin/activate ``` *** ### Step 4: Generate Policy Template Generate a policy model file for EC2 deployments: ```shellscript cp bru_policy.json.template bru_policy.json ``` The generated JSON file contains the policy template with default values. Edit the generated JSON file to define required policy rules. Example MCP Protection Configuration: ```shellscript "mcp": { "enable": true, "remediate": false } ``` Policy enforcement behavior is controlled using the `remediate` flag. * `remediate: false` → observe mode * `remediate: true` → enforce mode *** ### Step 5: Generate Signed Policy Blob Generate the signed policy package: ```shellscript python trex.py .json Example: python trex.py bru_policy.json ``` This produces: ```shellscript bru_policy.tar ``` Extract the archive: ```shellscript tar xvf bru_policy.tar ``` The extracted files include: * `policy.json` * `policy.json.sha256` * `policy.json.sig` These files are required for policy verification by UC. **Note:** The policy filename can be any valid JSON file name. There is no mandatory naming requirement. *** #### Step 6: Upload Policy Files to S3 The EC2 instance hosting the BlueRock runtime must be associated with an **IAM role that allows access to the S3 bucket storing the policy files**.\ This IAM role must allow the instance to **read policy artifacts during runtime policy retrieval**. Example IAM policy: ```shellscript { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ] } ] } ``` This policy allows the EC2 instance to: * list objects in the policy storage bucket * download the policy file and signature file required for runtime verification After configuring the IAM role, upload the policy files to the configured S3 bucket. Example: ```shellscript aws s3 cp policy.json s3://buv-dynamic-policy/bru_policy.json aws s3 cp policy.json.sig s3://buv-dynamic-policy/bru_policy.json.sig aws s3 cp dynpol_pubkey.pem s3://buv-dynamic-policy/dynpol_pubkey.pem ``` *** ### Policy Verification During UC startup: 1. Policy files are downloaded from S3 2. SHA256 hash is verified 3. Digital signature is validated using the public key 4. Policy is loaded if verification succeeds If verification fails: * The invalid policy is not applied * An error is logged * The service continues running ### Policy Package Content Every valid policy deployment requires the following files in the Cloud Storage: | File | Purpose | | ----------------- | --------------------------- | | `policy.json` | Policy Blob | | `policy.json.sig` | Cryptographic signature | | `public.pem` | Public key for verification | The private key used for signing must never be uploaded. If there is a mismatch in the policy signature/ Wrong PUB key uploaded, Policy signature file is missing, or an incorrect version of TREX tool is used for the upload, the BlueRock Control Plane will reject the policy. # Policy Structure ### Overview BlueRock protection policies are configured using a JSON-based policy definition.\ This JSON file defines the runtime enforcement behavior for: * MCP connection controls * Tool, prompt, and resource restrictions * Pattern-based detection * Execution controls * Optional sandbox and network settings All runtime behavior is determined by this policy configuration. Policies are generated and signed using the TREX tool before being uploaded to S3 and consumed by the BlueRock Control Plane. *** ### High-Level Policy Structure A typical policy contains the following top-level sections: ```json { "mcp": {}, "exec": {}, "options": {}, "network": {} } ``` | Section | Purpose | | --------- | ------------------------------------- | | `mcp` | MCP client-server protection policies | | `exec` | Execution control configuration | | `options` | Sandbox and namespace settings | | `network` | Firewall enforcement configuration | *** ## MCP Protection Configuration ### Enable MCP Protection ```json "mcp": { "enable": true, "remediate": true } ``` | Parameter | Description | | ---------------- | ---------------------------------- | | enable | Activates MCP policy evaluation | | remediate: true | Enforce mode (block violations) | | remediate: false | Observe mode (log violations only) | *** ### HTTP / SSE Connection Control ```json "http_servers": { "deny_http": false, "deny_sse": false, "exception_list": [], "force_authentication": true } ``` | Parameter | Description | | --------------------- | -------------------------------------- | | deny\_http | Block HTTP transport | | deny\_sse | Block SSE transport | | exception\_list | Allow specific URLs | | force\_authentication | Require authenticated HTTP connections | *** ### stdio Transport Control ```json "stdio": { "deny_stdio": true, "exception_list": [ { "command": "python", "args": "mcp_test_server.py" } ] } ``` Blocks stdio-based MCP server connections.\ Allows only explicitly listed command/argument combinations. *** ### Tool Execution Policies #### Deny Specific Tool ```json "tools": { "Linux admin Server": { "deny_list": ["run_command"] } } ``` Blocks execution of specific tools from a defined MCP server. *** #### Tool Argument Pattern Detection ```shellscript "forbidden_tool_argument_patterns": [ "[;&|`$]\\s*(?:whoami|id|pwd|ls|cat|curl|wget|nc|bash|sh|cmd\\.exe|powershell)", "\\$\\((?:cmd\\.exe|powershell).*?\\)", "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})", "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)", "\\b(?:sudo|su|doas)\\s+\\w+", "shell_exec\\s*\\(", "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b", "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b" ] ``` If a tool argument matches these patterns: * Enforce mode → Execution blocked * Observe mode → Execution allowed, violation logged *** #### Tool Response Pattern Detection ```shellscript "forbidden_tool_response_patterns": [ "[;&|`$]\\s*(?:whoami|id|pwd|ls|cat|curl|wget|nc|bash|sh|cmd\\.exe|powershell)", "\\$\\((?:cmd\\.exe|powershell).*?\\)", "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})", "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)", "\\b(?:sudo|su|doas)\\s+\\w+", "shell_exec\\s*\\(", "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b", "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b", "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b", "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b", "\\b(?:iptables|ufw|firewall-cmd)\\b" ] ``` Prevents sensitive or high-risk content in tool output. *** ### Resource Access Control ```json "resources": { "Linux admin Server": { "deny_list": ["file://"] } } ``` Restricts file-based or URI-based resource access. *** ### Prompt Execution Policies #### Deny Specific Prompt ```json "prompts": { "Linux admin Server": { "deny_list": ["useful_helper_prompt"] } } ``` *** #### Prompt Argument Pattern Detection ```json "forbidden_prompt_arg_patterns": [ "\\b(?:bash|sh|curl|wget|nc)\\b" ] ``` *** #### Prompt Response Pattern Detection ```json "forbidden_prompt_response_patterns": [ "\\b(?:curl|wget|ssh|nc)\\b" ] ``` *** ## Execution and Sandbox Configuration The following sections configure execution and sandbox enforcement.\ Detailed runtime behavior is documented separately under BRACE runtime documentation. *** ### Execution Policy (`exec`) Controls binary execution behavior. ```shellscript "exec": { "enable": true, "remediate": true, "is_deny_list": false, "match_list": [] } ``` | Field | Description | | -------------- | ---------------------------- | | enable | Enables execution control | | remediate | Enforce or observe mode | | is\_deny\_list | true → block listed binaries | | match\_list | Binaries to allow or deny | *** ### Sandbox Options (`options`) Defines namespace and bind mount settings. ```shellscript "options": { "bind_mount": { "enable": true, "mount_proc": true, "mounts": [] }, "pid_ns": true, "root": false } ``` Controls filesystem isolation and namespace configuration. *** ### Network Firewall Configuration (`network`) ```shellscript "network": { "enable": true, "general": {}, "firewall": {} } ``` Defines network firewall enforcement rules used by runtime policies. *** ## Complete Example Policy Below is a minimal production-style policy configuration: ```shellscript { "mcp": { "enable": true, "remediate": true, "client": { "tools": { "Linux admin Server": { "deny_list": ["run_command"] } }, "prompts": {}, "resources": {}, "http_servers": { "deny_http": false, "deny_sse": false, "exception_list": [], "force_authentication": true }, "stdio": { "deny_stdio": true, "exception_list": [] } } }, "exec": { "enable": true, "remediate": true, "is_deny_list": false, "match_list": ["/usr/bin/date"] }, "options": { "bind_mount": { "enable": true, "mount_proc": true, "mounts": [] }, "pid_ns": true, "root": false }, "network": { "enable": false } } ``` *** # Policy Life Cycle The complete lifecycle of a policy is as follows: | Stage | Component | Description | | ----------------------------------- | ------------------------- | --------------------------------------------------- | | Policy Authoring | JSON Format / TREX Tool | Generating the Policy template/modifying the Policy | | Generating Signed Policy Blob | Key Pairs / TREX Tool | Policy integrity protected | | Publishing the Policy Blob | Cloud Storage (AWS / GCP) | Policy uploaded | | Download, Validate and Apply Policy | BlueRock Control Plane | Verification of Policy Signature and Policy syntax | | Enforcement | BlueRock Control Plane | Rules are evaluated at Program Run-time | | Observability | BlueRock Control Plane | Source Events and Violations are logged | ### Policy Source Configuration The BlueRock Runtime (bluerockd) loads its configuration from the local configuration file: `/etc/bluerock/bluerock.toml` The `bluerock.toml` configuration file defines the following parameters: * Runtime settings * Policy storage bucket name * Policy file name * Policy signature file name * Public key used for signature verification * Policy polling interval * Transport authentication settings * Storage bucket region * OTLP event export configuration If the signature validation fails, the policy will not be loaded. Example configuration: ```yaml [runtime] metrics_timer = 1800 state_dir = "/var/lib/bluerockd/" [policy] public_key = "s3://buv-dynamic-policy/dynpol_pubkey.pem" poll_period = 300 [policy.source] location = "s3://buv-dynamic-policy/" policy = "policy.json" policy_sig = "policy.json.sig" [policy.source.transport] auth_method = "default" region = "us-east-2" [policy.engine] augment_events = true [otlp] file = "/var/log/bluerockd/otel-events.log" [otlp.http] url = "http://:4318/" ``` *** ### When a Policy Is Applied Policies are applied at runtime by the BlueRock Control Plane service. The service periodically checks the policy source configured in `bluerock.toml` for updates and loads the latest valid policy. Policy application occurs in the following situations: 1. When the BlueRock Control Plane service starts or restarts. 2. When a newer policy version is detected in the configured cloud storage location during periodic checks. #### Policy Loading Workflow 1. The BlueRock Runtime (bluerockd) reads the local bluerock.toml configuration file. 2. It connects to the configured policy storage location (for example an S3 bucket). 3. The service checks whether a newer policy version is available. 4. If a new version is detected, the policy package is downloaded. 5. The policy signature is verified using the configured public key. 6. If verification succeeds, the policy configuration is validated. 7. The validated policy is applied to the BlueRock sensors (App Sensors and Kernel Sensors) for runtime enforcement. 8. Sensors generate MCP events and evaluate them against the configured policy rules during MCP client–server interactions. 9. Violations are exported through OpenTelemetry (OTEL) using OTLP streams to external observability systems such as AWS CloudWatch or Google LogExplorer. If signature verification or policy validation fails, the policy is rejected and the system continues using the previously active or default built-in policy. *** ### Enforcement Modes Policies support two enforcement modes: | Mode | Behavior | | ------------------------- | ------------------------------------------ | | observe (remediate:false) | Log violations but allow program execution | | enforce (remediate:true) | Block program execution and log violation | *** ## Policy Generation and Signing using TREX tool *** ## Validation Overview After uploading the policy artifacts and restarting the BlueRock Control Plane service, validation should confirm that the policy was successfully retrieved, verified, and applied by the BlueRock runtime. Validation includes the following checks: 1. Confirm BlueRock Control Plane service is running 2. Confirm policy download and signature verification in runtime logs 3. Confirm policy lifecycle events in CloudWatch (OTEL telemetry) 4. Trigger rule condition 5. Confirm runtime activity after policy execution *** ## 1. Confirm BlueRock Control Plane Service Is Running Verify that the BlueRock Control Plane service is running on the instance. ```shellscript sudo systemctl status bluerockd.service ``` Example output: ```shellscript ● bluerockd.service - BlueRock Runtime Service Loaded: loaded (/etc/systemd/system/bluerockd.service; disabled; preset: disabled) Active: active (running) since Wed 2026-03-04 12:43:28 UTC Main PID: 3714 (bluerockd.sh) Tasks: 2 Memory: 2.4M CPU: 4.843s CGroup: /system.slice/bluerockd.service ├─3714 /usr/bin/bash /opt/bluerock/bin/bluerockd.sh start └─4055 sleep 5 Mar 04 12:43:28 ip-172-31-22-98.us-east-2.compute.internal systemd[1]: Started bluerockd.service - BlueRock Runtime Service. ``` This confirms that the BlueRock Control Plane service is active and running. *** ## 2. Confirm Policy Download and Signature Verification in Runtime Logs Check the BlueRock Control Plane service logs to confirm that the policy has been downloaded and applied. ```shellscript journalctl -u bluerockd.service ``` Example output: ```shellscript 2026-03-04T12:43:28.302213+00:00 ip-172-31-22-98 kernel: brs_policy: Cleared brs_configuring_task (was PID 3644) 2026-03-04T12:43:29.308937+00:00 ip-172-31-22-98 bluerockd.sh: Starting bluerockd.sh 2026-03-04T12:43:29.322074+00:00 ip-172-31-22-98 bluerockd.sh: Bluerockd starting 2026-03-04T12:43:34.573057+00:00 ip-172-31-22-98 kernel-sensor.sh: starting kernel-sensor.sh 2026-03-04T12:43:34.585662+00:00 ip-172-31-22-98 kernel-sensor.sh: launching kernel-sensor 2026-03-04T12:43:34.593384+00:00 ip-172-31-22-98 kernel: brs_policy: Updated brs_configuring_task to point to PID 3851 2026-03-04T12:43:34.732971+00:00 ip-172-31-22-98 kernel: BR config: Loaded a policy of 2248 bytes ``` The log entry below confirms that the BlueRock runtime successfully loaded the generated policy: ``` BR config: Loaded a policy of 2248 bytes ``` *** ## 3. Confirm Policy Lifecycle Events in CloudWatch (OTEL Telemetry) BlueRock emits OpenTelemetry (OTEL) telemetry events during the policy lifecycle process. These events provide visibility into policy retrieval, validation, and application during runtime startup. To verify these events: 1. Open the **AWS CloudWatch Console** 2. Navigate to: ```shellscript Logs → Log groups ``` 3. Open the BlueRock telemetry log group: ```shellscript bluerock-1-TelemetryLogGroup ``` 4. Select the latest log stream: ```shellscript bluerock-1-TelemetryLogStream ``` 5. Locate the policy lifecycle events generated during service startup. These events are emitted by the **BlueRock Control Plane - Policy Control Manager (PCM)** component running on the deployed EC2 instance. *** ## Example OTEL Policy Lifecycle Events #### Policy Download Attempt ```json { "body": { "action": "policy_download_attempt", "delay": 300, "error": null, "startup_state": "WarmStartup" }, "severity_text": "INFO", "attributes": { "domain": "pcm", "event_name": "policy_lifecycle", "hostid": "bluerocknode1-ip-10-0-1-54" }, "scope": { "name": "uc-pcm" }, "resource": { "service.name": "bluerock" } } ``` *** #### Policy Download Started ```json { "body": { "action": "policy_download_started", "startup_state": "WarmStartup" }, "severity_text": "INFO", "attributes": { "event_name": "policy_lifecycle" } } ``` *** #### Policy Download Completed ```json { "body": { "action": "policy_download_completed", "error": null, "startup_state": "WarmStartup" }, "severity_text": "INFO", "attributes": { "event_name": "policy_lifecycle" } } ``` *** #### Policy Download Success ```json { "body": { "action": "policy_download_success", "delay": 300, "error": null, "startup_state": "WarmStartup" }, "severity_text": "INFO", "attributes": { "event_name": "policy_lifecycle" } } ``` *** This sequence confirms that the BlueRock Control Plane successfully downloaded, validated, and applied the configured runtime policy. *** ## **4. Confirm Runtime Policy Is Loaded** Check the BlueRock Runtime logs to confirm that the policy has been successfully loaded. Example command: ```shellscript journalctl -u bluerockd.service ``` Example output: ```shellscript 2026-03-04T12:43:34.593384+00:00 ip-172-31-22-98 kernel: brs_policy: Updated brs_configuring_task to point to PID 3851 2026-03-04T12:43:34.732971+00:00 ip-172-31-22-98 kernel: BR config: Loaded a policy of 2248 bytes ``` This confirms that the runtime policy engine has successfully loaded the configured policy. ## 5. Trigger Rule Condition Run commands that generate runtime activity to trigger policy evaluation and produce event logs for any policy violations (WARN or ERROR). Example command: ```shellscript curl http://example.com ``` This command generates a network request event, allowing the runtime policy engine to evaluate activity on the host. *** ## **6. Verify Policy Evaluation in Logs** Re-check the runtime logs to confirm that the rule evaluation and any violations are recorded. # Agent Frameworks Integration The BlueRock runtime provides native telemetry tracing for multiple agent ecosystems, including **LangChain**, **CrewAI**, **Anthropic**, **Google Agent Development Kit (ADK)**, **OpenAI**, and **LiteLLM**. By embedding the `bluerock` sensor directly into the execution space, the BlueRock runtime automatically hooks into internal orchestration and lifecycle engines. The integration requires no architectural changes to the codebase and no manual analytics callbacks. {% hint style="success" icon="lightbulb-exclamation-on" %} I**mportant:** The telemetry tracing feature is supported only on the BlueRock Ubuntu or AL2023 Virtual Machine (VM). The system does not support this feature on a generic Ubuntu Linux VM. {% endhint %} ## Core Architecture
The architecture remains consistent across all BlueRock agent integrations: 1. Agent Execution Space: The environment where the specific agent program runs alongside the `bluerock` sensor. The environment must operate within a BlueRock Ubuntu or AL2023 VM. 2. Event Collector: The component capturing telemetry from the execution space. 3. bluerockd: The BlueRock Control Plane processing intercepted execution tasks and intents. 4. CloudWatch or External Event Collector: The final destination for aggregated telemetry and logs. ## Environment Setup ### Prerequisites * [Python version 3.13](https://www.python.org/downloads/release/python-3130/) or above. * Package Manager: Install `uv` for dependency management and execution. ### Framework Configuration Reference Different frameworks require specific primary packages and example scripts. The project name parameter can be any string (for example, `search_agent` or `file_agent`); enter the desired project name when substituting the `` placeholder. Reference the table below when substituting the remaining placeholder values in the subsequent setup steps.
Framework<Package_Name>Example Scripts
LangChainlangchainchat_agent.py
CrewAIcrewaihelp_agent_crewai.py
Anthropicanthropicsearch_agent.py
Google ADKgoogle_adksearch_agent_gemini.py
OpenAIopenaihello_world_oai.py
LiteLLMlitellmsearch_agent_litellm.py
{% hint style="info" icon="notes-sticky" %} Note: The `` represents the primary framework entry point. Additional packages and adapters required by custom implementations (for example: `langchain_ollama`, `mcp`, or `fastmcp`) can be dynamically appended to the dependency installation command. {% endhint %} ### Install the `uv` Package Manager Run the installation script to install the package manager. ```shellscript $ curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### Provision the Isolated Project Environment Initialize the local project workspace using Python 3.13 (or above) and establish project dependencies using the target framework details from the reference table. ```shellscript $ uv init --python python3.13 $ cd $ uv venv --python python3.13 $ source .venv/bin/activate $ uv add [Additional_Packages...] ``` ### Inject and Register BlueRock Sensors Deploy the custom BlueRock telemetry sensor library directly within the activated workspace context. Activate runtime sensor hooks using the installation flag. ```shellscript $ uv pip install /opt/bluerock/python-dist/bluerock-0.0.1-py3-none-any.whl $ python -m bluerock --install ``` ### Stage the Agent Script Add the script based on the selected agent framework. If required, use the example scripts from BlueRock. ## Agent Execution Block {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** * Bind appropriate authorization environment variables to the parent terminal session to initiate runtime actions. * The **Anthropic**, **LiteLLM**, **LangChain**, and **CrewAI** scripts use the `OPENAI_API_KEY` environment variable as a standard label, whereas accept native Large Language Model (LLM) API keys for authentication. {% endhint %} ### Execution Variable Reference Reference the table below when substituting placeholder values in the execution commands.
Framework<API_Key_Variable>
LangChainOPENAI_API_KEY
CrewAIOPENAI_API_KEY
AnthropicOPENAI_API_KEY
Google ADKGOOGLE_API_KEY
OpenAIOPENAI_API_KEY
LiteLLMOPENAI_API_KEY
### Local Execution Set the required environment variable and execute the primary workspace script using the package manager. ```shellscript $ export = $ uv run ``` ### Containerized Execution Run the target agent as a Docker application. Securely mount the BlueRock socket into the container. 
$ docker run -d --name <Container_Name> \
  --rm \
  -e <API_Key_Variable>=<api_key> \
  -v /run/bluerock:/run/bluerock \
  <Image_Name>
{% hint style="info" icon="notes-sticky" %} **Note:** `` can be any arbitrary name assigned to the container. `` must match the exact tag assigned when building or pulling the Docker image. Run `docker images` in the terminal to list all locally available images and corresponding tags. {% endhint %} ## Sensor Configuration and Telemetry Events The sensors are governed by the `bru_policy.json` configuration file, located in the `/opt/bluerock/trex/` directory on a BlueRock instance or VM. The policy defines separate configuration blocks to activate interception hooks for fundamental LLM calls versus higher-level agentic orchestration. Depending on the active ecosystem, the sensor automatically captures distinct execution and lifecycle events. ### **LLM Sensors** The `llm` block controls the tracing of direct interactions with foundational models. Activating specific vendor flags within this block allows the sensor to capture raw generation requests, tokens, and response latencies. {% code title="bru\_policy.json" lineNumbers="true" %} ```json "llm": { "enable": true, "gemini": true, "openai": true, "anthropic": true, "litellm": true } ``` {% endcode %} ### **Agentic Sensors** The Agentic configuration blocks (such as `crewai` and `langchain`) hook into multi-step reasoning, tool execution, memory retrieval, and agent delegation. These are enabled independently of the base LLM sensors. {% code title="bru\_policy.json" lineNumbers="true" %} ```json "crewai": { "enable": true }, "langchain": { "enable": true } ``` {% endcode %} ### Standardized Sample Events by Sensor Type #### LLM Sensors * OpenAI ```json { "body": { "context": { "process": { "pid": "" } }, "entity_id": "", "event": "chat_completion_start", "model": "gpt-4o", "messages": [ { "role": "user", "content": "Why is the sky blue?" } ], "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_openai_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` * Anthropic ```json { "body": { "context": { "process": { "pid": "" } }, "entity_id": "", "event": "message_create_start", "model": "claude-3-5-sonnet-20241022", "messages": [ { "role": "user", "content": "Hello, Claude. Why is the sky blue?" } ], "max_tokens": 1024, "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_anthropic_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` * LiteLLM ```json { "body": { "context": { "process": { "pid": "" } }, "entity_id": "", "event": "completion_start", "model": "claude-sonnet-4-5-20250929", "messages": [ { "role": "user", "content": "Hello, what is a rainbow?" } ], "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_litellm_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` #### Agentic Sensors * LangChain ```json { "body": { "chain_type": "AgentExecutor", "context": { "process": { "pid": "" } }, "entity_id": "", "event": "chain_start", "inputs": { "question": "What files do I have in the folder?" }, "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_langchain_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` * CrewAI ```json { "body": { "context": { "process": { "pid": "" } }, "entity_id": "", "event": "crew_kickoff_started", "crew_name": "AssistantCrew", "tasks": ["task_one"], "agents": ["Helpful assistant"], "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_crewai_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` * Google Gemini ```json { "body": { "context": { "process": { "pid": "" } }, "entity_id": "", "event": "agent_run_start", "agent_name": "search_agent", "model": "gemini-2.5-flash", "query": "why is the sky blue?", "run_id": "" }, "severity_number": 0, "severity_text": "INFO", "attributes": { "domain": "gyro", "event_name": "python_google_adk_event", "origin": "bluepython", "sensor_id": 0000 }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` # Agent-to-Agent (A2A) Agent-to-Agent (A2A) communication enables autonomous AI agents to interact, delegate tasks, and exchange data programmatically without human intervention. To resolve interoperability limitations between disparate AI frameworks (such as LangChain, CrewAI, or custom scripts), BlueRock implements a standardized communication layer comprising three core components: * **Standardized Protocol**: \ Uniform routing and endpoints that allow agents to exchange structured data reliably regardless of their underlying frameworks. * **AgentCard**: \ A discoverable configuration profile defining an agent's identity, supported skills, capabilities, and required input/output formats. * **Telemetry and Security**: \ Native tracking of inter-agent prompts and generated artifacts to monitor system behavior, audit workflows, and intercept potentially malicious payloads. {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** * Telemetry tracing and policy enforcement are supported exclusively on a BlueRock Ubuntu or AL2023 Virtual Machine (VM). Standard Linux environments are not supported. * Unsanitized data from external agents exposes applications to severe prompt injection attacks. Treat all external input, including `AgentCards`, messages, and artifacts, as untrusted, and fully sanitize this data before constructing LLM prompts in production environments. {% endhint %} ## Core Architecture
* **Agent Execution Space:** \ The isolated environment hosting the A2A server or client program alongside the embedded `bluerock` sensor. * **Customer-Managed A2A Program:** \ Application code built using the Python A2A SDK or sample scripts from the public repository that handles agent tasks, resolves AgentCards, and constructs prompt payloads. * **BlueRock Sensor (`bluerock`):**\ The runtime hook library is deployed inside the virtual environment that transparently intercepts A2A card requests, responses, and task executions. * **BlueRock Control Plane (`bluerockd`):**\ The background service dispatches policy rules to the sensor, receives intercepted telemetry events via socket, and exports OpenTelemetry (OTEL) logs. * **CloudWatch or External Event Collector:**\ The final storage and monitoring target for compliance audits and security dashboards. ## Environment Setup ### Prerequisites * [Python version 3.13](https://www.python.org/downloads/release/python-3130/) or above. * Package Manager: Install `uv` for dependency management and execution. ### Clone the Repository Build custom A2A scripts using the Python A2A SDK or leverage pre-built sample scripts from the A2A samples repository: Clone the public A2A sample repository and navigate to the desired agent directory: 
$ git clone https://github.com/a2aproject/a2a-samples.git
$ cd a2a-samples/samples/python/agents/helloworld/
### Install BlueRock Sensor & Load Sensor Install the custom BlueRock sensor module and then load the sensor into memory using the installation flag. ```shellscript $ uv pip install /opt/bluerock/python-dist/bluerock-0.0.1-py3-none-any.whl $ python -m bluerock --install ``` ### Policy Configuration Policies are defined in the policy template that resides at `/opt/bluerock/trex/`. The `a2a` policy block within the agentic sensor manages pattern matching, remediation controls, and transport-level enforcement for Agent-to-Agent interactions.\ \ To learn more about the policy changes and building it, refer to the [Policy Configuration section](/policy-configuration/policy-builder). #### Default Policy Template (`a2a`) ```json "a2a": { "enable": false, "remediate": false, "card_name_filter": { "enable": true, "remediate": true, "forbidden_card_name_patterns": [ "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )", "\\$\\((?:cmd\\.exe|powershell).*?\\)", "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})", "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)", "\\b(?:sudo|su|doas)\\s+\\w+", "shell_exec\\s*\\(", "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b", "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b", "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b", "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b", "\\b(?:iptables|ufw|firewall-cmd)\\b" ] }, "card_description_filter": { "enable": true, "remediate": true, "forbidden_card_description_patterns": [ "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )", "\\$\\((?:cmd\\.exe|powershell).*?\\)", "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})", "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)", "\\b(?:sudo|su|doas)\\s+\\w+", "shell_exec\\s*\\(", "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b", "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b", "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b", "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b", "\\b(?:iptables|ufw|firewall-cmd)\\b" ] }, "skills_description_filter": { "enable": true, "remediate": true, "forbidden_skills_description_patterns": [ "[;&|`$]\\s*(?:whoami |id |pwd |ls |cat |curl |wget |nc |bash |sh |cmd\\.exe |powershell )", "\\$\\((?:cmd\\.exe|powershell).*?\\)", "(?:curl|wget|nc|netcat).*?(?:-X\\s+POST|-d|--data).*?(?:(?i)https?://|[0-9]{1,3}\\.[0-9]{1,3})", "(?i)(?:~/.ssh/|\\.ssh/)(?:id_rsa|id_ecdsa|id_ed25519|authorized_keys|known_hosts)", "\\b(?:sudo|su|doas)\\s+\\w+", "shell_exec\\s*\\(", "\\b(?:bash|sh|zsh|fish|csh|tcsh)\\b", "\\b(?:ls|cat|grep|ps|rm|mv|cp|chmod|chown)\\b", "\\b(?:curl|wget|ssh|scp|rsync|nc|netcat)\\b", "\\b(?:systemctl|mount|umount|fdisk|lsblk)\\b", "\\b(?:iptables|ufw|firewall-cmd)\\b" ] }, "http_servers": { "enable": true, "remediate": true, "deny_http": false, "deny_websocket": false, "exception_list": [], "force_authentication": false } } ``` #### Policy Configuration Parameters
ParameterTypeDefaultDescription
a2a.enablebooleanfalseMain toggle to enable or disable the entire A2A sensor inspection block.
a2a.remediatebooleanfalseMain toggle to activate mitigation or blocking actions for detected A2A policy violations.
a2a.card_name_filter.enablebooleantrueEnables pattern inspection specifically on the Agent Card name field.
a2a.card_name_filter.remediatebooleantrueTriggers remediation/blocking when a forbidden pattern is matched in the card name.
a2a.card_name_filter.forbidden_card_name_patternsarray[string](RegEx List)Array of regex patterns used to flag unsafe commands or terms in the Agent Card name.
a2a.card_description_filter.enablebooleantrueEnables pattern inspection on the Agent Card description field.
a2a.card_description_filter.remediatebooleantrueTriggers remediation/blocking when a forbidden pattern is matched in the card description.
a2a.card_description_filter.forbidden_card_description_patternsarray[string](RegEx List)Array of regex patterns used to flag unsafe commands or credentials in the card description.
a2a.skills_description_filter.enablebooleantrueEnables pattern inspection on skill descriptions (skills[].description) advertised by the agent.
a2a.skills_description_filter.remediatebooleantrueTriggers remediation/blocking when a forbidden pattern is matched in any skill description.
a2a.skills_description_filter.forbidden_skills_description_patternsarray[string](RegEx List)Array of regex patterns used to flag dangerous binary or shell command usage within advertised skills.
a2a.http_servers.enablebooleantrueActivates transport-level inspection and policy rules for HTTP-based A2A endpoints.
a2a.http_servers.remediatebooleantrueEnforces active transport remediation when policy rules are violated.
a2a.http_servers.deny_httpbooleanfalseWhen set to true, blocks unencrypted HTTP traffic for A2A communications.
a2a.http_servers.deny_websocketbooleanfalseWhen set to true, blocks WebSocket connections used by A2A streaming channels.
a2a.http_servers.exception_listarray[string][]List of excluded URLs or hosts exempt from transport-level restrictions.
a2a.http_servers.force_authenticationbooleanfalseWhen set to true, enforces strict authentication requirements on incoming A2A card requests.
## Execution ### Running an A2A Program **Natively on a BlueRock Instance** Running the A2A Python program directly/natively on the BlueRock VM shell prompt. 1. Start the Server. \ Run the A2A agent server locally on port `9999`: ```shellscript $ uv run python __main__.py ``` \ Expected output: ```shellscript INFO: Started server process [82625] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit) ``` 2. Run the Test Client. \ In a separate host terminal session, execute the test client to verify communication: ```shellscript $ source .venv/bin/activate $ uv run python test_client.py ``` \ Expected Output: ```shellscript $Starting an internactive session with A2A Server [http://127.0.0.1:9999] Use `exit` to quit. user > What is a Cat? Initializes the A2ACardResolver instance with an HTTP client Successfully fetched the public agent card: --- Public Agent Card - Non-Streaming Call --- Initializing a non-streaming client. Response: task { id: "bf4a7874-8805-40c8-b3ee-717001ab8a2c" context_id: "268b7df9-9a2c-449e-b6e1-51cfabd3628b" status { state: TASK_STATE_COMPLETED message { message_id: "b1d9d5eb-b61c-46f8-99f4-1c7fa95f1a30" role: ROLE_AGENT parts { text: "Request is completed!" } } timestamp { seconds: 1786103559 nanos: 986411000 } } artifacts { artifact_id: "1a5604b0-8d51-4e56-8143-5ea07efb464e" parts { text: "Hello, World! I have received your request (What is a Cat?)" media_type: "text/plain" } } history { message_id: "cdeac187-0996-4b82-8551-faf26f5ec889" context_id: "268b7df9-9a2c-449e-b6e1-51cfabd3628b" task_id: "bf4a7874-8805-40c8-b3ee-717001ab8a2c" role: ROLE_USER parts { text: "What is a Cat?" } } history { message_id: "288438e2-a0bf-4f22-9213-291093f8f510" role: ROLE_AGENT parts { text: "Processing request..." } } } -- user > ``` ### Running an A2A Program as a Container (Docker) with BlueRock Sensor Running the A2A Python program as a container with BlueRock Sensor. 1. Create a Dockerfile.\ In the root directory of your A2A agent application, ensure you have a `Dockerfile` that installs dependencies and copies the BlueRock Sensor
```docker ARG PYTHON_VERSION=3.13 FROM python:${PYTHON_VERSION}-slim COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ WORKDIR /app COPY python-packages/*.deb python-packages/*.deb /app/ COPY ai_agents/python/a2a/hello_world_agent/agent_executor.py \ ai_agents/python/a2a/hello_world_agent/pyproject.toml \ ai_agents/python/a2a/hello_world_agent/__main__.py \ ai_agents/python/a2a/hello_world_agent/README.md /app/ RUN apt-get update && \ apt-get install -y --no-install-recommends curl vim net-tools && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* && \ dpkg -i *.deb *.deb && \ rm -f *.deb *.deb RUN pip install /opt/bluerock/python-dist/*.whl && \ python -m bluerock --install EXPOSE 9999 CMD ["uv", "run", ".", "--host", "0.0.0.0"] ``` 2. Build the Container Image Navigate to the directory containing your application files and build the Docker image: ```shellscript $ docker build -t helloworld-a2a-server:latest . ``` \ Expected Output: ```shellscript [+] Building 8.4s (10/10) FINISHED => [internal] load build definition from Dockerfile => => transferring dockerfile: 341B => [internal] load .dockerignore => [1/5] FROM docker.io/library/python:3.13-slim => [2/5] WORKDIR /app => [3/5] COPY . /app => [4/5] RUN pip install --no-cache-dir /tmp/bluerock-0.0.1-py3-none-any.whl uv => [5/5] RUN python -m bluerock --install => exporting to image => => naming to docker.io/library/helloworld-a2a-server:latest ``` 3. Run the Container Image. ```shellscript $ docker run -d \ --name helloworld-a2a-server \ -p 9999:9999 \ -v /run/bluerock:/run/bluerock \ helloworld-a2a-server:latest ``` \ Expected output: ```shellscript Using CPython 3.12.13 interpreter at: /usr/local/bin/python3 Creating virtual environment at: .venv Building helloworld @ file:///app Downloading pygments (1.2MiB) Downloading pydantic-core (2.0MiB) Downloading cryptography (4.5MiB) Downloaded pydantic-core Downloaded cryptography Downloaded pygments Built helloworld @ file:///app Installed 42 packages in 99ms INFO: Started server process [50] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit) ``` 4. Run the Test Client In a separate host terminal session, execute the test client to communicate with the containerized agent: ```shellscript $ uv run python test_client.py ``` \ **Expected Output:**
```shellscript Starting an internactive session with A2A Server [http://127.0.0.1:9999] Use `exit` to quit. user > What is a cat? Initializes the A2ACardResolver instance with an HTTP client Successfully fetched the public agent card: ... Response: task { id: "78a383c3-1934-4859-bb46-b79692bc2c59" status { state: TASK_STATE_COMPLETED } artifacts { parts { text: "Hello, World! I have received your request (What is a cat?)" media_type: "text/plain" } } history { role: ROLE_USER parts { text: "What is a cat?" } } } ``` ## **Example OTEL Event** Below is an example of the OpenTelemetry event captured by the BlueRock sensor daemon during an A2A task invocation and exported to CloudWatch: ```json { "resource": { "service.name": "bluerock" }, "scope": { "name": "bluerockd" }, "attributes": { "domain": "gyro", "origin": "bluepython", "event_name": "python_a2a_event", "component_id": "default/", "hostid": "ip-.compute.internal", "sensor_id": 7222, "type": "event" }, "body": { "event": "client_recv_response", "card": "Hello World Agent", "server": "http://:9999", "result": { "task": { "id": "", "contextId": "", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2026-08-07T14:14:06.991877Z", "message": { "role": "ROLE_AGENT", "parts": [ { "text": "Request is completed!" } ] } }, "history": [ { "role": "ROLE_USER", "parts": [ { "text": "" } ] }, { "role": "ROLE_AGENT", "parts": [ { "text": "Processing request..." } ] } ], "artifacts": [ { "artifactId": "", "parts": [ { "mediaType": "text/plain", "text": "" } ] } ] } } }, "severity_number": 9, "severity_text": "INFO" } ``` # AWS Deployments Explore the comprehensive guide to deploying BlueRock instances on Amazon Web Services (AWS). Choose a preferred method to get started: ### [AWS Deployment with CLI](/deployment-guides/aws-deployments/aws-deployment-with-cli) Deploy BlueRock EC2 instances using the AWS CLI. The implementation process launches the EC2 image within associated subnets and establishes storage in an Amazon S3 bucket for signed policy files. ### [AWS Deployment with Terraform](/deployment-guides/aws-deployments/aws-deployment-using-terraform-template) Learn step-by-step how to configure, manage, and deploy BlueRock instances with Terraform on AWS allowing better integration and resource management. ### [AWS Deployment with CloudFormation](/deployment-guides/aws-deployments/aws-deployment-with-cloud-formation-template) With the capabilities of AWS CloudFormation to define and manage BlueRock resources on AWS. Utilize templates for seamless deployment and management, ensuring a structured and organized approach to cloud infrastructure. # AWS Deployment with CLI ### High-Level Architecture Overview This section provides a conceptual overview of how the BlueRock instance is deployed on AWS EC2 and how its core components interact. #### End-to-End Flow Deployment scripts are executed from a user's desktop or client environment where AWS CLI is configured. The script uses AWS APIs to provision the required AWS Resources and deploy the BlueRock instance. #### BlueRock EC2 Architecture Components #### Architecture Diagram
#### **BlueRock EC2 Architecture Components** A typical BlueRock Secure MCP Server EC2 deployment consists of the following AWS Resources/Services:
AWS Resources/ServicesDescription
Virtual Private Cloud (VPC)Provides an isolated networking environment in AWS where all BlueRock deployment resources are created.
Amazon VPC GatewayEnables controlled inbound and outbound internet access for resources deployed inside the VPC.
Amazon EC2 (BlueRock Instance)Runs the BlueRock MCP Server using a hardened BlueRock AMI and hosts all runtime services.
Amazon Elastic Block Store (EBS)Provides persistent block storage attached to the EC2 instance for operating system and application data.
Amazon S3 (BlueRock Config)Stores BlueRock configuration files such as config.toml that are retrieved by the BlueRock control plane during runtime.
AWS Identity and Access Management (IAM) RoleGrants the EC2 instance permission to access required AWS services such as Amazon S3 and Amazon CloudWatch.
Amazon CloudWatch LogsStores runtime logs and security events generated by the BlueRock MCP Server for analysis and auditing.
User / AdministratorManages and monitors the BlueRock deployment through AWS services such as CloudWatch and AWS Systems Manager (SSM).
*** #### Deployment types BlueRock EC2 deployments support multiple deployment modes depending on networking and telemetry requirements:
Deployment ModeDescription
PrivateDeploys a single BlueRock EC2 instance into a private subnet, with outbound access via a NAT Gateway and management access enabled through AWS Systems Manager (SSM).
PublicDeploys a single BlueRock EC2 instance into a public subnet, allowing management access through SSH (if configured) and AWS Systems Manager (SSM).
*** ### Supported AMI Distributions BlueRock Secure MCP Server supports the following Linux distributions. Each distribution has a corresponding AMI with a specific kernel version: | **Name** | **Kernel Version** | **AMI NAME** | | --------------------- | ------------------ | ------------------------------------------- | | **Amazon Linux 2023** | 6.12.89 | bluerock-release-26-23-1-amzlnx2023-6.12.89 | | **Ubuntu 24.04** | 6.12.89 | bluerock-release-26-23-1-ubuntu2404-6.12.89 | {% hint style="info" icon="notes-sticky" %} **Note:** The AMI name includes the **BlueRock release version**, **Linux distribution**, and **Kernel version**, allowing users to identify compatibility directly from the AMI name {% endhint %} *** ### Prerequisites #### AWS Requirements * Active AWS account * [AWS CLI](https://aws.amazon.com/cli/) * [AWS key credentials](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-configure.html) configured in the local environment ### Deployment Workflow Overview 1. **Phase 1: AWS Infrastructure Provisioning (Local Client / AWS CLI)** 1. [Create the IAM Role and Instance Profile](#create-the-iam-role-and-instance-profile) 1. [Create the Trust Policy](#create-the-trust-policy) 2. [Create the Role](#create-the-role) 2. [Create the S3 Bucket](#create-the-s3-bucket) 1. [Attach AWS Managed Policies](#attach-aws-managed-policies) 2. [Create and Attach the Custom Policy with Minimal Permissions](#create-and-attach-the-custom-policy-with-minimal-permissions) 3. [Create and Link the Instance Profile](#create-and-link-the-instance-profile) 3. [Launch the EC2 Instance](#launch-the-ec2-instance) 1. [Check Instance Access](#check-instance-access) 1. [SSH Access](#ssh-access-public-deployment) 2. [SSM Access](#ssm-access-private-deployments) 2. **Phase 2: BlueRock Instance Setup** 1. [Policy Creation and Upload to S3 Bucket](#policy-creation-and-upload-to-s3-bucket) 1. [Create Policy](#create-policy) 2. [Required Policy Artifacts](#required-policy-package-artifacts) 3. [Upload Files to S3](#upload-policy-files-to-s3) 2. [OTEL Configuration](#otel-configuration) 3. [BlueRock Instance Configuration](#bluerock-instance-configuration) 1. [Verify `bluerockd` operation](#verify-bluerockd-operation) 3. **Phase 3: Logs in CloudWatch and Troubleshooting** 1. [View Logs in AWS CloudWatch](#view-logs-in-aws-cloudwatch) 2. [Troubleshooting](#troubleshooting) 1. [Review `bluerockd` logs](#review-bluerockd-logs) 2. [OpenTelemetry Connectivity Verification](#opentelemetry-connectivity-verification) 3. [Verify BlueRock Kernel Sensor Service](#verify-bluerock-kernel-sensor-service) 4. [Verify BlueRock Kernel Sensor Logs](#verify-bluerock-kernel-sensor-logs) 5. [Verify Runtime Artifacts (BlueRock Sensor Socket)](#runtime-artifacts-bluerock-sensor-socket) 6. [Inspect Local OTEL Event Logs](#local-otel-event-logs) 7. [Check `otelcol.service` logs](#opentelemetry-collector-logs) ### Create the IAM Role and Instance Profile Configure an IAM Role for the EC2 instance with least-privilege permissions tailored to each service requirement: * **Amazon S3 Access:**\ Grants permissions to upload and download policy configuration files, public keys, digital signatures, and checksum files to and from the target S3 bucket. * **Amazon CloudWatch Logging:**\ Grants permission to push OTEL log events to CloudWatch Log Streams for central monitoring and visualization. * **AWS Systems Manager (SSM) Management:**\ Enables core agent capabilities for remote management, administration, and patching of the BlueRock VM instance. * **Amazon EC2 Read Access:**\ Grants read-only access to query instance metadata, subnets, and security groups required by the BlueRock VM. #### Create the Trust Policy Create a local file named `ec2-trust-policy.json` : {% code title="ec2-trust-policy.json" lineNumbers="true" %} ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` {% endcode %} #### Create the Role Execute the following command to create the IAM role: ```shellscript $ aws iam create-role \ --role-name \ --assume-role-policy-document file://ec2-trust-policy.json ``` Expected Command Output: ```shellscript { "Role": { "Path": "/", "RoleName": "", "RoleId": "", "Arn": "arn:aws:iam:::role/", "CreateDate": "2026-08-13T20:52:29+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } } } ``` ### Create the S3 Bucket Create a globally unique S3 bucket to store the BlueRock Instance policies: ```shellscript $ aws s3 mb s3:// --region ``` #### Attach AWS Managed Policies Attach the required AWS-managed policies for EC2 read access, CloudWatch telemetry, and Systems Manager (SSM) core agent support: * **`AmazonEC2ReadOnlyAccess`**:\ Grants read-only access to query EC2 infrastructure details, subnets, and security groups. * **`CloudWatchAgentServerPolicy`**:\ Grants permission to collect and push OTEL telemetry logs to Amazon CloudWatch. * **`AmazonSSMManagedInstanceCore`**:\ Enables core agent capabilities for remote instance management and administration via Systems Manager. ```shellscript $ aws iam attach-role-policy \ --role-name \ --policy-arn arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess $ aws iam attach-role-policy \ --role-name \ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy $ aws iam attach-role-policy \ --role-name \ --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore ``` #### **Create and Attach the Custom Policy with Minimal Permissions** Create a local file named `bluerock-installer-policy.json` containing the explicit minimal permissions for S3 policy objects and log stream events: {% code title="bluerock-installer-policy.json" lineNumbers="true" %} ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "logs:PutLogEvents" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": [ "arn:aws:s3:::/bluerock_pub_key.pem", "arn:aws:s3:::/policy.json", "arn:aws:s3:::/policy.json.sha256", "arn:aws:s3:::/policy.json.sig" ] } ] } ``` {% endcode %} Execute the commands to create the custom policy and attach it to the role: ```shellscript $ aws iam create-policy \ --policy-name \ --policy-document file://bluerock-installer-policy.json $ aws iam attach-role-policy \ --role-name \ --policy-arn arn:aws:iam:::policy/ ``` #### Create and Link the Instance Profile Create the instance profile and link the IAM role: ```shellscript $ aws iam create-instance-profile --instance-profile-name $ aws iam add-role-to-instance-profile \ --instance-profile-name \ --role-name ``` Expected Command Output: ```shellscript { "InstanceProfile": { "Path": "/", "InstanceProfileName": "", "InstanceProfileId": "", "Arn": "arn:aws:iam:::instance-profile/", "CreateDate": "2026-08-13T20:53:01+00:00", "Roles": [] } } ``` ### Launch the EC2 Instance Launch the EC2 instance using the target AMI and attach the IAM Instance Profile created previously: ```shellscript $ aws ec2 run-instances \ --image-id \ --instance-type \ --key-name \ --security-group-ids \ --subnet-id \ --iam-instance-profile Name="" \ --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":40,"VolumeType":"gp3"}}]' \ --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=}]' \ --region ``` {% hint style="info" icon="notes-sticky" %} **Note:** * Ensure that the specified `--security-group-ids` and `--subnet-id` belong to the same VPC prior to execution. * To locate the shared AMI ID in the target account, run: ```shellscript $ aws ec2 describe-images --owners self --region --output table ``` * If Subnet or Security Group IDs are already known, skip retrieving infrastructure details; otherwise, run the following CLI commands for your region: * Subnets: ```shellscript $ aws ec2 describe-subnets --region --query 'Subnets[*].[SubnetId, AvailabilityZone]' --output table ``` * Security Groups: ```shellscript $ aws ec2 describe-security-groups --region --query 'SecurityGroups[*].[GroupId, GroupName]' --output table ``` {% endhint %} **Parameter Table:**
ParameterTypeDescription
--image-idRequiredTarget region Amazon Machine Image (AMI) ID (e.g., ami-<00xxx00xx>).
--instance-typeRequiredHardware configuration size for the EC2 instance (e.g., t3.large).
--key-nameRequiredSSH Key Pair identifier created in the target region (e.g., <key-name>)
--security-group-idsRequiredVPC Security Group ID regulating inbound and outbound network access rules (e.g., sg-<00xxx00xx>).
--subnet-idRequiredSpecific Subnet and Availability Zone ID where the instance is deployed (e.g., subnet-<00xxx00xx>).
--iam-instance-profileRequiredIAM Instance Profile name granting S3 and CloudWatch access to the instance (e.g., <InstanceProfileName>).
--block-device-mappingsRequiredStorage volume configurations specifying a 40GB gp3 root volume.
--tag-specificationsRequiredResource identification tags in key-value format (e.g., Name=<EC2Username>).
--regionRequiredTarget AWS Region code where infrastructure is hosted (e.g., <region-code>).
--countOptionalNumber of identical instances to launch simultaneously (Default: 1).
--associate-public-ip-addressOptionalFlag to automatically assign a public IP address.
--user-dataOptionalPath to a bootstrapping script executed automatically upon instance boot.
--ebs-optimizedOptionalFlag enabling dedicated EBS throughput for high performance.
--instance-initiated-shutdown-behaviorOptionalAction taken when OS-level shutdown is initiated (stop or terminate).
#### Check Instance Access #### **SSH Access (Public Deployment)** Check instance access to confirm SSH connectivity for public deployments by running the appropriate command for the selected AMI: ```shellscript Amazon Linux: $ ssh -i /path/to/key.pem ec2-user@ Ubuntu: $ ssh -i /path/to/key.pem ubuntu@ ``` #### **SSM Access (Private Deployments)** For instances deployed in a private subnet without a public IP address, establish an interactive shell session using AWS Systems Manager (SSM) Session Manager. {% hint style="success" %} **Important:** * The AWS Systems Manager Session Manager plugin must be installed on the local machine. * The EC2 instance must have the `AmazonSSMManagedInstanceCore` policy attached via its IAM Instance Profile. {% endhint %} **Connect via AWS CLI** Start a session using the EC2 Instance ID: ```shellscript $ aws ssm start-session \ --target \ --region ``` ### Policy Creation and Upload to S3 Bucket #### Create Policy Policy artifacts must be generated, signed, and uploaded to the target Amazon S3 bucket prior to starting or updating the service daemon. The BlueRock instance uses the TREX tool that resides at `/opt/bluerock/trex` to generate a signed policy blob (`.tar`), extract the signed files, and verify digital signatures during startup. For detailed instructions on generating public keys, configuring `trex.toml`, and building policy templates, refer to the [Policy Builder documentation](/policy-configuration/policy-builder). #### Required Policy Package Artifacts | **File** | **Purpose** | | -------------------- | ------------------------------------------------------------------------------- | | `policy.json` | The core JSON policy file containing the defined enforcement rules. | | `policy.json.sha256` | The cryptographic hash file used to verify JSON integrity. | | `policy.json.sig` | The digital signature file used to authenticate the policy file. | | `dynpol_pubkey.pem` | The public key certificate used by the daemon to validate the policy signature. | #### Upload Policy Files to S3 Copy the policy package artifacts to the configured S3 bucket path: ```shellscript $ aws s3 cp policy.json s3:/// $ aws s3 cp policy.json.sig s3:/// $ aws s3 cp dynpol_pubkey.pem s3:/// ``` {% hint style="info" icon="notes-sticky" %} **Note:** Ensure file names and bucket paths match the target locations specified in the [BlueRock Instance Configuration](#bluerock-instance-configuration) section. The private key used for signing policy files must never be uploaded to S3. {% endhint %} ### OTEL Configuration Configure the OTEL Collector to capture runtime telemetry and log events from `bluerockd` and route them to Amazon CloudWatch Logs for centralized monitoring and auditing. The default configuration file resides at `/opt/bluerock/otel` with file name `otel-config.yaml`, includes standard OTLP HTTP receivers and batch processors. Only the `exporters` section requires modification to establish the target CloudWatch Logs integration. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` Modify the `exporters` block in `otel-config.yaml` to specify the CloudWatch Log Group, Log Stream, and regional API endpoint: {% code title="otel-config.yaml" lineNumbers="true" %} ```yaml exporters: debug: verbosity: detailed awscloudwatchlogs: log_group_name: "" log_stream_name: "" region: "" endpoint: https://logs..amazonaws.com ``` {% endcode %} #### Configuration Parameters Table
ParameterSectionDescription
exporters.debug.verbosityExporter ConfigDetail level of debug output generated by the collector (basic, normal, or detailed).
exporters.awscloudwatchlogs.log_group_nameExporter ConfigTarget Amazon CloudWatch Log Group name where log events are published.
exporters.awscloudwatchlogs.log_stream_nameExporter ConfigSpecific Amazon CloudWatch Log Stream name within the log group.
exporters.awscloudwatchlogs.regionExporter ConfigAWS Region code hosting the CloudWatch Logs endpoint (e.g., <Region>).
exporters.awscloudwatchlogs.endpointExporter ConfigRegional CloudWatch Logs API endpoint URL (e.g., https://logs.<Region>.amazonaws.com).
Enable the OTel service: ```shellscript $ sudo systemctl enable otelcol.service ``` Start the otel service: ```shellscript $ sudo systemctl start otelcol.service ``` Check the status of the OTel service: ```shellscript $ sudo systemctl status otelcol.service ``` Expected output: ```shellscript ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Thu 2026-08-13 17:13:18 UTC; 6 days ago Docs: https://opentelemetry.io/docs/collector/ Main PID: (aws-otel-collec) Tasks: 10 (limit: 18781) Memory: 128.3M (peak: 144.3M) CPU: 7min 8.857s CGroup: /system.slice/otelcol.service └─ /opt/aws/aws-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Aug 19 20:58:52 ip- run-otelcol.sh[]: 2026-08-19T20:58:52.945Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:00:34 ip- run-otelcol.sh[]: 2026-08-19T21:00:34.533Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:00:34 ip- run-otelcol.sh[]: 2026-08-19T21:00:34.559Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:00:34 ip- run-otelcol.sh[]: 2026-08-19T21:00:34.573Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:00:35 ip- run-otelcol.sh[]: 2026-08-19T21:00:35.444Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:02:34 ip- run-otelcol.sh[]: 2026-08-19T21:02:34.535Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> Aug 19 21:04:34 ip- run-otelcol.sh[]: 2026-08-19T21:04:34.580Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {> ``` ### BlueRock Instance Configuration BlueRock instances have a configuration file `bluerockd.toml` to define telemetry and policy settings that reside at `/etc/bluerock/`. {% code title="bluerockd.toml" lineNumbers="true" %} ```toml [runtime] metrics_timer = 1800 state_dir = "/var/lib/bluerockd/" [policy] public_key = "s3:///.pem" poll_period = 300 [policy.source] location = "s3:///" policy = ".json" policy_sig = ".json.sig" [policy.source.transport] auth_method = "default" region = "us-east-1" [policy.engine] augment_events = true [otlp] file = "/var/log/bluerockd/otel-events.log" [otlp.http] url = "http://:4318/" ``` {% endcode %} {% hint style="info" icon="notes-sticky" %} **Note:** The `` placeholder specifies the local private IP address of the EC2 instance. This local address is used because the OTEL Collector service `otelcol.service` runs locally on the BlueRock instance. {% endhint %} | **Parameter** | **Type** | **Description** | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `metrics_timer` | Integer | How often (in seconds) the agent pushes its performance metrics (e.g., `1800` = 30 minutes). | | `state_dir` | Path / String | The local directory path where the agent (`bluerockd`) stores its internal state data. | | `policy.public_key` | S3 Path | The Amazon S3 bucket location of the public key used to validate the policy signature file (`.pem` format). | | `policy.poll_period` | Integer | How often (in seconds) the agent checks the source location for a new policy version (e.g., `300` = 5 minutes). | | `policy.source.location` | S3 Path | The base Amazon S3 bucket path where the policy-related files are hosted. | | `policy.source.policy` | File Name | The specific JSON file name containing the agent's configuration rules. | | `policy.source.policy_sig` | File Name | The digital signature file used to verify that the core policy JSON file hasn't been tampered with. | | `policy.source.transport.auth_method` | String | The authentication strategy used to access files. Setting it to `default` utilizes the EC2 instance's attached IAM Role / Instance Profile. | | `policy.source.transport.region` | String | The Amazon Web Services (AWS) region where the storage resources are located (e.g., `us-east-1`). | | `policy.engine.augment_events` | Boolean | Determines whether the policy engine should enrich or add additional metadata/context to the captured events (`true` or `false`). | | `otlp.file` | Path / String | The local file path where OpenTelemetry log events are written. | | `otlp.http.url` | URL | The local or internal HTTP endpoint (usually an OTLP/HTTP receiver or collector) where telemetry data is forwarded. | After editing `bluerockd.toml`, restart the `bluerockd.service`: ```shellscript $ sudo systemctl restart bluerockd.service ``` #### Verify `bluerockd` operation Verify the operational status and log output of the `bluerockd` service after modifying `/etc/bluerock/bluerockd.toml` and restarting the service. ```shellscript $ sudo systemctl status bluerockd.service ``` Expected output: ```shellscript ● bluerockd.service - BlueRock Daemon Loaded: loaded (/usr/lib/systemd/system/bluerockd.service; enabled; preset: enabled) Drop-In: /usr/lib/systemd/system/bluerockd.service.d └─10-containerd.conf Active: active (running) since Thu 2026-08-20 08:33:53 UTC; 6s ago TriggeredBy: ● bluerockd.socket ● bluerockd-sandbox.socket Docs: https://bluerock.io/ Main PID: (bluerockd) Tasks: 14 (limit: 18781) Memory: 39.0M (peak: 40.2M) CPU: 865ms CGroup: /system.slice/bluerockd.service └─ /opt/bluerock/bin/bluerockd --config=/etc/bluerock/bluerockd.toml --socket=/run/bluerock/sensor.sock --stdout Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.898111427Z INFO bluerockd: system/bluerockd/src/main.rs:186: Listening on socket-activated (/run/bluerock/sensor.sock) Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.899239699Z INFO bluerockd: system/bluerockd/src/main.rs:190: Accepting new connection Handshake { pid: , protocol> Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.89992773Z INFO bluerockd::pcm::connection: system/bluerockd/src/pcm/connection.rs:81: Connection 9318: New connection,> Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.899985321Z INFO bluerockd::pcm::connection: system/bluerockd/src/pcm/connection.rs:164: Connection 9318: Notified mana> Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.899986599Z INFO bluerockd::pcm::mgmt: system/bluerockd/src/pcm/mgmt.rs:294: Management Task: Received Status: 'Handlin> Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.900056787Z INFO bluerockd::pcm::mgmt: system/bluerockd/src/pcm/mgmt.rs:318: Management Task: id=9318 - Current policy > Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.900137021Z INFO bluerockd: system/bluerockd/src/main.rs:219: Sensor 9318: Spawn metadata updater Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.900167295Z INFO bluerockd: system/bluerockd/src/main.rs:221: Sensor 9318: Spawning handler Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.901101875Z INFO bluerockd::pcm::connection: system/bluerockd/src/pcm/connection.rs:421: Connection 9318: Selecting ker> Aug 20 08:33:53 ip- bluerockd[]: 2026-08-20T08:33:53.901450267Z INFO bluerockd::pcm::connection: system/bluerockd/src/pcm/connection.rs:558: Connection 9318: HandshakeConf> ``` #### Check `bluerockd` Journal logs Check `bluerockd` journal logs to confirm that policy files loaded successfully from the target S3 bucket location: ```shellscript $ journalctl -u bluerockd ``` Expected output: * Once the configured policies are loaded: ```shellscript Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.47823964Z INFO bluerockd::pcm::downloaders::s3: system/bluerockd/src/pcm/downloaders/s3.rs:227: Creating S3 downloader with default AWS credential chain for region: Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.50509293Z INFO bluerockd::pcm::configmgr: system/bluerockd/src/pcm/configmgr.rs:184: Downloading public key from S3 URL s3:///.pem Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.505149472Z INFO bluerockd::pcm::downloaders::s3: system/bluerockd/src/pcm/downloaders/s3.rs:242: Downloading object from s3:///.pem Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.622084622Z INFO bluerockd::pcm::downloaders::s3: system/bluerockd/src/pcm/downloaders/s3.rs:260: Successfully downloaded 800 bytes from s3:///.pem Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.622388861Z INFO bluerockd::pcm::configmgr: system/bluerockd/src/pcm/configmgr.rs:218: Successfully downloaded and saved public key from S3 to /var/lib/bluerockd/.pem Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.622761955Z INFO bluerockd::pcm::configmgr: system/bluerockd/src/pcm/configmgr.rs:422: Resolved public key local path: /var/lib/bluerockd/.pem (Source: config file S3 URL s3:///.pem) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.622782861Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:808: Using default hostid: Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.62280346Z INFO bluerockd::pcm::cloud: system/bluerockd/src/pcm/cloud/mod.rs:114: Auto-detecting cloud provider environment... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.6313084Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:52: Testing IMDS (Instance Metadata Service) accessibility... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.640629106Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:66: IMDS Check: Requesting IMDSv2 token from http://169.254.169.254/latest/api/token... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.652360689Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:79: IMDS Check: ✓ Successfully acquired IMDSv2 token (56 chars) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.652400198Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:107: IMDS Check: Testing security credentials endpoint... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.654405361Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:124: IMDS Check: ✓ Found IAM role(s): Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.655109389Z INFO bluerockd::pcm::cloud: system/bluerockd/src/pcm/cloud/mod.rs:134: Detected cloud provider: AWS Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.655136399Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:784: Detected cloud provider: AWS Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.655161213Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:529: Checking for policy in state directory: /var/lib/bluerockd//active-policy.json Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.655184552Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:246: Starting policy validation for: /var/lib/bluerockd//active-policy.json Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.657101271Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:307: Policy hash/version verification passed policy_file=/var/lib/bluerockd//active-policy.json policy_version= policy_hash= Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.657133236Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:319: Excluded cgroups that will be passed as policy addendum: None Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.667703856Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:567: Policy (state directory): /var/lib/bluerockd//active-policy.json Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.668267975Z INFO bluerockd::pcm: system/bluerockd/src/pcm/mod.rs:604: Management task spawned Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.668294831Z INFO bluerockd::pcm::tasks: system/bluerockd/src/pcm/tasks.rs:61: Policy context initialization completed. ``` * IAM and other credential validation in `bluerockd` logs: ```shellscript Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.713101294Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:52: Testing IMDS (Instance Metadata Service) accessibility... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.721588203Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:66: IMDS Check: Requesting IMDSv2 token from http://169.254.169.254/latest/api/token... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.723210594Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:79: IMDS Check: ✓ Successfully acquired IMDSv2 token (56 chars) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.723245025Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:107: IMDS Check: Testing security credentials endpoint... Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724073433Z INFO bluerockd::pcm::aws::imds: system/bluerockd/src/pcm/aws/imds.rs:124: IMDS Check: ✓ Found IAM role(s): Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724862577Z INFO bluerockd::pcm::cloud: system/bluerockd/src/pcm/cloud/mod.rs:39: Early IMDS accessibility test passed: IMDS accessible with IAM role: Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724889609Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:17: DEBUG: Checking AWS-related environment variables: Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724902817Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_ACCESS_KEY_ID = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724911666Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_SECRET_ACCESS_KEY = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724918381Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_SESSION_TOKEN = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.72492495Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_PROFILE = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724932067Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_REGION = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724939111Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_DEFAULT_REGION = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724945911Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_EC2_METADATA_DISABLED = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724952283Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_EC2_METADATA_SERVICE_ENDPOINT = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724959564Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724966144Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_CONTAINER_CREDENTIALS_FULL_URI = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724972681Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_WEB_IDENTITY_TOKEN_FILE = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.724979606Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_ROLE_ARN = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.72498625Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:43: DEBUG: AWS_ROLE_SESSION_NAME = (not set) Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.72499489Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:49: DEBUG: Loading AWS SDK config with default credential provider chain Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.725002394Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:70: DEBUG: Credential source hints: [] Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.728726471Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:76: DEBUG: AWS SDK resolved region: us-east-1 Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.728760434Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:92: DEBUG: Attempting STS GetCallerIdentity to verify credentials Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.762396019Z INFO bluerockd::pcm::aws: system/bluerockd/src/pcm/aws/mod.rs:97: DEBUG: STS GetCallerIdentity succeeded, ARN: arn:aws:sts:::assumed-role// Aug 20 07:53:10 ip-.ec2.internal bluerockd[]: 2026-08-20T07:53:10.762795792Z INFO bluerockd::pcm::cloud: system/bluerockd/src/pcm/cloud/mod.rs:48: Early AWS credentials verified for ARN: arn:aws:sts:::assumed-role// ``` ### View Logs in AWS CloudWatch **Check CloudWatch logs:** 1. Navigate to the **CloudWatch Console**
2. Go to **Log Groups**
3. Find the BlueRock Log Group
3. **Verify:** * Log entries are present * Events originate from the EC2 instance * Timestamps align with instance startup activity
### Troubleshooting Execute the following diagnostic checks on the local Amazon EC2 instance to resolve failed event processing or missing Amazon CloudWatch telemetry data. #### Review `bluerockd` Logs Review the `bluerockd` logs to identify failed OpenTelemetry (OTEL) event publishes:\ Bash ```shellscript journalctl -u bluerockd ``` Expected error log indicating a failed publish: ```shellscript Aug 20 08:10:19 ip-.ec2.internal bluerockd[]: 2026-08-20T08:10:19.197004761Z ERROR opentelemetry_sdk: /opentelemetry_sdk-0.31.0/src/logs/batch_log_processor.rs:537: name="BatchLogProcessor.ExportError" error="Operation failed: reqwest::Error { kind: Request, url: \"http://:4318/v1/logs\", source: hyper_util::client::legacy::Error(Connect, ConnectError(\"tcp connect error\", :4318, Os { code: 113, kind: HostUnreachable, message: \"No route to host\" })) }" ``` #### OpenTelemetry Connectivity Verification If the `bluerockd` logs indicate a connection error to the OpenTelemetry endpoint, verify network reachability to the collector. Execute the following command from the BlueRock Instance: ```shellscript curl -v http://:4318/v1/logs ``` Review the command output to determine the next action: * **Connection established:** \ Investigate the OpenTelemetry collector configuration files to resolve the export failure. * **Connection failed:** \ Verify the OpenTelemetry endpoint IP address configuration within the `/etc/bluerock/bluerockd.toml` file. #### Verify BlueRock Kernel Sensor Service Verify the operational status of the BlueRock Kernel Sensor service to ensure the activation of the underlying driver: ```shellscript sudo systemctl status bluerock-kernel-sensor.service ``` Expected Output: ```shellscript Warning: The unit file, source configuration file or drop-ins of bluerock-kernel-sensor.service changed on disk. Run 'systemctl daemon-reload' to reload units. ● bluerock-kernel-sensor.service - BlueRock Kernel Sensor Loaded: loaded (/usr/lib/systemd/system/bluerock-kernel-sensor.service; enabled; preset: enabled) Active: active (running) since Fri 2026-08-14 13:16:02 UTC; 4 days ago Docs: https://bluerock.io/ Main PID: (kernel-sensor) Tasks: 7 (limit: 18781) Memory: 16.5M (peak: 17.1M) CPU: 258ms CGroup: /system.slice/bluerock-kernel-sensor.service └─ /opt/bluerock/bin/kernel-sensor --socket=/run/bluerock/sensor.sock --directory=/sys/kernel/tracing/brs/ --mode=mmap Aug 14 13:16:03 ip- bluerock-kernel-sensor[]: 2026-08-14T13:16:03.364657821Z INFO ThreadId(03) kernel_sensor: sensors/kernel-sensor/src/main.rs:761: Starting Thread[1] Aug 14 13:16:03 ip- bluerock-kernel-sensor[]: 2026-08-14T13:16:03.365904675Z INFO ThreadId(03) kernel_sensor: sensors/kernel-sensor/src/main.rs:646: Thread1: events "/sys/> Aug 14 13:16:03 ip- bluerock-kernel-sensor[]: 2026-08-14T13:16:03.365962517Z INFO ThreadId(03) kernel_sensor: sensors/kernel-sensor/src/main.rs:647: Thread1: response "/sy> ``` #### Verify BlueRock Kernel Sensor Logs Review the BlueRock Kernel Sensor logs: ```shellscript journalctl -u bluerock-kernel-sensor ``` Expected output: ```shellscript Aug 13 10:28:19 ip- systemd[1]: Starting bluerock-kernel-sensor.service - BlueRock Kernel Sensor... Aug 13 10:28:20 ip- systemd[1]: Started bluerock-kernel-sensor.service - BlueRock Kernel Sensor. Aug 13 10:28:21 ip- bluerock-kernel-sensor[]: 2026-08-13T10:28:21.671836262Z INFO main acoustic::connector: libraries/acoustic/src/connector.rs:33: Using socket path: "/run/> Aug 13 10:28:37 ip- bluerock-kernel-sensor[]: 2026-08-13T10:28:37.496144373Z INFO ThreadId(02) kernel_sensor: sensors/kernel-sensor/src/main.rs:761: Starting Thread[0] Aug 13 10:28:37 ip- bluerock-kernel-sensor[]: 2026-08-13T10:28:37.496873782Z INFO ThreadId(02) kernel_sensor: sensors/kernel-sensor/src/main.rs:646: Thread0: events "/sys/ke> ``` #### Runtime Artifacts (BlueRock Sensor Socket) Confirm the presence of the communication BlueRock Sensor Socket file in the runtime directory: ```shellscript ls -l /run/bluerock/sensor.sock ``` Expected output: ```shellscript srwxrwxrwx 1 root root 0 Aug 13 10:28 /run/bluerock/sensor.sock ``` #### Local OTEL Event Logs List the log directory contents to confirm the generation of local OTEL event and metric logs: ```shellscript sudo ls -l /var/log/bluerockd/ ``` Expected output: ```shellscript total 26660 -rw-r--r-- 1 root root 5325821 Jul 23 05:12 otel-events-otel-logs.log -rw-r--r-- 1 root root 11112231 Jul 23 04:28 otel-events-otel-logs.log.20260623T042835 -rw-r--r-- 1 root root 5105497 Jul 23 05:00 otel-events-otel-logs.log.20260623T050028 -rw-r--r-- 1 root root 133534 Jul 23 05:12 otel-events-otel-metrics.log ``` #### OpenTelemetry Collector Logs Verify the `otelcol` journal logs to confirm collector initialization and the active exportation of log events to Amazon CloudWatch Logs: ```shellscript journalctl -u otelcol ``` Expected output:Plaintext ```shellscript Aug 20 05:55:24 ip-.ec2.internal run-otelcol.sh[]: 2026-08-20T05:55:24.216Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {"resource": {"service.instance.id": "", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "awscloudwatchlogs", "otelcol.component.kind": "exporter", "otelcol.signal": "logs", "NumOfLogEvents": 16, "LogEventsSize": 16.70703125, "Time": 16} Aug 20 05:55:25 ip-.ec2.internal run-otelcol.sh[]: 2026-08-20T05:55:25.219Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {"resource": {"service.instance.id": "", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "awscloudwatchlogs", "otelcol.component.kind": "exporter", "otelcol.signal": "logs", "NumOfLogEvents": 2, "LogEventsSize": 2.099609375, "Time": 19} Aug 20 05:55:26 ip-.ec2.internal run-otelcol.sh[]: 2026-08-20T05:55:26.215Z debug cwlogs@v0.130.0/pusher.go:271 logpusher: publish log events successfully. {"resource": {"service.instance.id": "", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "awscloudwatchlogs", "otelcol.component.kind": "exporter", "otelcol.signal": "logs", "NumOfLogEvents": 2, "LogEventsSize": 1.9677734375, "Time": 13} ``` # AWS Deployment Using Terraform Template ### High-Level Architecture Overview This section provides a conceptual overview of how the BlueRock instance is deployed on AWS EC2 and how its core components interact. #### End-to-End Flow Deployment scripts are executed from a user's desktop or client environment where AWS CLI is configured. The script uses AWS APIs to provision the required AWS Resources and deploy the BlueRock instance. #### BlueRock EC2 Architecture Components #### Architecture Diagram
#### **BlueRock EC2 Architecture Components** A typical BlueRock Secure MCP Server EC2 deployment consists of the following AWS Resources/Services:
AWS Resources/ServicesDescription
Virtual Private Cloud (VPC)Provides an isolated networking environment in AWS where all BlueRock deployment resources are created.
Amazon VPC GatewayEnables controlled inbound and outbound internet access for resources deployed inside the VPC.
Amazon EC2 (BlueRock Node)Runs the BlueRock MCP Server using a hardened BlueRock AMI and hosts all runtime services.
Amazon Elastic Block Store (EBS)Provides persistent block storage attached to the EC2 instance for operating system and application data.
Amazon S3 (BlueRock Config)Stores BlueRock configuration files such as config.toml that are retrieved by the BlueRock control plane during runtime.
AWS Identity and Access Management (IAM) RoleGrants the EC2 instance permission to access required AWS services such as Amazon S3 and Amazon CloudWatch.
Amazon CloudWatcReceives telemetry and monitoring data generated by the BlueRock MCP Server.
Amazon CloudWatch LogsStores runtime logs and security events generated by the BlueRock MCP Server for analysis and auditing.
User / AdministratorManages and monitors the BlueRock deployment through AWS services such as CloudWatch and AWS Systems Manager (SSM).
*** #### Deployment types BlueRock EC2 deployments support multiple deployment modes depending on networking and telemetry requirements:
Deployment ModeDescription
PrivateDeploys a single BlueRock EC2 instance into a private subnet, with outbound access via a NAT Gateway and management access enabled through AWS Systems Manager (SSM).
PublicDeploys a single BlueRock EC2 instance into a public subnet, allowing management access through SSH (if configured) and AWS Systems Manager (SSM).
*** ### Supported AMI Distributions BlueRock Secure MCP Server supports the following Linux distributions. Each distribution has a corresponding AMI with a specific kernel version: | **Name** | **Kernel Version** | **AMI NAME** | | --------------------- | ------------------ | ------------------------------------------- | | **Amazon Linux 2023** | 6.12.89 | bluerock-release-26-23-1-amzlnx2023-6.12.89 | | **Ubuntu 24.04** | 6.12.89 | bluerock-release-26-23-1-ubuntu2404-6.12.89 | Note: The AMI name includes the **BlueRock release version**, **Linux distribution**, and **Kernel version**, allowing users to identify compatibility directly from the AMI name *** ### Prerequisites #### AWS Requirements * Active AWS account * API key credentials configured in the local environment * AWS CLI should be installed, and key credentials should be configured #### Required Packages The BlueRock Deployment Package for EC2 is provided by BlueRock as part of customer onboarding.\ This package includes Terraform infrastructure-as-code (IaC) scripts required to deploy the BlueRock Secure MCP Server on AWS EC2. #### Deployment Method The following tools must be installed and configured in the local environment before running the deployment: * **Terraform**\ Required to execute the BlueRock Terraform deployment scripts. Terraform installation guide:\ * **AWS CLI**\ Required for authentication, resource validation, and post-deployment verification. AWS CLI installation and configuration guide:\ ```shellscript Configuration file location: ~/.aws/credentials File Content: AWS_ACCESS_KEY_ID=[your_access_key] AWS_SECRET_ACCESS_KEY=[your_secret_key] AWS_SESSION_TOKEN=[your_session_token] ``` #### AWS Permissions Required **User permissions:** The user executing the deployment script requires permissions to create the following AWS objects: * VPC, Subnets, Internet Gateway, Route Tables * EC2 instance * Security Group * IAM Profile * S3 bucket {% hint style="info" icon="notes-sticky" %} **Note:** The IAM instance profile required for the BlueRock instance is automatically created by the deployment script. {% endhint %} *** ### Deployment Package Overview #### Download and Extract Package Download the BlueRock deployment package and extract it in your local environment. ```bash terraform.tar.gz $ tar -xzf terraform.tar.gz $ ls -l cloudformation.tar.gz terraform/ terraform.tar.gz ``` *** ### **Directory Structure** #### Public Deployment ```shellscript terraform/ └── ec2/ ├── al2023/ │ └── PublicDeployment/ │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ ├── terraform.tfvars.example │ └── variables.tf └── ubuntu/ └── PublicDeployment/ ├── README.md ├── main.tf ├── outputs.tf ├── terraform.tfvars.example └── variables.tf ``` #### Private/ External OTEL Deployment ```shellscript terraform/ └── ec2/ ├── al2023/ │ └── ExternalOtel/ │ ├── README.md │ ├── main.tf │ ├── outputs.tf │ ├── terraform.tfvars.example │ ├── user_data.sh.tpl │ └── variables.tf └── ubuntu/ └── ExternalOtel/ ├── README.md ├── main.tf ├── outputs.tf ├── terraform.tfvars.example ├── user_data.sh.tpl └── variables.tf ``` *** ### Terraform Deployment #### Configuration Parameters Navigate to the Terraform deployment directory, copy the example variables file, and update the deployment parameters by editing the Terraform variables file: ```shellscript ## Amazon Linux: $ cd terraform/ec2/al2023/PublicDeployment ## Ubuntu: $ cd terraform/ec2/ubuntu/PublicDeployment $ cp terraform.tfvars.example terraform.tfvars $ vi terraform.tfvars ``` ### Parameter Reference The following table details the variables and parameters for the provided Terraform configuration block. | **Parameter** | **Type** | **Description** | | ------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `region` | String | The AWS region where the resources will be provisioned (e.g., `us-east-1`). | | `prefix` | String | A naming prefix applied to all created resources to easily identify them (e.g., `bluerock-ec2`). | | `allow_ip` | String | The CIDR block permitted to access the instance, typically used for restricting inbound SSH or API traffic (e.g., `10.0.0.0/32`). | | `node_instance_type` | String | The AWS EC2 instance size/type to provision for the BlueRock node (e.g., `t3.xlarge`). | | `sample_host_name` | String | The designated hostname for the deployed instance. | | `ssh_key_name` | String | The name of an existing AWS EC2 Key Pair used to authenticate SSH access to the instance. | | `ami_id` | String | The specific Amazon Machine Image (AMI) ID used to launch the instance. | | `existing_vpc_id` | String | The ID of an existing AWS VPC. If left empty (`""`), the Terraform module will create a new VPC. | | `existing_subnet_id` | String | The ID of an existing AWS Subnet. If left empty (`""`), the Terraform module will create a new Subnet. | | `enable_external_otel` | Boolean | Master toggle (`true` or `false`) to enable or disable the external OpenTelemetry (OTel) configuration. | | `existing_policy_bucket_name` | String | *(Optional)* The name of an existing S3 bucket used for storing policies. | | `existing_telemetry_log_group_name` | String | *(Optional)* The name of an existing AWS CloudWatch Log Group for routing telemetry logs. | | `existing_telemetry_log_stream_name` | String | *(Optional)* The name of an existing AWS CloudWatch Log Stream within the designated Log Group. | {% hint style="info" icon="notes-sticky" %} **Note:** * Deployment on existing VPC: Provide both vpc\_id and subnet\_id values * Deployment on new VPC: Leave both values empty (null) {% endhint %} ### Running the Deployment Script Navigate to the Terraform deployment directory, initialize Terraform, review the execution plan, and apply the configuration to provision the BlueRock Secure MCP Server: ```shellscript $ cd terraform/ec2/al2023/PublicDeployment $ terraform init $ terraform plan $ terraform apply ``` **Capture outputs** The deployment will output critical information including: * EC2 instance Public IP * S3 bucket name * CloudWatch log group name ```bash ## Expected Output: s3_bucket_name = "bluerock-ec2-policy-bucket" s3_bucket_url = "https://bluerock-ec2-policy-bucket.s3.us-east-1.amazonaws.com" instance_id = "i-0x0x0x0x0x0x00000" instance_public_ip = "00.000.00.00" instance_private_ip = "00.0.0.00" vpc_id = "vpc-0x0x0x0x0x0x00000" subnet_id = "subnet-0x0x0x0x0x0x00000" log_group_name = "bluerock-ec2-telemetry" log_stream_name = "bluerock-ec2-stream" ``` *** ### Post-Deployment Validation This section verifies that the BlueRock Secure MCP Server has been deployed successfully and is functioning as expected. #### Check Bluerock Instance Check the instance status to confirm that the EC2 instance is running and has a public IP address assigned (for public deployments): 
aws ec2 describe-instances\ --filters "Name=tag:Name,Values=bluerock*"

Output:
{
  "Reservations": [
    {
      "Instances": [
        {
          "InstanceId": "i-09d31837043f8b71d",
          "InstanceType": "t3.xlarge",
          "State": {
            "Code": 16,
            "Name": "running"
          },
          "PublicIpAddress": "3.85.120.175",
          "PrivateIpAddress": "172.31.134.24",
          "Placement": {
            "AvailabilityZone": "us-east-1b"
          },
          "Tags": [
            {
              "Key": "Name",
              "Value": "bluerock-ec2"
            }
          ]
        }
      ]
    }
  ]
}
#### Check Instance Access **SSH Access** Check instance access to confirm SSH connectivity for public deployments by running the appropriate command for the selected AMI: ```shellscript Amazon Linux: $ ssh -i /path/to/key.pem ec2-user@ Ubuntu: $ ssh -i /path/to/key.pem ubuntu@ ``` #### Verify BlueRock Control Plane Service Verify that the BlueRock Control Plane service is running by checking that the `bluerockd.service` service is in the **active (running)** state. ```shellscript $ sudo systemctl status bluerockd.service ● bluerockd.service - BlueRock Daemon Loaded: loaded (/usr/lib/systemd/system/bluerockd.service; enabled; preset: enabled) Drop-In: /usr/lib/systemd/system/bluerockd.service.d └─10-containerd.conf Active: active (running) since Thu 2026-07-02 12:35:22 UTC; 55ms ago Docs: https://bluerock.io/ Main PID: 2955 (bluerockd) Tasks: 8 (limit: 18781) Memory: 3.3M (peak: 3.3M) CPU: 52ms CGroup: /system.slice/bluerockd.service └─2955 /opt/bluerock/bin/bluerockd --config=/etc/bluerock/bluerockd.toml --socket=/run/bluerock/sensor.sock --stdout Jul 02 12:35:22 ip-172-31-29-210 systemd[1]: Started bluerockd.service - BlueRock Daemon. Jul 02 12:35:22 ip-172-31-29-210 bluerockd[2955]: 2026-07-02T12:35:22.612626065Z INFO bluerockd: bluerockd/src/main.rs:54: Config: /etc/bluerock/bluerockd.toml Jul 02 12:35:22 ip-172-31-29-210 bluerockd[2955]: 2026-07-02T12:35:22.613193913Z INFO bluerockd: bluerockd/src/main.rs:95: OTEL event file: /var/log/bluerockd/otel-events.log (from config) ``` `bluerockd.service` works on the configuration of `bluerockd.toml` file that resides at `/etc/bluerock/bluerockd.toml` in the BlueRock VM instance. {% code title="bluerockd.toml" lineNumbers="true" %} ```toml [runtime] metrics_timer = 1800 state_dir = "/var/lib/bluerockd/" [policy] public_key = "s3://${policy_bucket}/bluerock_pub_key.pem" poll_period = 100 [policy.source] location = "s3://${policy_bucket}/" policy = "policy.json" policy_sig = "policy.json.sig" [policy.source.transport] auth_method = "default" region = "${region}" [policy.engine] augment_events = true [otlp] file = "/var/log/bluerockd/otel-events.log" [otlp.http] url = "http://$SERVICE_PRIVATE_IP:4318/" ``` {% endcode %} It is created automatically with Terraform and has the following parameters. | **Parameter** | **Type** | **Description** | | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `runtime.metrics_timer` | Integer | The interval (in seconds) at which metrics are collected or emitted (e.g., `1800`). | | `runtime.state_dir` | String | The directory path where the daemon maintains its internal state files (e.g., `/var/lib/bluerockd/`). | | `policy.public_key` | String | The URI location (e.g., an S3 path) of the public key used to cryptographically verify the policy file's signature. | | `policy.poll_period` | Integer | The frequency (in seconds) at which the system polls the source location for policy updates. | | `policy.source.location` | String | The base URI or storage bucket path where the policy files are hosted. | | `policy.source.policy` | String | The filename of the primary JSON policy document (e.g., `policy.json`). | | `policy.source.policy_sig` | String | The filename of the cryptographic signature corresponding to the policy document (e.g., `policy.json.sig`). | | `policy.source.transport.auth_method` | String | The authentication strategy used to access the policy source (e.g., `default` to use instance IAM roles/profiles). | | `policy.source.transport.region` | String | The cloud provider region where the policy source bucket is located. | | `policy.engine.augment_events` | Boolean | Controls whether evaluated policy events are augmented with additional system context before being logged or forwarded. | | `otlp.file` | String | The absolute file path where local OpenTelemetry (OTel) events and logs are written. | | `otlp.http.url` | String | The HTTP endpoint URL used to export OTel telemetry data to a collector or backend service. | {% hint style="info" %} **Note:**\ To update the `${policy_bucket}` change or update the prefix param `${var.prefix}-policybucket` in `terraform.tfvars` . {% endhint %} ### **Check OTEL Collector** 1. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 2. Edit the `otel-config.yaml` file based on the requirements. 3. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 4. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 5. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/aws/aws-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` #### Verify Telemetry Events in AWS CloudWatch **Check CloudWatch logs:** 1. Navigate to the **CloudWatch Console**
2. Go to **Log Groups**
3. Find the BlueRock Log Group
3. **Verify:** * Log entries are present * Events originate from the EC2 instance * Timestamps align with instance startup activity
Expected logs include runtime events emitted by the BlueRock Secure MCP Server. # AWS Deployment with Cloud Formation Template ### High-Level Architecture Overview This section provides a conceptual overview of how the BlueRock Secure MCP Server is deployed on AWS EC2 and how its core components interact. #### End-to-End Flow Deployment scripts are executed from a user desktop or client environment where AWS CLI is configured. The script uses AWS APIs to provision the required AWS Resources and deploy BlueRock Secure MCP Server. #### BlueRock EC2 Deployment Architecture #### Architecture Diagram
#### **BlueRock EC2 Architecture Components** A typical BlueRock Secure MCP Server EC2 deployment consists of the following AWS Resources/Services:
AWS Resources/ServicesDescription
Virtual Private Cloud (VPC)Provides an isolated networking environment in AWS where all BlueRock deployment resources are created.
Amazon VPC GatewayEnables controlled inbound and outbound internet access for resources deployed inside the VPC.
Amazon EC2 (BlueRock Node)Runs the BlueRock MCP Server using a hardened BlueRock AMI and hosts all runtime services.
Amazon Elastic Block Store (EBS)Provides persistent block storage attached to the EC2 instance for operating system and application data.
Amazon S3 (BlueRock Config)Stores BlueRock configuration files such as bluerockd.toml that are retrieved by the BlueRock control plane during runtime.
AWS Identity and Access Management (IAM) RoleGrants the EC2 instance permission to access required AWS services such as Amazon S3 and Amazon CloudWatch.
Amazon CloudWatchReceives telemetry and monitoring data generated by the BlueRock MCP Server.
Amazon CloudWatch LogsStores runtime logs and security events generated by the BlueRock MCP Server for analysis and auditing.
User / AdministratorManages and monitors the BlueRock deployment through AWS services such as CloudWatch and AWS Systems Manager (SSM).
*** ### Supported AMI Distributions BlueRock Secure MCP Server supports the following Linux distributions. Each distribution has a corresponding AMI with a specific kernel version:
NameKernel VersionAMI Name
NameKernel VersionAMI Name
Amazon Linux 20236.12.89bluerock-release-26-23-1-amzlnx2023-6.12.89
Ubuntu 24.046.12.89bluerock-release-26-23-1-ubuntu2404-6.12.89
Note: The AMI name includes the **BlueRock release version**, **Linux distribution**, and **Kernel version**, allowing users to identify compatibility directly from the AMI name. *** ### Prerequisites #### AWS Requirements * Active AWS account * API key credentials configured in the local environment * AWS CLI should be installed, and key credentials should be configured #### Required Packages The BlueRock Deployment Package for EC2 is provided by BlueRock as part of customer onboarding. This package includes AWS CloudFormation templates required to deploy the BlueRock Secure MCP Server on AWS EC2. **AWS CLI installation and configuration guide:**\ [AWS-CLI-Installation-Config-Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) ```shellscript ## AWS CLI uses credentials stored in the following file: $ ~/.aws/credentials ## If the .aws directory does not exist, create it using: $ mkdir -p ~/.aws ## Create or edit the credentials file: $ ~/.aws/credentials ## Add the following entries: AWS_ACCESS_KEY_ID=[your_access_key] AWS_SECRET_ACCESS_KEY=[your_secret_key] AWS_SESSION_TOKEN=[your_session_token] ``` #### Obtaining AWS Access Keys Access keys can be generated from the AWS Management Console. 1. Navigate to the **AWS Management Console** 2. Open **IAM** 3. Go to **Users** 4. Select your user account 5. Open the **Security credentials** tab 6. Under **Access keys**, choose **Create access key** Copy the **Access Key ID** and **Secret Access Key** into the credentials file shown above. #### **AWS Permissions Required** **User permissions:** The user executing the deployment script requires permissions to create the following AWS resources: * VPC, Subnets, Internet Gateway, Route Tables * EC2 instance * Security Group * IAM Profile * S3 bucket **Note:** The IAM instance profile required for the BlueRock instance is automatically created by the deployment script. *** ### Deployment Package Overview #### Download and Extract Package Download the BlueRock deployment package (bluerock-cloudformation-ec2) and extract it in your local environment. It contains AWS CloudFormation templates required to deploy the BlueRock Secure MCP Server on AWS EC2. ```shellscript Download the package: bluerock_rel25500_deploy_script.tar.gz Extract the package: tar -xzf bluerock_rel25500_deploy_script.tar.gz Verify extraction: ls -l Output: bluerock_rel25500_deploy_script/ ``` **Note:** On macOS, the tar command may display the warning: ```shellscript tar: Ignoring unknown extended header keyword 'LIBARCHIVE.xattr.com.apple.quarantine' ``` This warning is expected and can be safely ignored. \ **Directory Structure** After extracting the CloudFormation deployment package, the directory structure contains AWS CloudFormation templates and parameter files for different EC2 deployment modes. ``` bluerock_rel25500_deploy_script/ └── cloudformation/ └── ec2/ ├── README.md ├── al2023/ │ ├── bluerock-bru-aws-ec2-template.yaml │ └── parameters.json ├── ubuntu2404/ ├── bluerock-bru-aws-ec2-template.yaml └── parameters.json ``` *** ### CloudFormation Deployment #### Configuration Parameters The CloudFormation deployment uses a predefined set of parameters to control networking, instance configuration, and telemetry settings. Parameters can be provided in either of the following ways: * Through a **JSON parameters file** * Directly via the **AWS CloudFormation Console** #### Deployment using AWS Web Console 1. Navigate to the **AWS CloudFormation Console** 2. Click **Create Stack** → With new resources (standard).
3. Upload the CloudFormation template
4. Configure parameters **Parameters List:** ```shellscript AllowIp Public IP address allowed to access the instance via SSH. Example: 101.0.62.104/32 NodeInstanceType Instance type used for BlueRock worker node. Example: t3.xlarge Prefix Prefix used for AWS resource names. SshKeyName Name of an existing EC2 key pair. AmiId AMI ID for the BlueRock Secure MCP Server image. Example: ami-0251e1dd3708aab50 ExistingVpcId (Optional) Existing VPC ID for deployment. ExistingSubnetId (Optional) Existing subnet ID for deployment. ```
4. Configure Stack Options
4. Review and create stack
4. Monitor stack events for completion
*** #### Deployment using AWS CLI **Step 1:** Navigate to the CloudFormation template directory ```shellscript Amazon Linux: cd bluerock-aws-cloudformation-bru-release-26.08.0/ec2/al2023/ Ubuntu: cd bluerock-aws-cloudformation-bru-release-26.08.0/ec2/ubuntu2404/ ``` **Step 2:** Create CloudFormation stack ```shellscript aws cloudformation create-stack \ --stack-name bluerock-deployment \ --template-body file://template.yaml \ --parameters file://parameters.json \ --capabilities CAPABILITY_IAM ``` **Step 3:** Monitor stack status. Wait until the stack status shows **CREATE\_COMPLETE** before proceeding. ```shellscript aws cloudformation describe-stacks --stack-name bluerock-deployment Output: { "Stacks": [ { "StackName": "bluerock-deployment", "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/bluerock-deployment/9c8f1e20-1234-11ef-a2c3-0a1b2c3d4e5f", "StackStatus": "CREATE_COMPLETE", "CreationTime": "2026-02-03T10:42:18.123Z", "Description": "BlueRock Secure MCP Server EC2 Deployment", "Capabilities": [ "CAPABILITY_IAM" ] } ] } ``` *** ### Post-Deployment Validation This section verifies that the BlueRock Secure MCP Server has been deployed successfully and is functioning as expected. #### Check BlueRock Instance Check the instance status to confirm that the EC2 instance is running and has a public IP address assigned (for public deployments): ```shellscript ~ $ aws ec2 describe-instances \ --filters "Name=tag:Name,Values=bluerock*" { "Reservations": [ { "ReservationId": "r-00fc24c1245a2e96c", "OwnerId": "077227809213", "RequesterId": "043320173835", "Groups": [], "Instances": [ { "Architecture": "x86_64", "BlockDeviceMappings": [ { "DeviceName": "/dev/sda1", "Ebs": { "AttachTime": "2026-02-09T07:37:36+00:00", "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-0929b350547dc3802", "EbsCardIndex": 0 } } ], "ClientToken": "2f7fae10-b724-84df-0dcf-c85aee79c683", "EbsOptimized": false, "EnaSupport": true, "Hypervisor": "xen", "IamInstanceProfile": { "Arn": "arn:aws:iam::077227809213:instance-profile/bluerock-external-otel-InstanceProfile", "Id": "AIPARD6ZC3G673AWVVTM6" }, "NetworkInterfaces": [ { "Association": { "IpOwnerId": "amazon", "PublicDnsName": "ec2-18-227-161-122.us-east-2.compute.amazonaws.com", "PublicIp": "18.227.161.122" }, "Attachment": { "AttachTime": "2026-02-09T07:37:35+00:00", "AttachmentId": "eni-attach-09c4ad25e1611d5df", "DeleteOnTermination": true, "DeviceIndex": 0, "Status": "attached", "NetworkCardIndex": 0 }, "Groups": [ { "GroupId": "sg-053ae813feb64d4f4", "GroupName": "bluerock-external-otel-InstanceSecurityGroup-hzuMqu5i2q7W" } ], "MacAddress": "02:bc:a1:63:78:df", "NetworkInterfaceId": "eni-0d8d5fda7c9e7459c", "OwnerId": "077227809213", "PrivateDnsName": "ip-10-0-1-211.us-east-2.compute.internal", "PrivateIpAddress": "10.0.1.211" } ], "State": { "Code": 16, "Name": "running" }, "Tags": [ { "Key": "Name", "Value": "bluerock-external-otel-node" } ] } ] } ] } ``` #### Check Instance Access **Option 1: SSH Access** (Public Deployment Only) Check instance access to confirm SSH connectivity for public deployments by running the appropriate command for the selected AMI: ```shellscript Amazon Linux: ssh -i /path/to/key.pem ec2-user@ Ubuntu: ssh -i /path/to/key.pem ubuntu@ ``` **Option 2: AWS Systems Manager (SSM)** For Private deployment, where SSH is disabled, connect via AWS SSM. 1. Navigate to EC2 Console 2. Select the BlueRock instance 3. Click **Connect → Session Manager**
4. Click **Connect**
Successful connection confirms: * SSM agent is running * IAM instance profile permissions are correct ```shellscript sh-5.2$ whoami ssm-user sh-5.2$ ``` ### OTEL Event Collection 1. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 2. Edit the `otel-config.yaml` file based on the requirements. 3. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 4. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 5. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/aws/aws-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` ### Verify OTEL Events in AWS CloudWatch **Check CloudWatch logs:** 1. Navigate to **CloudWatch Console**
2. Go to **Log Groups**
3. Find the BlueRock Log Group
4. **Verify:** * Log entries are present * Events originate from the EC2 instance * Timestamps align with instance startup activity
Expected logs include runtime events emitted by the BlueRock Secure MCP Server. For additional information on CloudWatch Logs, see:\ [CloudWatchLogs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) # GCP Deployments Explore comprehensive guide to deploy BlueRock instances on Google Cloud Platform (GCP). Choose your preferred method to get started: ### [**GCP Deployment with CLI**](/deployment-guides/gcp-deployments/gcp-deployment-with-cli) Learn how to deploy using the Google Cloud Command Line Interface for quick and efficient management. ### [**GCP Deployment with Terraform**](/deployment-guides/gcp-deployments/gcp-deployment-with-terraform) Discover the power of Infrastructure as Code with Terraform for scalable and repeatable deployments. # GCP Deployment with CLI This guide provides the necessary technical steps to install the Google Cloud CLI, configure your project environment, and deploy BlueRock-hardened instances on Google Cloud Platform (GCP). ### Prerequisites * Google Cloud CLI tools (`gcloud`), for installation, refer to the official [Google Cloud CLI installation](https://docs.cloud.google.com/sdk/docs/install-sdk) guide. * BlueRock images: BlueRock provides pre-packaged images for the BlueRock Ubuntu 2404 Linux Distribution; contact [BlueRock support](https://www.bluerock.io/contact) for the images.
OSKernel VersionGCP Image NameDescription
Ubuntu 24.046.12.89bluerock-release-26-23-1-ubuntu2404-6-12-89-2703260707Provides full policy configuration control. Allow switching policy action from observe to enforce mode.
### Procedure To deploy the BlueRock-hardened instances on GCP with CLI following is the procedure: 1. [Instance Deployment](#instance-deployment) 2. [Create Storage Bucket](#create-a-storage-bucket) 3. [Instance Configuration](#bluerock-instance-configuration) 4. [Updating Configuration Source](#updating-configuration-source) 5. [OTEL Event Collection](#otel-event-collection) 6. [View Logs in GCP](#view-logs-in-gcp) ### Instance Deployment Deploy the instance to provision the virtual hardware and Identity (Service Account) required for BlueRock. This command initializes a pre-configured environment with the security protocols needed to securely pull your configuration from GCP storage buckets. ```shell gcloud compute instances create \ --zone us-central1-a \ --machine-type n1-standard-2 \ --image bluerock-release-26-08-0-ubuntu2404-6.12.89 \ --image-project \ --boot-disk-size \ --boot-disk-type \ --tags ```
Parameter (Flag)DescriptionExample Value
--zoneDefines the specific physical data center location where the VM resides.us-central1-a
--machine-typeSpecifies the hardware configuration (CPU and RAM). n1-standard-2
--imageThe image name or OS template to install on the boot disk.bluerock-release-26-08-0-ubuntu2404-6.12.89
--image-projectThe Project ID where the specific image is stored (crucial for custom images in other projects).project-1234
--scopesGrants the VM permissions to interact with other GCP services (like Cloud Storage or Logging).cloud-platform
--boot-disk-sizeSets the total storage capacity of the primary (OS) disk.20GB
--boot-disk-typeDefines the performance tier of the disk (Standard, Balanced, or SSD).pd-balanced
--tagsMetadata labels for the instance.bluerock-instance
To validate the instance status: ```sh $ gcloud compute instances describe --zone=us-central1-a --format="value(status)" ``` To connect with the instance using **SSH:** ```shell $ gcloud compute ssh --zone= ``` > **Note**: > > SSH may give some warnings and prompts to generate an SSH key for the first time. While generating SSH key leave the passphrase as empty by pressing Enter. It will automatically create the key and add the key permanently to the host. ### Create a Storage Bucket Ensure to create a GCP Storage Bucket to save the Configuration files and Policy files as the BlueRock Instance picks these files from a separate bucket using `config.source` file that contains this Bucket's URL/URI. To create a bucket run the following command: {% code overflow="wrap" %} ```shell $ gcloud storage buckets create gs:// --location= ``` {% endcode %} Bucket URL example: `gs://bluerock-bucket/` Refer to the [About Cloud Storage buckets](https://docs.cloud.google.com/storage/docs/buckets) guide to learn more about storage buckets in GCP. ### BlueRock Instance Configuration BlueRock instances have a configuration file `bluerockd.toml` to define telemetry and policy settings that resides at `/etc/bluerock/`. {% code title="bluerockd.toml" overflow="wrap" lineNumbers="true" %} ```toml [runtime] metrics_timer = 1800 state_dir = "/var/lib/bluerockd/" [policy] public_key = "gs:///.pem" poll_period = 300 [policy.source] location = "gs:///" policy = ".json" policy_sig = ".json.sig" [policy.source.transport] auth_method = "default" region = "us-central1" [policy.engine] augment_events = true [otlp] file = "/var/log/bluerockd/otel-events.log" [otlp.http] url = "http://:4318/" ``` {% endcode %}
ParameterTypeDescription
metrics_timerIntegerHow often (in seconds) the agent pushes its performance metrics (e.g., 1800 = 30 minutes).
state_dirPath / StringThe local directory path where the agent (bluerockd) stores its internal state data.
policy.public_keyGCS PathThe Cloud Storage bucket location of the public key used to validate the policy signature file (.pem format).
policy.poll_periodIntegerHow often (in seconds) the agent checks the source location for a new policy version (e.g., 300 = 5 minutes).
policy.source.locationGCS PathThe base Google Cloud Storage bucket path where the policy-related files are hosted.
policy.source.policyFile NameThe specific JSON file name containing the agent's configuration rules.
policy.source.policy_sigFile NameThe digital signature file used to verify that the core policy JSON file hasn't been tampered with.
policy.source.transport.auth_methodStringThe authentication strategy used to access files. Setting it to default utilizes the VM's attached Application Default Credentials (ADC).
policy.source.transport.regionStringThe Google Cloud Platform (GCP) region where the storage resources are located (e.g., us-central1).
policy.engine.augment_eventsBooleanDetermines whether the policy engine should enrich or add additional metadata/context to the captured events (true or false).
otlp.filePath / StringThe local file path where OpenTelemetry log events are written.
otlp.http.urlURLThe local or internal HTTP endpoint (usually an OTLP/HTTP receiver or collector) where telemetry data is forwarded.
After editing the `bluerockd.toml` restart the `bluerockd.service` . ```shellscript $ sudo systemctl restart bluerockd.service ``` ### OTEL Event Collection 1. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 2. Edit the `otel-config.yaml` file based on the requirements. 3. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 4. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 5. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/gcp/gcp-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` ### View Logs in GCP To view logs in GCP: 1. Log in to your GCP account in a browser, navigate to **Compute Engine** > **VM Instances**. 2. Select the required instance. 3. Select **Logging**.
# GCP Deployment with Terraform This guide describes how the BlueRock Secure MCP Server is deployed on Google Compute Engine (GCE) using Terraform. Terraform scripts are executed from a local machine or CI/CD environment with the Google Cloud SDK (gcloud) initialized. The scripts use the Google Cloud APIs to provision the necessary Compute Engine, Networking, and Storage resources. ### Prerequisites * Google Cloud CLI tools (`gcloud`), for installation refer to the official [Google Cloud CLI installation](https://docs.cloud.google.com/sdk/docs/install-sdk) guide. * Terraform: Version `1.0` or higher installed; for installation, refer to the official [HashiCorp Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) guide. * BlueRock images: BlueRock provides pre-packaged images of BlueRock Ubuntu 2404 Linux Distribution; contact [BlueRock support](https://www.bluerock.io/contact) for the images.
OSKernel VersionGCP Image Name
Ubuntu 24.046.12.89bluerock-release-26-23-1-ubuntu2404-6-12-89-2703260707
#### BlueRock GCP Architecture Components A typical deployment on GCP consists of the following resources:
GCP Resource/ServiceDescription
VPC NetworkProvides an isolated virtual network environment in GCP.
Cloud NAT / RouterEnables outbound internet access for private instances without a Public IP.
Compute Engine (GCE)Runs the BlueRock MCP Server using a hardened Ubuntu image.
Persistent DiskProvides persistent block storage attached to the GCE instance.
Cloud Storage (GCS)Stores configuration files and certificates for the BlueRock node.
IAM Service AccountGrants the GCE instance minimal permissions for Logging and Storage.
Cloud LoggingCollects and monitors system and application logs from the node.
### Deployment Types BlueRock GCP deployments support two primary modes based on networking requirements: * **Public Deployment**: The instance is assigned a Public IP and is accessible via SSH restricted by a specific CIDR range. * **Private Deployment:** The instance has no public IP. Access is facilitated through Identity-Aware Proxy (IAP), and outbound connectivity is provided via Cloud NAT. ### Deployment Package Overview #### Download and Extract Package Download and extract the BlueRock deployment `bluerock_gcp_deployments_scripts.zip` package in which a sub-package `bluerock-gcp-terraform-26-08.tar.gz` refer to the and extract it on your local environment. ```bash $ tar -xzf terraform.tar.gz $ ls terraform/ terraform.tar.gz ``` ### Directory Structure The GCP Terraform scripts follow a hierarchical structure: ```zsh gcp/compute/terraform/ ├── ubuntu/ │ ├── PublicDeployment/ │ ├── main.tf │ ├── outputs.tf │ ├── terraform.tfvars │ ├── terraform.tfvars.example │ ├── user_data.sh.tpl │ └── variables.tf │ └── PrivateDeployment/ │ ├── main.tf │ ├── outputs.tf │ ├── terraform.tfvars │ ├── terraform.tfvars.example │ ├── user_data.sh.tpl │ └── variables.tf ``` ### Parameter Reference Key variables defined in `variables.tf` that must be configured in your `terraform.tfvars`: | **Parameter** | **Description** | **Required** | **Example** | | -------------- | ------------------------------------- | ------------ | -------------------------------------- | | `project_id` | The unique ID of your GCP project | Yes | `project-1234` | | `region` | GCP region for resource deployment | Yes | `us-central1` | | `boot_image` | The name of the BlueRock Ubuntu image | Yes | `bluerock-release-26-23--0-ubuntu2404` | | `machine_type` | GCE instance type | Yes | `e2-standard-2` | | `allow_ip` | User's or Admin's desktop IP Address | Yes | `xx.xx.xx.xx/32` | ### `terraform.tfvars` Configuration By default, the package has `terraform.tfvars.example` file to configure parameters based on requirements and rename it to `terraform.tfvars` for quick onboarding. ### `terraform.tfvars` Parameter Reference The following parameters are defined in the `terraform.tfvars` file. You must update these values to match your GCP project environment before running the deployment scripts.
ParameterDescriptionRequiredExample / Default Value
project_idThe unique GCP Project ID where resources will be deployed.Yesyour-project-id
regionThe GCP region for the deployment (e.g., us-central1).Yesus-central1
zoneThe specific availability zone within the region.Yesus-central1-a
prefixA string prefix used for naming all generated GCP resources.Nobluerock
allow_ipCIDR range allowed for SSH access to the BlueRock node.Yesxx.xx.xx.xx/20 (Use some private network of xx.xx.xx.xx/20)
machine_typeThe GCE machine type (vCPU/RAM) for the instance.Yese2-standard-4
boot_imageThe name of the pre-baked BlueRock Ubuntu OS image.Yesbluerock-release-26-23--0-ubuntu2404
existing_networkExisting VPC Network name. Leave empty to create a new one.Optional""
existing_subnetworkExisting Subnetwork name. Leave empty to create a new one.Optional""
enable_external_otelEnables the OpenTelemetry collector for external telemetry.Notrue
existing_bucket_nameExisting GCS bucket name to store configuration/logs.Optional""
### Configuration Steps for `terraform.tfvars` To prepare your environment for deployment, follow these steps to initialize your variables: 1. Navigate to the appropriate deployment directory. for example: `gcp/compute/terraform/ubuntu/PublicDeployment/`
2. Copy the example variables file to a live configuration file: ```shell cp terraform.tfvars.example terraform.tfvars ``` 3. Edit the `terraform.tfvars` file and provide your specific `project_id` and `boot_image`. > **Note**: > > If you are deploying into an existing network, ensure both `existing_network` and `existing_subnetwork` are provided; otherwise, Terraform will attempt to create a new VPC and Subnet. ### Terrform Running the Deployment 1. Navigate to the desired deployment directory (e.g., `PublicDeployment`). 2. Initialize: ```yaml $ terraform init ``` 3. Plan: ```yaml $ terraform plan ``` 4. Apply: ```yaml $ terraform apply ``` ### Post-Deployment Validation #### Check BlueRock Instance Verify the VM status and retrieve the IP via the gcloud CLI: ```shell $ gcloud compute instances list --filter="name~'bluerock*'" ``` #### Verify Services SSH into the instance and check the BlueRock control plane status: ```shell $ sudo systemctl restart bluerockd.service $ sudo systemctl status bluerockd.service ``` ### OTEL Event Collection 1. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 2. Edit the `otel-config.yaml` file based on the requirements. 3. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 4. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 5. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/aws/aws-otel-collector/bin/aws-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` ### View Logs in GCP To view logs In GCP: 1. Log in to your GCP account in a browser navigate to **Compute Engine** > **VM Instances**. 2. Select the required instance. 3. Select **Logging**.
# Azure Deployments Explore the comprehensive guide to deploy BlueRock instances on Microsoft Azure. Choose the preferred method to get started: ### [Azure Deployment with CLI](/deployment-guides/azure-deployments/azure-deployment-with-cli) Learn how to deploy using the Azure Command-Line Interface (CLI) for quick and efficient management. ### [Azure Deployment with Terraform ](/deployment-guides/azure-deployments/azure-deployment-with-terraform) Discover the power of Infrastructure as Code with Terraform for scalable and repeatable deployments. # Azure Deployment with CLI This guide provides the necessary technical steps to install the Microsoft Azure CLI, configure your project environment, and deploy BlueRock-hardened instances on Microsoft Azure. ### Prerequisites * Microsoft Azure CLI tools (`az`), for installation, refer to the official [Microsoft Azure CLI installation guide](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest). * BlueRock images: BlueRock provides pre-packaged images of BlueRock Ubuntu 2404 Linux Distribution. Contact [BlueRock support](https://www.bluerock.io/contact) for the images. | OS | Kernel Version | Image Name | Description | | ------------ | -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Ubuntu 24.04 | 6.12.89 | bluerock-release-26-23-1-ubuntu2404-6-12-89-20260724125938 | Provides full policy configuration control. Allow switching policy action from observe to enforce mode. | ### Procedure To deploy the BlueRock-hardened instances on Microsoft Azure with the CLI, the following is the procedure: 1. [Instance Deployment](#instance-deployment) 2. [Create Storage Container](#create-a-storage-container) 3. [Instance Configuration](#bluerock-instance-configuration) 4. [Updating Configuration Source](#updating-configuration-source) 5. [OTEL Event Collection](#otel-event-collection-setup) 6. [View Logs in Azure](#view-logs-in-azure) 7. [Configuring Remote Project Workspace in Claude Desktop IDE](#configuring-remote-project-workspace-in-claude-desktop-ide) ### Instance Deployment To deploy a BlueRock VM in a Customer (Target) Azure Account using the Golden Image hosted in the BlueRock Production Account, cross-tenant authentication must be established. A Service Principal authorized in both the source and target tenants is required to facilitate this deployment. Execute the following Azure CLI script to authenticate the Service Principal across both tenants, generate the User Assigned Managed Identity, and provision the virtual machine. Modify the variables at the top of the script to match the target environment details: {% code overflow="wrap" %} ```shellscript # Define environment variables $ tenant1="" $ tenant2="" $ appid="" $ secret="" $ image_id="" $ rg_name="" $ uami_name="" $ location="" $ ssh_pubkey_path="" # Authenticate against the BlueRock Production tenant $ az login --service-principal -u "${appid}" -p "${secret}" --tenant "${tenant1}" $ az account get-access-token # Authenticate against the Customer target tenant $ az login --service-principal -u "${appid}" -p "${secret}" --tenant "${tenant2}" $ az account get-access-token # Create Managed Identity $ az identity create --resource-group "${rg_name}" --name "${uami_name}" --location "${location}" $ uami_id=$(az identity show --resource-group "${rg_name}" --name "${uami_name}" --query id -o tsv) # Provision the BlueRock VM in the target environment $ az vm create \ --resource-group "${rg_name}" \ --name bluerock-ubuntu-vm \ --image "${image_id}" \ --admin-username ubuntu \ --ssh-key-values @"${ssh_pubkey_path}" \ --size Standard_D2s_v3 \ --assign-identity "${uami_id}" ``` {% endcode %} `az vm create` parameters table:
ParameterDescriptionValue in Your Command
--resource-groupThe logical container in Azure where the VM and its associated resources (disk, network, etc.) will be stored.<resource-group-name>
--nameThe unique name assigned to your virtual machine within the resource group.bluerock-ubuntu-vm
--image

The Operating System image to install. In this case, you're using a variable ($image_id) which likely points to the BlueRock Node AMI.

$image_id
--admin-usernameThe name of the primary administrator account created on the VM.ubuntu
--ssh-key-valuesThe path to your SSH public key for secure, passwordless authentication. The @ symbol tells the CLI to read the content of the file at that path.@<path-to-ssh-pubkey>
--sizeThe hardware profile (SKU) of the VM. Standard_D2s_v3 provides a balanced 2 vCPUs and 8 GiB of memory.Standard_D2s_v3
--locationThe Azure region (datacenter) where the VM will be physically hosted.eastus
--assign-identityAssociates a Managed Identity (such as a User-Assigned Managed Identity) with the virtual machine to allow secure, credential-free access to other Azure resources.$uami_id
The required variable values are sourced from a combination of the BlueRock administrative team and the target Customer's Azure environment. Below is a breakdown of where each specific value is retrieved:
VariableDescription & Source
tenant1BlueRock Production Tenant ID: Provided directly by BlueRock support.
tenant2Customer Tenant ID: Retrieved from the Customer's Azure environment. In the Azure Portal, navigate to Microsoft Entra ID > Overview. The value is listed as the Tenant ID.
appidService Principal App ID: Provided by BlueRock support. This is the Application (client) ID of the Service Principal explicitly authorized to access the shared Golden Image.
secretService Principal Secret: Provided securely by BlueRock support. This acts as the authentication password for the Service Principal.
image_idGolden Image Resource ID: Provided by BlueRock support. This is the full Azure Resource Manager (ARM) path to the specific BlueRock Ubuntu image (e.g., /subscriptions/.../resourceGroups/.../providers/Microsoft.Compute/images/...).
rg_nameCustomer Resource Group Name: The existing resource group in the Customer's Azure environment where the VM and Managed Identity will be provisioned.
uami_nameManaged Identity Name: The desired name for the User Assigned Managed Identity (UAMI) created during the deployment.
locationAzure Region: The specific Azure data center location where the resources will be deployed (e.g., eastus, westeurope).
ssh_pubkey_pathSSH Public Key Path: The local file path to the SSH public key used for authenticating into the deployed VM (e.g., ~/.ssh/id_ed25519.pub).
To validate the instance status: ```shellscript $ az vm show --resource-group --name --show-details --query "powerState" --output tsv ``` To connect with instance using SSH: ```shellscript $ ssh -i ubuntu@ ``` {% hint style="info" icon="notes-sticky" %} **Note:**\ SSH may give some warnings and prompts to generate an SSH key for the first time. While generating an SSH key leave the passphrase as empty by pressing Enter. It will automatically create the key and add the key permanently to the host. {% endhint %} ### Create a Storage Container Ensure to create an Azure Storage Container to save the Configuration file and Policy files as the BlueRock Instance picks these files from a separate container using config.source file that contains this Blob's URL/URI. Create Storage Account: ```shellscript $ az storage account create \ --name \ --resource-group \ --location eastus \ --sku Standard_LRS ``` Create Storage Container: ```shellscript $ az storage container create \ --name \ --account-name \ --auth-mode login ``` #### Identify the Managed Identity Authentication for a BlueRock instance without managed keys requires a Managed Identity, either System-assigned or User-defined. The following command retrieves the Principal ID (Object ID) of the managed identity used while creating the VM instance. Get the Object ID (Principal ID): ```shellscript $ az identity show \ --resource-group "my_resource_group" \ --name "managed_identity_name" \ --query principalId -o tsv ``` #### Authorize the BlueRock Instance (RBAC) Granting the **Storage Blob Data Contributor** role to the identified **Object ID** ensures the instance possesses authority to download policy and configuration artifacts during the startup verification process. UC performs policy signature verification during startup before loading the configuration. Create the Role Assignment: ```shellscript $ az role assignment create \ --assignee-object-id "object_id_from_previous_step" \ --assignee-principal-type ServicePrincipal \ --role "Storage Blob Data Contributor" \ --scope "/subscriptions//resourceGroups//providers/Microsoft.Storage/storageAccounts/" ``` ### BlueRock Instance Configuration BlueRock instances have a configuration file `bluerockd.toml` to define telemetry and policy settings that resides at `/etc/bluerock/`. {% code title="bluerockd.toml" overflow="wrap" lineNumbers="true" %} ```toml [runtime] metrics_timer = 1800 state_dir = "/var/lib/bluerockd/" [policy] public_key = "az://{{STORAGE_ACCOUNT}}/{{BLOB_CONTAINER}}/{{PUBKEY_FILE}}" poll_period = 300 [policy.source] location = "az://{{STORAGE_ACCOUNT}}/{{BLOB_CONTAINER}}/" policy = "policy.json" policy_sig = "policy.json.sig" [policy.source.transport] auth_method = "managed_identity" [otlp] file = "/var/log/bluerockd/otel-events.log" [otlp.http] url = "http://:4318/" ``` {% endcode %}
ParameterTypeDescription
metrics_timerIntegerHow often (in seconds) the agent pushes its performance metrics (e.g., 1800 = 30 minutes).
state_dirPath / StringThe local directory path where the agent (bluerockd) stores its internal state data.
policy.public_keyAzure Blob PathThe Azure Blob Storage URL path to the public key used to validate the policy signature file (az:// protocol).
policy.poll_periodIntegerHow often (in seconds) the agent checks Azure Blob Storage for a new policy version (e.g., 300 = 5 minutes).
policy.source.locationAzure Blob PathThe base Azure Blob Storage container path where the policy-related files are stored.
policy.source.policyFile NameThe specific JSON file name containing the configuration rules.
policy.source.policy_sigFile NameThe digital signature file used to verify that the policy.json hasn't been tampered with.
policy.source.transport.auth_methodStringAuthentication type. Setting it to managed_identity uses the Azure Managed Identity assigned to the host machine/resource.
otlp.filePath / StringThe local file path where OpenTelemetry log events are written.
otlp.http.urlURLThe local or internal HTTP endpoint (usually an OTLP/HTTP receiver or collector) where telemetry data is forwarded.
{% hint style="info" icon="notes-sticky" %} **Note:** BlueRock Secure MCP Server enforces runtime security controls through configurable MCP Protection Policies. Refer to the [Policy Configuration guide ](/policy-configuration/policy-life-cycle#policy-source-configuration)to learn more about these policies. {% endhint %} After editing the `bluerockd.toml` restart the `bluerockd.service` . ```shellscript $ sudo systemctl restart bluerockd.service ``` #### BlueRock Custom Policy Configuration The Full Edition facilitates custom policy enforcement via the TREX tool. This workflow includes environment activation, template generation, cryptographic signing, and artifact upload. 1. Navigate to the TREX directory ```shellscript $ cd /opt/bluerock/trex ``` 2. Create signing key or certificate ```shellscript openssl req -x509 -newkey rsa:4096 -keyout dynpol_key.pem -out dynpol_cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname" ``` 3. Extract pub key from certificate ```shellscript $ openssl x509 -pubkey -noout -in dynpol_cert.pem > dynpol_pubkey.pem ``` 4. Create the `trex.toml` 
[incoming]
   sig_required = false
   sig_hash = "sha256"
   public_key_pem = "dynpol_cert.pem"
   [outgoing]
   sig_required = true 
   sig_hash = "sha256"
   private_key_pem = "dynpol_key.pem"
   private_key_passphrase = ""
5. Activate TREX Environment ```shellscript $ source /opt/bluerock/trex/py312/bin/activate ``` 6. Generate Policy Template ```shellscript $ cp bru_policy.json.template bru_policy.json ``` Manual editing of the JSON file allows defining specific rules, such as enabling or disabling MCP remediation. 7. Generate Signed Policy Blob\ The TREX tool processes the JSON file to generate a signed policy package in `.tar` format: ```shellscript $ python trex.py bru_policy.json ``` 8. Extract Policy Artifacts\ Extraction of the signed blob archive yields the specific files necessary for UC verification: ```shellscript $ tar xvf bru_policy.tar ``` 9. Set environment variables ```shellscript $ export AZCOPY_AUTO_LOGIN_TYPE=MSI $ export AZCOPY_MSI_CLIENT_ID= ``` 10. Upload BlueRock configuration 
$ azcopy copy policy.json https://<url>.blob.core.windows.net/pol/policy.json
    $ azcopy copy policy.json.sig https://<url>.blob.core.windows.net/pol/policy.json.sig
{% hint style="info" icon="notes-sticky" %} **Note:** Upload only the public key for the digital signature so that the signed policy blob (`policy.json`) can be verified by the system using that key. {% endhint %} *** ### OTEL Event Collection Setup To forward OpenTelemetry (OTEL) events and agent telemetry, an Azure Log Analytics Workspace and an Application Insights component must be created and linked. 1. Create Azure Monitoring Resources\ Use the Azure CLI to provision the workspace, create the Application Insights component, and retrieve the required connection string: 
# Create the Log Analytics Workspace with a 30-day retention policy
   $ az monitor log-analytics workspace create \
     --resource-group <rg-name> \
     --workspace-name <workspace-name> \
     --retention-time 30

   # Create the workspace-based Application Insights component
   $ az monitor app-insights component create \
     --app <app-name> \
     --location <region-name> \
     --resource-group <rg-name> \
     --workspace <workspace-resource-id>

   # Retrieve the connection string required for the OTEL collector
   $ az monitor app-insights component show \
     --app <app-name> \
     --resource-group <rg-name> \
     --query connectionString -o tsv
2. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 3. Edit the `otel-config.yaml` file based on the requirements. 4. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 5. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 6. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/azure/aws-otel-collector/bin/azure-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` ### View Logs in Azure Events generated by the BlueRock instance are forwarded to the **Azure Log Analytics Workspace** and can be queried using Kusto Query Language (KQL). Navigate to **Azure Log Analytics Workspace** > select an instance name > **Logs**. In the logs workspace change the **Simple mode** to **KQL mode** run the required query to view application traces.
Following is a sample KQL query: ```shellscript // Retrieve the 50 most recent application traces from the last 10 minutes AppTraces | where TimeGenerated > ago(10m) | project TimeGenerated, Message, SeverityLevel, Properties | order by TimeGenerated desc | take 50 ``` ### Configuring Remote Project Workspace in Claude Desktop IDE To allow AI-assisted development while maintaining BlueRock's telemetry tracking, a dedicated user session must be established for the Claude Desktop IDE. 1. Create the User Account and Configure SSH:\ Connect to the BlueRock Azure VM and execute the following commands in order to create a dedicated user and configure key-based SSH authentication: 1. Create the dedicated account First, create the new user account intended for the Claude Desktop IDE: ```shellscript $ sudo adduser claude_code_user ``` 2. Switch to the new user profile Change your current session to operate as the newly created user: ```shellscript $ sudo su - claude_code_user ``` 3. Generate an SSH keypair Run the `ssh-keygen` command. This will automatically create the `.ssh` directory with the correct permissions. ```shellscript $ ssh-keygen -t ed25519 -C "your_email@example.com" ```

Note:

When prompted, press Enter to accept the default file location, and press Enter again to leave the passphrase empty

4. Authorize the public key Finally, append the designated public key to the `authorized_keys` file to grant inbound access, and lock down the file's permissions: ```shellscript $ echo "" >> ~/.ssh/authorized_keys $ chmod 600 ~/.ssh/authorized_keys ``` 2. Configure the Claude Desktop IDE:\ In the Claude Desktop IDE interface, click the environment selector menu (typically labeled **Local** in the bottom corner) and select **+ Add SSH host...** from the dropdown list. \ ![](/files/Ji8P3qTQy8EtJcLmPvQC)\ In the Add SSH connection dialog box, populate the fields with the following parameters: 1. SSH Connection Name: `` 2. SSH Host: `claude_code_user@` 3. SSH Port: `22` (default) 4. Identity file: `` \ ![](/files/ZuUOW39o6da3pCsvnqTD) 3. Initialize the Remote Workspace: 1. Upon successful SSH connection to the remote VM, select the project folder. Either the default home directory (`/home/claude_code_user`) or a newly created subfolder (e.g., `project`) can be used. 2. The Claude code session initializes in the background on the remote VM. Code generation occurs directly within the remote workspace based on instructions provided in the IDE chat interface. 4. Telemetry and Event Tracking:\ The BlueRock agent actively monitors this remote workspace and generates OpenTelemetry (OTEL) events for all Claude code actions, including file operations and forked/executed processes. These events are automatically forwarded to the configured Azure Log Analytics workspace for security monitoring. {% hint style="info" icon="notes-sticky" %} **Note:** W*hen prompted, press Enter to accept the default file location, and press Enter again to leave the passphrase empty* {% endhint %} # Azure Deployment with Terraform This guide describes how to deploy the BlueRock Secure MCP Server on Microsoft Azure using Terraform. Terraform scripts are executed from a local machine or CI/CD environment with the Microsoft Azure CLI (`az`) initialized. The scripts utilize the Azure Resource Manager APIs to provision the necessary Compute, Networking, Storage, and Monitor resources. *** ### Prerequisites * Microsoft Azure CLI tools (`az`), for installation refer to the official [Microsoft Azure CLI installation guide](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest). * [Terraform](https://developer.hashicorp.com/terraform/install): Version 1.0 or higher installed. * BlueRock images: BlueRock provides pre-packaged images of BlueRock Ubuntu 2404 Linux Distribution. Contact [BlueRock Support](https://www.bluerock.io/contact) for the images. | OS | Kernel Version | Image Name | Description | | ------------ | -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Ubuntu 24.04 | 6.12.89 | bluerock-release-26-23-1-ubuntu2404-6-12-89-20260724125938 | Provides full policy configuration control. Allow switching policy action from observe to enforce mode. | #### Prerequisite Steps Execute the following steps prior to initiating a Terraform deployment to provision the BlueRock "Golden Image" within the customer's Azure Compute Gallery. 1. **Set Environment Variables**:\ Update the variables below with target environment details and execute the block in the terminal. Refer to the provided table for parameter definitions: 
CUSTOMER_SUBSCRIPTION_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   CUSTOMER_RG="rg-customer-sec"
   CUSTOMER_GALLERY="gal_customer_bluerock"
   IMAGE_DEF="bluerock-golden-linux"
   IMAGE_VER="1.0.4"
   LOCATION="eastus"
   SOURCE_IMAGE_VERSION_RESOURCE_ID="/subscriptions/<source-sub>/resourceGroups/<source-rg>/providers/Microsoft.Compute/galleries/<source-gallery>/images/<source-image-def>/versions/<source-version>"
| Text | Text | | ---------------------------------- | -------------------------------------------------------------------------------- | | **Parameter** | **Description** | | `CUSTOMER_SUBSCRIPTION_ID` | Azure subscription where the customer deploys Terraform resources. | | `CUSTOMER_RG` | Customer resource group for Compute Gallery resources. | | `CUSTOMER_GALLERY` | Customer Azure Compute Gallery name (customizable). | | `IMAGE_DEF` | Image definition name inside the customer gallery (e.g., bluerock-golden-linux). | | `IMAGE_VER` | Image version to publish/use (e.g., 1.0.4). | | `LOCATION` | Azure region for gallery resources (e.g., eastus). | | `SOURCE_IMAGE_VERSION_RESOURCE_ID` | Full Azure resource ID of the source image version to copy/publish from. | 2. **Run Provisioning Commands**:\ Execute the following Azure CLI commands to configure the gallery and import the image version*.* 
# Set target subscription
   $ az account set --subscription "$CUSTOMER_SUBSCRIPTION_ID"

   # Create Resource Group and Compute Gallery
   $ az group create --name "$CUSTOMER_RG" --location "$LOCATION"
   $ az sig create --resource-group "$CUSTOMER_RG" --gallery-name "$CUSTOMER_GALLERY" --location "$LOCATION"

   # Create Image Definition
   $ az sig image-definition create \
     --resource-group "$CUSTOMER_RG" --gallery-name "$CUSTOMER_GALLERY" \
     --gallery-image-definition "$IMAGE_DEF" --publisher "bluerock" \
     --offer "bluerock-golden-linux" --sku "stable" --os-type "Linux" \
     --hyper-v-generation "V2" --location "$LOCATION"

   # Create Image Version from Source
   $ az sig image-version create \
     --resource-group "$CUSTOMER_RG" --gallery-name "$CUSTOMER_GALLERY" \
     --gallery-image-definition "$IMAGE_DEF" --gallery-image-version "$IMAGE_VER" \
     --managed-image "$SOURCE_IMAGE_VERSION_RESOURCE_ID" --target-regions "$LOCATION" \
     --replica-count 1 --location "$LOCATION" \
     --query "{name:name,state:provisioningState}" -o table
{% hint style="info" icon="notes-sticky" %} **Note:** The `image-definition create` step is skippable if the definition already exists. {% endhint %} 3. **Terraform Mapping**:\ Upon successful image provisioning, set the `boot_image` variable in the `terraform.tfvars` file to the new gallery image version ID:
boot_image = "/subscriptions/<CUSTOMER_SUBSCRIPTION_ID>/resourceGroups/<CUSTOMER_RG>/providers/Microsoft.Compute/galleries/<CUSTOMER_GALLERY>/images/<IMAGE_DEF>/versions/<IMAGE_VER>"
### BlueRock Azure Architecture Components A typical Premium Public Deployment on Azure provisions the following resources: | **Azure Resource / Service** | **Description** | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Virtual Network (VNet) & Subnet | Provides an isolated virtual network environment. Can be newly created or linked to an existing network. | | Network Security Group (NSG) | Controls network traffic. Default rules allow inbound SSH access (Port 22) from a specified IP CIDR. | | Linux Virtual Machine | Runs the BlueRock MCP Server using the specified hardened Ubuntu image. | | User-Assigned Managed Identity | Grants the VM minimal role-based access control (RBAC) permissions to interact with Blob Storage and Azure Monitor. | | Storage Account & Blob Container | Stores runtime configuration files and cryptographic certificates for the BlueRock node. | | Log Analytics & App Insights | Optional external telemetry stack for collecting and monitoring system events, application logs, and OpenTelemetry (OTEL) data. | *** #### Deployment Package Overview **Directory Structure** The Azure Terraform scripts follow a structured hierarchy containing the necessary definition files: ```shellscript azure/compute/terraform/ubuntu/PublicDeployment/ ├── main.tf # Core Azure resource definitions ├── outputs.tf # Exported deployment variables ├── terraform.tfvars # Active variable values (created by user) ├── terraform.tfvars.example # Template for variable configuration ├── user_data.sh.tpl # Bootstrap script for the VM runtime ├── variables.tf # Variable declarations and validation rules └── README.md # Deployment documentation ``` *** ### `terraform.tfvars` Parameter Reference The following parameters are defined in the `variables.tf` file. These values must be updated in the local `terraform.tfvars` file to match the target Azure project environment before executing the deployment scripts. | **Parameter** | **Description** | **Required** | **Example / Default Value** | | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------- | | `subscription_id` | The unique Azure subscription ID used for deployment. | Yes | `11111111-2222-3333-4444-555555555555` | | `location` | Azure region where resources are provisioned. | Yes | `eastus` | | `prefix` | A string prefix applied to naming deployed resources. | No | `bluerock-premium` | | `allow_ip` | Ingress CIDR IP range permitted to access the network. | Yes | `0.0.0.0/0` | | `vnet_cidr` | CIDR block defined for the Virtual Network. | Yes | `10.20.0.0/16` | | `subnet_cidr` | CIDR block defined for the subnet. | Yes | `10.20.1.0/24` | | `existing_vnet_name` | Optional: Name of a pre-existing Virtual Network to use instead of creating a new one. | No | `vnet-shared-prod` | | `existing_subnet_name` | Optional: Name of a pre-existing subnet to use. | No | `snet-shared-prod` | | `existing_network_resource_group_name` | Optional: Resource group name of the existing network. | No | `rg-network-shared` | | `vm_size` | Hardware profile/size for the virtual machine. | Yes | `Standard_D4s_v5` | | `os_disk_type` | Storage tier for the operating system disk. | Yes | `Premium_LRS` | | `admin_username` | Primary administrator username for the instance. | Yes | `ubuntu` | | `existing_ssh_public_key_name` | Name of an existing SSH public key resource. | Yes | `my-ssh-key` | | `existing_ssh_public_key_resource_group_name` | Resource group containing the existing SSH key. | Yes | `shared-keys-rg` | | `boot_image` | Required: Azure custom image resource ID. | Yes | `/subscriptions/.../images/` | | `policy_storage_account_name` | Globally unique storage account name for policy artifacts. Must be 3-24 lowercase letters/numbers. | Yes | `bluerockpremiumpolicy01` | | `existing_storage_account_name` | Optional: Name of a pre-existing storage account for policy files. | No | `stsharedpolicy01` | | `existing_storage_container_name` | Optional: Name of a pre-existing storage container for policy files. | No | `policies` | | `existing_storage_resource_group_name` | Optional: Resource group of the existing storage account. | No | `rg-storage-shared` | | `enable_external_otel` | Flag to enable external OpenTelemetry integration. | Yes | `true` | | `monitor_resource_group_name` | Optional: Resource group name for monitoring integration. | No | `rg-bluerock-sentinel` | | `create_monitor_resource_group` | Optional: Flag indicating whether to create a new monitor resource group. | No | `false` | | `log_analytics_workspace_name` | Name of the Log Analytics Workspace. | Yes | `law-bluerock` | | `log_analytics_retention_days` | Data retention period for Log Analytics in days. | Yes | `90` | | `app_insights_name` | Name of the Application Insights component. | Yes | `ai-bluerock` | | `existing_log_analytics_workspace_name` | Optional: Name of an existing Log Analytics Workspace to reuse. | No | `law-shared` | | `existing_app_insights_name` | Optional: Name of an existing Application Insights component to reuse. | No | `ai-shared` | {% hint style="info" icon="notes-sticky" %} **Note:** Ensure the specified `vm_size` (e.g., `Standard_D2s_v3`) is available in the target `location` and meets Azure quota limits. Since Azure enforces VM deployments based on regional vCPU counts, verify sufficient capacity using: ```shellscript $ az vm list-usage --location eastus --query "[?contains(localName, 'vCPU')].{Name:localName, Current:currentValue, Limit:limit}" -o table ``` {% endhint %} *** ### Configuration Steps To prepare the environment for deployment, follow these steps to initialize the variables: 1. Navigate to the deployment directory: ```shellscript $ cd azure/compute/terraform/ubuntu/PublicDeployment/ ``` 2. Copy the example variables file to create a live configuration file: ```shellscript $ cp terraform.tfvars.example terraform.tfvars ``` 3. Edit the `terraform.tfvars` file and populate the mandatory fields, including the `subscription_id`, `boot_image`, and networking variables. {% hint style="info" icon="notes-sticky" %} **Note:** If deploying into an existing network or storage account, ensure the respective `existing_*` variables (e.g., `existing_vnet_name`, `existing_subnet_name`, `existing_storage_account_name`) are explicitly defined. Otherwise, Terraform will provision entirely new network and storage resources . {% endhint %} *** ### Running the Deployment Execute the standard Terraform workflow to provision the Azure infrastructure: 1. Initialize the working directory: ```shellscript $ terraform init ``` 2. Review the execution plan: ```shellscript $ terraform plan ``` 3. Apply the configuration: ```shellscript $ terraform apply ``` *** ### Post-Deployment Validation 1. Check BlueRock Instance:\ Verify the VM status and retrieve the Public IP address using the Azure CLI: 
$ az vm list -d --query "[?name=='<prefix>-node'].{Name:name, Status:powerState, PublicIP:publicIps}" -o table
For example: 
$ az vm list -d --query "[?name=='bluerock-test-node'].{Name:name, Status:powerState, PublicIP:publicIps}" -o table
Expected output: 
Name                Status      PublicIP
   ------------------  ----------  ----------
   bluerock-test-node  VM running  <public-ip-address>
2. Verify Services:\ Establish an SSH connection to the instance and verify the BlueRock control plane status: 1. Connect to the instance: 
$ ssh -i <path-to-priv-key> ubuntu@<ssh-ip-address>
2. Check the service status 
$ sudo systemctl status bluerockd.service
Expected Output: 
● bluerockd.service - Manage the Ultracontrol Docker Service
           Loaded: loaded (/etc/systemd/system/uc-docker.service; enabled; preset: enabled)
           Active: active (running) since Tue 2026-04-28 15:31:22 UTC; 12h ago
         Main PID: 2430 (uc-docker.sh)
            Tasks: 2 (limit: 4614)
           Memory: 648.0K (peak: 9.0M)
              CPU: 18.644s
           CGroup: /system.slice/uc-docker.service
                   ├─ 2430 /usr/bin/bash /opt/bluerock/bin/uc-docker.sh start
                   └─21732 sleep 5

      Apr 28 15:31:22 bluerock-test-node systemd[1]: uc-docker.service: Scheduled restart job, restart counter is at 1.
      Apr 28 15:31:22 bluerock-test-node systemd[1]: Started uc-docker.service - Manage the Ultracontrol Docker Service.
3. OTEL Event Collection 1. Locate the OTEL config file: ```shellscript $ cd /opt/bluerock/otel $ ls otel-config.yaml ``` 2. Edit the `otel-config.yaml` file based on the requirements. 3. Enable the otel service ```shellscript $ sudo systemctl enable otelcol.service ``` 4. Start the otel service ```shellscript $ sudo systemctl start otelcol.service ``` 5. Check the status of the otel service ```shell $ sudo systemctl status otelcol.service --no-pager -l ● otelcol.service - OpenTelemetry Collector (Bluerock) Loaded: loaded (/etc/systemd/system/otelcol.service; enabled; preset: enabled) Active: active (running) since Fri 2026-07-03 03:15:22 UTC; 7h ago Docs: https://opentelemetry.io/docs/collector/ Main PID: 3227 (aws-otel-collec) Tasks: 9 (limit: 18800) Memory: 19.9M (peak: 21.7M) CPU: 19.917s CGroup: /system.slice/otelcol.service └─3227 /opt/azure/aws-otel-collector/bin/azure-otel-collector --config=/opt/bluerock/otel/otel-config.yaml Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug builders/builders.go:24 Stable component. {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} Jul 03 03:15:22 ip-172-31-29-175 run-otelcol.sh[3227]: 2026-07-03T03:15:22.324Z debug Logger core does not support injecting component attributes {"resource": {"service.instance.id": "27df2ba6-b766-4dc7-9b5b-c80a5956c45c", "service.name": "aws-otel-collector", "service.version": "v0.44.0"}, "otelcol.component.id": "otlp", "otelcol.component.kind": "receiver", "otelcol.signal": "logs"} ``` *** ### Cleanup of Deployed Resource To remove or delete the deployed BlueRock instances or all resources, run the following command. ```shellscript $ terraform destroy --auto-approve ``` {% hint style="info" icon="notes-sticky" %} **Note:** Azure Monitor generates hidden Smart Detector Alert Rules that block the `terraform destroy` command. Clear these rules beforehand by executing: ```shellscript $ az resource list -g "" --resource-type "microsoft.alertsmanagement/smartDetectorAlertRules" --query "[].id" -o tsv | xargs -I {} az resource delete --ids "{}" ``` {% endhint %} *** ### View Logs in Azure For detailed instructions on how to view logs and OTEL events from the instance, please refer to the [View Logs in Azure](/deployment-guides/azure-deployments/azure-deployment-with-cli#view-logs-in-azure) section. *** ### Configuring Remote Project Workspace in Claude Desktop IDE For detailed instructions on how to set up and connect your remote environment, refer to the [Configuring Claude Desktop IDE](/deployment-guides/azure-deployments/azure-deployment-with-cli#configuring-remote-project-workspace-in-claude-desktop-ide) section. # BluerockCCPD Platform Overview ### Introduction BlueRockCCPD is a centralized observability and operational monitoring platform designed for monitoring MCP infrastructure, telemetry activity, sessions, alerts, and operational analytics. The platform combines dashboard visualization, telemetry ingestion, GraphQL services, authentication, analytics, and graph-based investigation capabilities into a unified deployment. BlueRockCCPD provides visibility into operational activity across MCP environments and enables users to monitor infrastructure, investigate events, analyze telemetry, visualize relationships between entities, and access operational dashboards and reports through a centralized interface. Key capabilities include: * MCP infrastructure visibility * Event and telemetry monitoring * Session tracking * Topology exploration * Alert monitoring * Analytics dashboards * Operational reporting * Graph-based investigation and tracing *** ## Platform Architecture Overview BlueRockCCPD is a modular, cloud-native platform that provides centralized observability, monitoring, analytics, and policy management for BlueRock deployments. The platform collects operational data from monitored environments, processes and correlates telemetry, and presents actionable insights through a unified dashboard. The platform consists of the following functional capabilities: | Capability | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Data Collection** | Collects telemetry, events, alerts, and operational data from BlueRock Runtime, MCP applications, AI agents, and monitored infrastructure. | | **Data Processing** | Processes, enriches, and correlates collected data to generate operational insights and policy events. | | **Monitoring and Analytics** | Provides dashboards, metrics, analytics, and health monitoring for BlueRock deployments. | | **Policy Management** | Supports centralized policy configuration and operational monitoring across monitored environments. | | **Graph-based Investigation** | Enables relationship visualization and investigation of entities, sessions, events, and telemetry. | | **Authentication and Access Control** | Secures platform access through authentication and role-based authorization. | This architecture enables organizations to monitor operational activity, investigate events, analyze telemetry, and visualize relationships across BlueRock deployments through a centralized interface. *** ## Core Data Model BlueRockCCPD organizes operational data into interconnected entities that can be explored and analyzed through dashboards, reports, and graph-based investigations. A typical operational flow consists of: ``` Host └─ MCP Server └─ MCP Agent └─ Session └─ Events └─ Tools ``` This relationship model enables users to trace activity across hosts, MCP servers, MCP agents, sessions, and operational events. *** ## Dashboard Access The platform is accessed through HTTPS endpoints. ### Dashboard URLs | Service | URL | | ------------- | --------------------------------------- | | Dashboard | [https://localhost](https://localhost/) | | OTLP Endpoint | | *** ### HTTPS Access The dashboard uses HTTPS with a self-signed certificate. During initial access, the browser may display a security warning. Accept the warning to continue accessing the dashboard. *** ## Exposed Ports | Port | Protocol | Purpose | | ---- | -------- | ---------------------------------------------- | | 443 | HTTPS | Dashboard, Grafana, Authentication, API Access | | 8080 | HTTP | OTLP event processing | *** ## Authentication and Authorization BlueRockCCPD uses WorkOS AuthKit for authentication and session management. Authentication is enforced before users can access dashboard functionality, APIs, analytics, and monitoring data. #### Authentication Flow The authentication process is performed as follows: 1. User navigates to the dashboard. 2. Frontend requests are routed through Nginx. 3. Nginx validates authentication using `auth_request`. 4. Unauthenticated users are redirected to `/login`. 5. WorkOS AuthKit performs authentication. 6. WorkOS redirects users to `/auth/callback`. 7. Authentication tokens are generated. 8. Session cookies are stored for authenticated requests. 9. Subsequent requests use the authentication cookie for validation. *** ### Role-Based Access Control (RBAC) BlueRockCCPD supports role-based access control for managing access to platform functionality. #### Supported Roles | Role | Description | | -------- | ----------------------------- | | Admin | Full platform access | | Operator | Operational monitoring access | | Viewer | Read-only access | #### Supported Capabilities Role assignments determine access to: * Dashboard views * Alerts * Telemetry data * Analytics dashboards * GFL queries * Reports * Platform operations *** ## Dashboard Capabilities The platform provides visibility into operational activity across the MCP ecosystem. ### Dashboard Features The dashboard supports: * Topology visualization * Timeline analysis * Graph exploration * Event monitoring * Session visibility * Alert visibility * Telemetry analysis * Analytics dashboards * Report generation *** ## Event Processing and Telemetry BlueRockCCPD processes telemetry and operational events using OTLP over HTTP. Events are collected, processed, enriched, and stored for operational monitoring and analytics. ### Telemetry Configuration BlueRockCCPD supports multiple methods for sending telemetry and operational events to the platform using OpenTelemetry Protocol (OTLP) over HTTP. Events can be sent using either of the following methods: * Configure an OpenTelemetry Collector using the `otel-config.yaml` configuration file. * Configure the BlueRock client using the `bluerock.toml` configuration file and specify the OTLP HTTP endpoint. **Example:** ``` [otlp.http]url = "http://:8080/" ``` Regardless of the configuration method used, events are ingested by the BlueRock platform and become available for dashboards, reports, alerts, analytics, and graph-based investigations. ### Event Visibility The dashboard provides visibility into: * Alert timelines * Event metadata * Event relationships * Host activity * Session activity * Real-time telemetry ### Telemetry Pipeline The telemetry pipeline includes: * OTLP event processing * Session telemetry * MCP activity monitoring * Event aggregation * Operational analytics Telemetry information is used throughout the platform for dashboards, analytics, reporting, alerts, and investigations. *** ## Graph Filter Language (GFL) BlueRockCCPD supports Graph Filter Language (GFL) for querying, filtering, aggregating, and analyzing entities within the platform. GFL enables users to investigate relationships, filter entities, generate aggregations, and visualize operational activity. ### GFL Features GFL supports: * Entity filtering * Query pipelines * Aggregation * Timeline analysis * Visualization transforms * Graph filtering #### Example Queries ``` gfl "mc.state == 'active'" ``` ``` gfl "mc | count by mc.state" ``` ``` gfl "mc | count by mc.state | bar" ``` #### GFL CLI Location ``` /usr/local/bin/gfl ``` *** ## Operational Monitoring BlueRockCCPD supports operational monitoring workflows across MCP infrastructure, telemetry, sessions, alerts, and analytics. Users can: * Monitor MCP agents * Monitor MCP servers * Analyze sessions * Review telemetry activity * Investigate alerts * Analyze event timelines * Explore entity relationships * Monitor analytics dashboards Operational data is available through dashboards, reports, alerts, graph exploration views, and analytics interfaces. *** ## Troubleshooting ### Common Checks Perform the following checks during troubleshooting: * Dashboard accessibility * Telemetry visibility * Event availability * Graph loading * Dashboard refresh behavior *** ## Health Endpoints ``` curl -sk https://localhost/health ``` ``` curl -s http://localhost:8080/health ``` ``` curl -s http://localhost:8123/ping ``` ### Useful Commands ``` docker logs -f bluerockccpd ``` ``` docker exec bluerockccpd s6-svstat /run/service/hramp ``` *** ## FAQ ### Why does the browser show "Not Secure"? The dashboard uses a self-signed certificate. Accept the browser warning during initial access. ### Why are some dashboard panels empty? Some dashboard panels require incoming event traffic before metrics and visualizations are displayed. ### Why are graphs not loading? Verify telemetry visibility, active event traffic, selected filters, and selected time ranges. ### When should GFL be used? GFL should be used when filtering entities, investigating operational activity, tracing relationships, analyzing sessions, or generating custom operational insights. ### What is the difference between dashboards and graph exploration? Dashboards provide summarized operational visibility, while graph exploration enables users to investigate relationships, dependencies, sessions, and activity across entities in greater detail. # Bluerock Dashboard User Guide ## Introduction The BlueRock Dashboard provides a centralized interface for monitoring MCP infrastructure, telemetry activity, sessions, events, alerts, analytics, and operational reports. The dashboard enables users to: * Monitor MCP infrastructure and activity * Investigate alerts and policy violations * Analyze telemetry and events * Visualize topology relationships * Review operational analytics * Monitor MCP agents and servers * Explore historical and real-time activity * Investigate operational trends and anomalies *** ## Accessing the Dashboard The dashboard is accessed through HTTPS. ### Dashboard URL ``` https:// ``` ### Grafana URL ``` https:///grafana ``` ### Browser Security Warning The dashboard uses a self-signed certificate. During first access, the browser may display a security warning or "Not Secure" message. Accept the warning to continue accessing the dashboard. *** ## Dashboard Navigation The left-side navigation menu provides access to dashboard sections and monitoring views. ### Main Navigation Areas * Dashboard * Hosts * MCP Servers * MCP Agents * Tools * Alerts * Event Log * Reports * Explore * Workbooks * Reactive Rules * HRamp Operations * A2M Analytics
*** ## Dashboard Home The Dashboard Home page provides a high-level summary of MCP ecosystem activity. ### Dashboard Metrics The dashboard displays the following summary metrics: * Alerts * Reviewed/Dismissed Alerts * Events * Servers * Tools * Agents * Hosts These metrics provide a quick overview of platform activity and operational health. #### User Interface Example:
*** ### Dashboard Widgets #### Agent Ecosystem The Agent Ecosystem section displays information about MCP agents operating within the environment. The visualization helps users understand: * Active agent inventory * Agent distribution * Agent activity trends * Framework utilization #### Recent Events The Recent Events section displays operational events collected by BlueRock. Events may include: * Informational events * Warning events * Error events * Operational events This section provides visibility into recent activity occurring within the monitored environment. #### MCP Activity Trends The MCP Activity section provides visibility into MCP operational activity. The dashboard displays: * Active MCP sessions * Session creation activity * Session termination activity * MCP activity trends over time These metrics help users understand MCP utilization patterns and operational behavior. #### Top Tools The Top Tools widget displays the most frequently utilized MCP tools within the environment. This visualization helps identify: * Frequently used tools * Tool activity patterns * Operational trends #### User Interface Example:
*** ### Time Filtering The dashboard supports time-based filtering for viewing recent operational activity. Available views depend on the selected dashboard and time range. #### User Interface Example:
*** ## Hosts The Hosts page displays infrastructure hosts monitored by BlueRock. Users can review host inventory and investigate host-related activity. ### Host Information Each host entry displays: * Host Name * First Seen * Last Seen ### Available Actions #### Graph Displays host relationships within the topology graph. #### Historical Displays historical activity for the selected host. #### User Interface Example:
*** ## MCP Servers The MCP Servers page displays registered MCP servers. ### MCP Server Information Each server entry displays: * Server Name * Host * Entity ID * Last Seen * Created Timestamp ### Available Actions #### Graph Displays server relationships within the topology graph. #### Historical Displays historical activity associated with the selected server. #### User Interface Example:
*** ## MCP Agents The MCP Agents page displays discovered MCP clients and agents. ### Agent Information Each agent entry displays: * Agent Name * Host * Entity ID * Component * Last Seen * Created Timestamp Users can review agent activity and investigate relationships between agents, sessions, and MCP servers. #### User Interface Example:
*** ## AI Agent Monitoring BlueRock supports monitoring of AI agents and AI-assisted workflows. Examples may include: * Claude Code * Cursor * Gemini CLI * Codex CLI * Custom AI Agents Available visibility includes: * Tool Calls * Token Consumption * Permission Denials * Errors * Cost Metrics * Sub-Agent Activity This information helps users understand AI usage patterns and operational behavior. *** ## Tools The Tools page displays tools registered by MCP servers. ### Tool Information Each tool entry displays: * Tool Name * Description * Associated Server ### Example Tools #### read\_file Reads file contents. #### write\_file Creates or modifies files. #### remove\_file Deletes files. #### User Interface Example:
*** ## Alerts The Alerts page displays operational alerts and policy violations. ### Alert Categories The dashboard supports: * Active Alerts * Acknowledged Alerts * Dismissed Alerts #### User Interface Example:
*** ### MCP Policy Violations Policy violations are generated when MCP activity violates configured security policies. Example: ``` check_message_size ``` #### Alert Information Each alert displays: * Alert ID * Rule Name * Host * Timestamp * Occurrence Count ### Alert Actions Available actions include: * Acknowledge * Dismiss #### User Interface Example:
*** ## Event Log The Event Log page provides access to operational events. ### Event Log Features The Event Log supports: * Event Search * Event Filtering * Event Export * Event Analysis ### Time Filters Available time ranges include: * 1 Hour * 6 Hours * 24 Hours * 3 Days * 7 Days #### User Interface Example:
*** ## Reports The Reports page provides pre-built operational reports. ### Accessing Reports 1. Navigate to Reports. 2. Browse available reports. 3. Click View to generate a report. #### User Interface Example:
*** ### Available Reports The Reports page includes several predefined reports.
ReportDescription
Active Hosts OverviewUnified view of hosts with status distribution, pulse vitals, and regional breakdown.
MCP Sessions ReportSession inventory with client-server connections, success rates, and lifecycle states.
Alert Trends & Critical AlertsAlert severity trends with detailed critical alert drill-down.
Top Tools UsageTool call counts, success rates, and average execution times.
Tool Failure AnalysisTool failures, error codes, and failure patterns.
MCP Agent ActivityAgent inventory, status, session counts, request velocity, and host associations.
MCP Server ActivityServer inventory with status, registered tools, session activity, and request throughput.
#### User Interface Example:
*** ## Explore The Explore page provides an interactive topology visualization of the MCP ecosystem. ### Root Views Available root views include: * Default * MCP Servers * Agents * Sessions * LLMs #### User Interface Example:
*** ### Layout Modes The topology graph supports multiple layouts: * Tree * Force * Circle * Group #### User Interface Example:
*** ### Graph Filter Language (GFL) The Explore page supports Graph Filter Language (GFL) expressions for filtering and analyzing entities. GFL is used throughout BlueRock for: * Entity filtering * Relationship analysis * Session tracing * Activity investigation * Operational analytics #### Common Entity Types | Prefix | Entity | | ------ | ---------- | | ho | Host | | ms | MCP Server | | mc | MCP Agent | | ss | Session | | tl | Tool | | mo | Model | | ag | AI Agent | | al | Alert | #### Example Filters ``` mc.state == 'active' ``` ``` ms.transport == 'stdio' ``` ``` pivot mc mc == ALL ``` #### Time-Based Filtering **Examples:** ``` since 1h ``` ``` since 24h ``` ``` mc.state == 'active' && since 6h ``` #### User Interface Example:
*** ### Session Tracing Explore supports graph-based tracing of relationships between entities. A typical investigation workflow may involve: Host → Agent → MCP Server → Session → Event Activity This enables users to follow operational activity across the MCP ecosystem and investigate issues. *** ### Ghost Entities Ghost entities represent historical relationships that are no longer active. #### User Interface Example:
*** ### Re-layout The Re-layout action redraws the topology using the selected layout algorithm. #### User Interface Example:
*** ## Workbooks The Workbooks page provides access to predefined and custom analytical workbooks. Workbooks organize charts, tables, and analytical panels into reusable investigation views. #### User Interface Example:
*** ### Available Workbooks Examples visible in the dashboard include: * agent-drill-down * agent-health * danger-tool-audit * error-investigation * health-matrix * llm-cost-performance * llm-operations * mcp-activity * ops-triage * production-triage * server-overview * session-drill-down * topology-and-stats *** ### Workbook Purpose Workbooks help users: * Investigate incidents * Analyze trends * Monitor infrastructure * Review session activity * Track agent behavior * Perform operational triage *** ### Workbook Panel Types Workbooks may contain: * Charts * Tables * Time Series * Health Tests * Snapshots * Event Views * Alert Views *** ### Creating a Workbook 1. Navigate to Workbooks. 2. Select Create Workbook. 3. Configure workbook details. 4. Add charts and panels. 5. Save the workbook. #### User Interface Example:
*** ## Reactive Rules Reactive Rules allow users to create automated operational monitoring rules. Rules monitor selected entities and trigger actions when configured conditions are met. #### User Interface Example:
*** ### Creating a Rule 1. Select New Rule. 2. Enter a rule name. 3. Define a GFL expression. 4. Configure conditions. 5. Configure actions. 6. Save the rule. #### User Interface Example:
*** ### Rule Components #### GFL Expression A GFL expression defines the scope of entities that the rule evaluates. The expression is used to identify the graph entities that should be monitored by the rule. Example: ``` mc.state == 'active' ``` #### **Rule Conditions** Rule conditions define the criteria that must be met before an action is triggered. Conditions are configured during rule creation and are evaluated against the entities returned by the GFL expression. #### **Actions** Actions define the response that occurs when the configured rule conditions are met. *** ## HRamp Operations Dashboard The HRamp Operations dashboard provides operational telemetry visibility. ### Dashboard Metrics Visible metrics include: * Active Hosts * Total Active Entities * Total Terminated Sessions ### Dashboard Panels The dashboard includes: * Top Event Types by Volume * Event Type Counts * Active MCP Sessions * Session Creation Rate * Total MCP Sessions Created * Session Termination Reasons #### User Interface Example:
*** ## Agent-to-Model (A2M) Analytics The A2M Analytics dashboard provides visibility into LLM activity, token consumption, latency, and cost. ### Purpose A2M Analytics helps organizations understand how AI models are being used across monitored environments. ### Supported Use Cases #### Agent Monitoring Organizations running AI agents can monitor: * Model Usage * Framework Usage * Token Consumption * Cost * Request Volume * Latency #### Developer AI Usage Organizations using AI-assisted development tools can monitor: * LLM Utilization * Token Consumption * Cost Trends * Model Adoption ### Dashboard Metrics Visible metrics include: * Total Calls * Pending Requests * Completed Requests * Input Tokens * Output Tokens * Models * Frameworks ### Dashboard Panels The dashboard includes: * LLM Call Rate * Token Consumption Rate * Call Latency * Calls by Model * Model Distribution * Framework Distribution * Cost Trends #### User Interface Example:
*** ## LLM Cost Dashboard ### Overview The **LLM Cost** dashboard provides operational visibility into Large Language Model (LLM) usage by monitoring token consumption, estimated costs, and model utilization across AI agents and applications. The dashboard helps administrators understand LLM usage patterns and identify opportunities to optimize AI workloads. *** #### Dashboard Views The dashboard displays estimated LLM token consumption and cost information. Data can be grouped using the following dimensions: * Team * User * Application * Agent * Model * Framework * Tag The dashboard supports multiple time ranges, including: * Last 1 hour * Last 6 hours * Last 24 hours * Last 7 days *** #### Dashboard Panels **LLM Cost** Displays estimated LLM token consumption and cost information. The table provides usage statistics grouped by the selected view (Agent, Model, Framework, Team, or Tag) and includes: * Selected grouping dimension * Usage trend * Input token count * Output token count * Estimated cost (when available) Users can switch between grouping options to analyze LLM usage from different operational perspectives. **Calls by Outcome** Displays the distribution of completed LLM requests based on request outcomes. The panel summarizes: * Total tool calls * Stop conditions * Average response length * Percentage distribution of each outcome This information helps administrators understand request completion behavior and overall workload characteristics. **Tokens per Call** Displays statistical information about input and output token consumption for each language model. The panel includes: * Input token distribution * Output token distribution * Percentile statistics (P50, P95, and P99) These metrics help identify models generating unusually large requests or responses. **Containment Activity** Displays alerts generated by configured cost-control rules and other containment policies. This panel helps administrators identify policy violations, abnormal LLM usage patterns, and cost-related operational events. #### User Interface Example:
*** #### Grouping Views The LLM Cost dashboard allows users to analyze usage data using the following views: **Agent View** Displays token usage and estimated cost information grouped by AI agent. This view helps identify: * High-utilization agents * Token consumption by individual agents * Estimated LLM cost per agent * Input and output token counts * Usage trends
**Model View** Displays token usage grouped by Large Language Models. This view enables administrators to: * Compare model utilization * Identify heavily used models * Compare token consumption across models * Review estimated costs by model
**Framework View** Displays token usage grouped by AI framework or provider, such as OpenAI, Anthropic, Gemini, or LiteLLM. This view helps compare framework utilization and understand token consumption across different AI providers.
**Team View** Displays aggregated LLM usage grouped by organizational team. This view enables administrators to compare token consumption and estimated costs across teams and identify which teams are generating the highest LLM usage.
**User View** Displays LLM usage grouped by individual users, allowing administrators to analyze token consumption, estimated costs, and usage patterns for each user. **Application View** Displays LLM usage grouped by application or service, enabling administrators to compare token consumption and estimated costs across applications. *** #### Operational Benefits The LLM Cost dashboard helps administrators: * Monitor LLM token consumption across AI workloads. * Compare usage across agents, models, frameworks, applications, and teams. * Identify the most frequently used AI models and providers. * Understand request characteristics using call outcome statistics. * Analyze input and output token distribution across models. * Detect abnormal usage through containment policies and alerts. * Optimize AI usage and reduce operational costs. *** ### LLM Cost Alerts #### Overview The LLM Cost Alerts page provides visibility into alerts generated when configured LLM cost-control or containment policies are triggered. Alerts are generated when configured thresholds detect abnormal LLM activity, excessive token usage, or other cost-related conditions requiring administrator attention. Administrators can review alert details, investigate related events, and perform follow-up actions to understand and resolve abnormal LLM usage. #### Alert Information Each alert includes information to help administrators understand the detected condition, including: * Alert severity * Alert status * Alert type * Timestamp * Affected agent or application * Alert description * Associated containment policy * Related operational events This information helps administrators quickly identify the cause of the alert and determine the appropriate response. #### Alert Actions The Alerts page provides the following actions for managing and investigating alerts: * **Acknowledge** the alert after review. * **Dismiss** alerts that do not require further action. * **Add to TODO** for follow-up investigation. * **View Events** to examine the events associated with the alert. * **View Trace** to analyze the execution path leading to the alert. * **Analyze** to investigate the alert using the available analytics and investigation tools. These actions help administrators investigate policy violations, understand runtime behavior, and perform operational troubleshooting. #### User Interface Example:
*** ### Agent-to-Model (A2M) Analytics #### Overview The **Agent-to-Model (A2M) Analytics** dashboard provides operational insights into interactions between AI agents and Large Language Models (LLMs). It enables administrators to monitor request volume, token consumption, model utilization, framework distribution, and call performance over time. Unlike the LLM Cost dashboard, which focuses on cost and token usage, the A2M Analytics dashboard emphasizes request volume, latency, model utilization, and operational performance. The dashboard helps identify usage trends, evaluate model performance, and optimize AI workloads. #### Dashboard Panels **Summary Metrics** Provides an overview of LLM activity, including: * Total calls * Pending calls * Completed calls * Input tokens * Output tokens * Models in use * Frameworks in use **LLM Call Rate** Displays the rate of LLM requests over time for each model, helping administrators monitor workload trends and identify spikes in activity. **Token Consumption Rate** Displays input and output token usage over time, allowing users to analyze token consumption patterns across different language models. **Call Latency (Average)** Displays the average response time for LLM requests, enabling users to monitor model performance and identify latency trends. **Calls by Model** Displays the distribution of requests across configured language models, helping administrators understand model utilization. **Calls by Framework** Displays the distribution of requests across supported AI frameworks or providers, such as OpenAI, Anthropic, Gemini, and LiteLLM. #### Time Filter The dashboard supports viewing analytics over configurable time ranges. Users can select the desired time period from the time filter to analyze recent activity. #### User Interface Example:
*** ### Token Usage Policy Control #### Overview The Token Usage Policy Control feature enables administrators to monitor and control Large Language Model (LLM) token consumption. The policy helps prevent excessive token usage by enforcing configurable limits on individual requests and overall token consumption. When enabled, the policy can generate violations or block requests that exceed configured limits. It also provides token usage information that is displayed in the BlueRock Dashboard for operational monitoring and cost analysis. **Note:** Token usage monitoring is supported for the LLM Model Framework sensors, including OpenAI, Anthropic, Gemini, and LiteLLM. It is not supported for Coding Sensors in this release. #### Policy Configuration The Token Usage Policy Control feature is configured using the **`llm_max_tokens`** policy. **Default Policy:** ```json "llm_max_tokens": { "enable": false, "remediate": false, "max_total_tokens_per_call": null, "bucket_enabled": false, "bucket_capacity": 100000, "refill_rate": 200.0, "multiplier": 0.3, "refuse_fewer_than_tokens": 100, "token_estimator": "bytes_div4" } ``` **Configuration Parameters**
ParameterDescription
enableEnables or disables token usage monitoring.
remediateWhen enabled, requests exceeding configured limits are blocked.
max_total_tokens_per_callMaximum combined input and output tokens permitted for a single LLM request. Null means no limit.
bucket_enabledEnables token bucket rate limiting.
bucket_capacityMaximum number of tokens that can accumulate in the token bucket.
refill_rateNumber of tokens added to the bucket per second.
multiplierMultiplier applied to available bucket tokens to determine the effective request allowance.
refuse_fewer_than_tokensRejects requests when the remaining available response token budget falls below the configured threshold.
token_estimatorMethod used to estimate input token usage.
*** #### Generated Events The Token Usage Policy Control feature generates operational events that provide visibility into LLM token usage and policy enforcement. **Usage Event** A python\_llm\_reply event is generated for each monitored LLM request. The event contains token usage statistics together with the model and framework information. **Token Limit Violation Event** A python\_llm\_max\_tokens\_violation event is generated in the following situations: • When max\_total\_tokens\_per\_call is configured and the estimated request and response tokens exceed the configured limit. • When refuse\_fewer\_than\_tokens is configured and the effective response token budget falls below the configured threshold. **Event Examples** The following examples demonstrate the operational events generated by the Token Usage Policy Control feature. **Example 1 – Usage Event** The following example shows a python\_llm\_reply event containing token usage statistics. **Policy Configuration** ```json "llm_max_tokens": { "enable": true, "remediate": true, "max_total_tokens_per_call": 2048, "bucket_enabled": true, "bucket_capacity": 10000, "refill_rate": 200.0, "multiplier": 0.3, "refuse_fewer_than_tokens": 100, "token_estimator": "bytes_div4" } ``` **Event Output** {% code expandable="true" %} ```json { "created": 1783409328, "id": "chatcmpl-7d7295d5-42c3-42f5-87f1-ea613929d8b5", "model": "claude-sonnet-4-6@default", "object": "chat.completion", "usage": { "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "completion_tokens": 53, "completion_tokens_details": { "reasoning_tokens": 0, "text_tokens": 53 }, "prompt_tokens": 2375, "prompt_tokens_details": { "cache_creation_token_details": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_creation_tokens": 0, "cached_tokens": 0, "text_tokens": 2375 }, "total_tokens": 2428 }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/7dac4012-146e-44a2-bc3e-e4745f33e6b4", "domain": "gyro", "event_name": "python_llm_reply", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "bluepython", "sensor_id": 3727, "source_event_id": 18, "type": "event" } } ``` {% endcode %} **Example 2 – Maximum Token Limit Violation** The following example shows a python\_llm\_max\_tokens\_violation event generated when the estimated request and response tokens exceed the configured max\_total\_tokens\_per\_call limit. **Remediation Disabled** ```json "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "LLM request max_tokens set to 1744 (was Some(4096), input estimate: 304)", "event_name": "python_llm_max_tokens_violation", "type": "log" } ``` **Remediation Enabled** ```json "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "LLM request max_tokens set to 889 (was Some(4096), input estimate: 2036)", "event_name": "python_llm_max_tokens_violation", "remediation_kind": "modify", "type": "remediation" } ``` **Example 3 – Response Token Threshold Violation** The following example shows a python\_llm\_max\_tokens\_violation event generated when the effective response token budget falls below the configured refuse\_fewer\_than\_tokens threshold. **Remediation Disabled** ```json "severity_number": 13, "severity_text": "WARN", "attributes": { "description": "LLM request refused: effective max_tokens 12 is below threshold 100 (input estimate: 2036)", "domain": "gyro", "event_name": "python_llm_max_tokens_violation", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "uc-gyro", "sensor_id": 3737, "source_event_id": 17, "type": "log" } ``` **Remediation Enabled** ```json "severity_number": 17, "severity_text": "ERROR", "attributes": { "description": "LLM request refused: effective max_tokens 80 is below threshold 100 (input estimate: 390)", "domain": "gyro", "event_name": "python_llm_max_tokens_violation", "hostid": "ip-172-31-39-21.ec2.internal", "origin": "acoustic Python sensor", "remediation_kind": "block", "sensor_id": 3746, "source_event_id": 52, "type": "remediation" } ``` *** ## Operational Diagnostics The Operational Diagnostics panel displays diagnostic events generated by the platform. Users can: * View diagnostic events * Review operational health information * Clear diagnostic entries #### User Interface Example:
*** ## User Profile The User Profile panel displays authenticated user information. Information displayed includes: * User Email * Role * Capabilities #### User Interface Example:
*** ## Common User Workflows ### Monitoring MCP Activity Users can: * Monitor MCP agents * Monitor MCP servers * Analyze sessions * Review activity trends * Explore topology relationships ### Investigating Alerts Users can: * Review active alerts * Analyze policy violations * View related events * Investigate traces ### Exploring Infrastructure Users can: * Open Explore * Apply GFL filters * Switch layouts * Analyze relationships ### Monitoring Analytics Users can: * Review A2M metrics * Analyze token consumption * Monitor latency trends * Review operational dashboards ### Managing Reactive Rules Users can: * Create rules * Configure triggers * Monitor rule activity *** ## Troubleshooting ### Dashboard Not Loading Verify: * Dashboard accessibility * HTTPS connectivity * Active dashboard instance ### Empty Dashboard Panels Some dashboard views require active event traffic before data becomes visible. ### Graph Loading Issues Verify: * Selected filters * Selected time ranges * Event visibility * Active telemetry ingestion ### Alert Visibility Issues Verify: * Event ingestion * Active policies * Alert generation *** ## FAQ ### Why does the browser show "Not Secure"? The dashboard uses a self-signed certificate. Accept the browser warning to continue. ### Why are some dashboards empty? Certain dashboards require incoming telemetry and event traffic before data is displayed. ### Why are graphs not loading? Verify event visibility, filters, and selected time ranges. # BlueDev Container - Introduction ## Introduction to BlueDev Container BlueDev Container executes development workloads inside a devcontainer on a remote host. By moving the execution environment to dedicated host infrastructure, client machines maintain standard local workflows without bearing the computational overhead. ### Core System Capabilities #### Remote Workload Execution Offloads container image builds, source code checkouts, language toolchains, and AI agent executions entirely to the remote host. #### Minimal Local Dependencies Eliminates the need for local installation of Docker Desktop, local Docker daemons, and the Docker CLI on client workstations. #### Native Client Integration Connects local development environments (VS Code, Cursor, Claude Code Desktop, and Codex) to remote containers using a local SSH proxy. #### Enforced Access Control Secures the host boundary by restricting incoming connections to a shell-less bouncer service and authenticating requests using short-lived, OIDC-signed SSH user certificates. ### Deployment and Usage Flow {% stepper %} {% step %} #### BlueDev Identity Deployment Kit Deploy the identity service to handle OIDC authentication and issue short-lived SSH user certificates for host access. For setup/deployment details, refer to the [BlueDev Identity Deployment Kit doc](/bluedev-container/bluedev-identity-deployment-kit). {% endstep %} {% step %} #### BlueRock Connector for VS Code and Cursor Install and configure the editor extension to attach local VS Code or Cursor sessions to remote containers via the **BlueRock Identity** or local **SSH proxy**. For setup and usage details, refer to the BlueRock Connector for [VS Code](/bluedev-container/bluerock-connector-for-vs-code) and [Cursor](/bluedev-container/bluerock-connector-for-cursor-ide) doc. {% endstep %} {% step %} #### BlueRock Connector for Claude and Codex IDE Deploy the desktop application and CLI to connect standalone AI agents (Claude Code Desktop and Codex) directly to remote sandboxes. For setup and usage details, refer to the [BlueRock Connector for Claude and Codex IDE](/bluedev-container/copy-of-bluerock-connector-for-claude-and-codex-ide) doc. {% endstep %} {% endstepper %} {% hint style="warning" %} **Important:** The guides in this current section apply to the latest BlueRock release v26.23.1. For documentation regarding BlueRock v23.26.0, please refer to the [Archive (v26.23.0)](/bluedev-container/archive-v26.23.0) section. {% endhint %} # BlueDev Identity Deployment Kit The Bluedev Identity Deployment Kit provides instructions for bringing up a StepCA server to manage OIDC provisioners and handle enrollment requests initiated by `bluedev-bouncer` on BlueRock hosts. The StepCA server can be deployed either directly within a BlueRock VM instance or on a separate VM to serve multiple BlueRock instances. The StepCA package contains Docker files for StepCA and Caddy, along with `just` command scripts for setup and management. * **StepCA:** Registers OIDC provisioners for `bluedevx` sign-in and accept enrollment authentication requests initiated by `bluedev-bouncer`. * **Caddy (Optional):** Handles automatic TLS certificate generation and maintenance from Let's Encrypt for public deployments. For private, VPN-gated network architectures, StepCA can run independently without Caddy by binding directly to a private interface.
### StepCA Deployment {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** Whether deployed on a BlueRock VM or an independent VM, StepCA can generate TLS certificates using a Public IP address instead of a DNS domain. For successful enrollment, ensure firewall or security group rules permit inbound traffic from BlueRock host instances to the StepCA port via this IP. {% endhint %} #### Prerequisites and Installation 1. Extract the package source: ```shellscript $ mkdir bluedevca $ cp /opt/bluerock/bluedev-identity-ca-0.1.0.tar.gz ~/bluedevca/ $ cd ~/bluedevca/ $ tar zxvf bluedev-identity-ca-0.1.0.tar.gz ``` 2. Install prerequisites: 1. For AL2023: ```shellscript $ sudo dnf install -y spal-release $ sudo dnf install -y just $ sudo dnf install docker $ sudo usermod -aG docker ec2-user $ sudo systemctl enable docker.service $ sudo systemctl start docker.service $ sudo systemctl status docker $ sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/libexec/docker/cli-plugins/docker-compose $ sudo chmod +x /usr/local/bin/docker-compose ``` 2. For Ubuntu: ```shellscript $ sudo apt-get update $ sudo apt-get install -y docker.io just curl $ sudo usermod -aG docker $USER $ sudo systemctl enable docker.service $ sudo systemctl start docker.service $ sudo systemctl status docker $ sudo mkdir -p /usr/lib/docker/cli-plugins $ sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m) -o /usr/lib/docker/cli-plugins/docker-compose $ sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose ``` ### Configure Environment Navigate to the `compose` directory and configure the environment settings: ```shellscript $ cd compose/ $ cp .env.example .env $ vi .env ``` Set the bouncer password matched during BlueRock Host enrollment: ```shellscript BOUNCER_PASSWORD= ``` ### **Choose a Deployment Architecture** Configure the `.env` file based on the required network architecture: #### Private Deployment (without Caddy) Use this configuration for a CA reachable over a VPN-gated private subnet or SSH tunnel (without Caddy). StepCA publishes directly on a specific interface using self-signed TLS certificates generated for the designated private IP. ```shellscript # Host address the :9000 listener publishes on STEPCA_BIND_ADDR= # Host port for the publish + client URL STEPCA_BIND_PORT=9000 ``` {% hint style="info" icon="notes-sticky" %} **Note:** Avoid setting `STEPCA_BIND_ADDR` to `0.0.0.0`. This configuration generates the leaf certificate without Subject Alternative Name (SAN) information and bypasses strict firewall routing. Specify the exact private IP address and let the subnet's security group serve as the security boundary. For without caddy deployment, `CADDY_DOMAIN` should be blank. {% endhint %} #### Public Deployment (with Caddy) Use this configuration for a publicly reachable StepCA server using Let's Encrypt or a local CA: ```shellscript # Public DNS address OR Public IP address of the Step CA VM instance CADDY_DOMAIN= # Email used for Let's Encrypt registration CADDY_ACME_EMAIL= # Standard incoming ports to allow in AWS Security Group CADDY_HTTP_PORT=80 CADDY_HTTPS_PORT=443 ``` {% hint style="info" icon="notes-sticky" %} **Note:** When a registered public DNS domain is unavailable, set `CADDY_DOMAIN` directly to the Public IP address of the VM instance (for example, `CADDY_DOMAIN=000.0.000.00`). StepCA will include the Public IP in the Subject Alternative Names (SANs) of the certificate so client handshakes validate without certificate naming errors. For without caddy deployment, `CADDY_DOMAIN` should be blank. {% endhint %} ### Configure Google Identity Provisioner 1. Create a Google OIDC Desktop Client App via the Google Cloud Console (*Requires admin privileges*) to enable Google Workspace integration.\ \ To create a Google OIDC app: 1. Access the **Google Cloud Console** and select or create a project. 2. Navigate to **APIs & Services**, then select **Credentials**. 3. Configure the **OAuth Consent Screen** by selecting the user type (**Internal** or **External**) and defining the mandatory fields, such as the App Name and support email. 4. Select **Create Credentials** and choose **OAuth client ID**. 5. Select **Desktop** app as the **Application type**. This automatically sets the redirect URI to `http://127.0.0.1`. Define a name and select **Create**. 6. Copy the generated **Client ID** and **Client Secret**. {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** For additional context on Google's authentication protocols, refer to the official documentation: * [OAuth 2.0 API Guidelines](https://developers.google.com/identity/protocols/oauth2) * [OpenID Connect Overview](https://developers.google.com/identity/openid-connect/openid-connect) {% endhint %} 2. Copy and edit the Google provider template: 
$ cd providers/
   $ cp provisioner.env.example google.env
   $ vi google.env
3. Configure the required parameters: ```shellscript PROVISIONER_NAME=google ISSUER_URL=https://accounts.google.com CLIENT_ID= CLIENT_SECRET= ADMINS= DOMAIN_RESTRICT= BLUEDEV_DOMAINS= DEFAULT_SSH_CERT_DURATION=8h MAX_SSH_CERT_DURATION=24h ``` **Google Workspace Provisioner Configuration Variables** Review and define the following variables carefully before executing the provisioner setup script. Incorrect values will prevent successful host enrollment and developer authentication. | **Variable** | **Description** | **Notes** | | --------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | `PROVISIONER_NAME` | The internal identifier for the OIDC provisioner within the StepCA configuration. | Example: `google` | | `ISSUER_URL` | The OpenID Connect discovery endpoint for Google Workspace. | The value must be exactly `[https://accounts.google.com](https://accounts.google.com)`. | | `CLIENT_ID` | The OAuth 2.0 Client ID generated within the Google Cloud Console credentials page. | Required to identify the application to Google's authorization servers. | | `CLIENT_SECRET` | The sensitive OAuth 2.0 Client Secret paired with the designated Client ID. | Must be kept secure and never committed to version control. | | `ADMINS` | A comma-separated list of administrator email addresses authorized to manage the CA. | Example: `admin@domain.com` | | `DOMAIN_RESTRICT` | The specific email domain authorized to authenticate via this OIDC provisioner. | Example: `bluerock.io` | | `BLUEDEV_DOMAINS` | The domain name utilized for generating the SSH principal mapping. | Typically matches the `DOMAIN_RESTRICT` value. | | `DEFAULT_SSH_CERT_DURATION` | The standard time-to-live (TTL) validity period assigned to issued SSH certificates. | Example: `8h` | | `MAX_SSH_CERT_DURATION` | The absolute maximum validity period permitted for issued SSH certificates. | Example: `24h` | #### Service Bring-Up and Management Review available commands using `just help`: ```shellscript bluedev-identity — CA-side deployment kit SETUP just up [--no-caddy] bring step-ca [+ caddy] up; register provisioners just add register OIDC provisioner from providers/.env just remove remove OIDC provisioner from step-ca SHARE WITH DOWNSTREAM just fingerprint [|--auto] print CA root SPKI (or full pin URL) just bouncer-info print bouncer enrollment inputs (URL + name + password) MAINTENANCE just update [ca|caddy|all] apply config changes (default: all) — non-destructive just rotate-bouncer-password re-key bouncer provisioner (DESTRUCTIVE: invalidates enrolled bouncers) just info read-only health + state probe just dump-config [ca|caddy|defaults] print live container config (default: ca) just down [--force] destructive teardown (containers + volumes) KIT DEVELOPMENT just test [unit|component|all] run the test gate (auto-detects step-ca for component) Per-verb detail: just --help ``` 1. Register the OIDC provider and start services: ```shellscript $ just add google $ just up ``` 2. Check health status: ```shellscript $ just info ``` \ Expected Output: ```shellscript == bluedev-identity info (read-only) == filesystem [ ok ] compose/.env present [ ok ] BOUNCER_PASSWORD set docker [ ok ] daemon reachable [ ok ] compose plugin v2 containers [ ok ] step-ca running [ ok ] caddy running (ec2-3-144-79-172.us-east-2.compute.amazonaws.com) step-ca api [ ok ] /health 200 ok provisioners [ ok ] google registered bluedev JWK provisioners [ ok ] bluedev-bouncer registered (dev-host bouncers auth as this) [ ok ] admin (break-glass) info-only; not for routine signing Summary: HEALTHY ``` 3. Retrieve the auto-generated CA enrolment string: ```shellscript $ just fingerprint --auto ``` Output format: ```shellscript https://:443#fp= ## Example using Public IP: `https://000.0.000.00:443#fp=a1b2c3d4e5...` ``` \ For private deployments, the generated fingerprint URL utilizes the specified private IP address.\ \ Output format: ```shellscript https://:443#fp= ## Example using Private IP: `https://x0x.x0.x0.xx:443#fp=a1b2c3d4e5...` ``` {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** Executing a destructive teardown regenerates the CA fingerprint and requires re-enrolling the bouncer on all VMs. Do not execute `just down --force` for routine configuration modifications. To apply configuration changes to an existing deployment without losing the CA fingerprint, execute the non-destructive update command: ```shellscript $ just update ca ``` {% endhint %} ### Modifying Certificate Expiration (TTL) To extend the session validity period and reduce sign-out frequency, update the Time-to-Live (TTL) settings in the provider configuration. 1. Open the relevant provider environment file (for example, `providers/entra.env` or `providers/google.env`). 2. Update the duration parameters to the required validity period (for example, 168 hours). The `MAX_SSH_CERT_DURATION` value must always be greater than or equal to the `DEFAULT_SSH_CERT_DURATION` value: ```yaml DEFAULT_SSH_CERT_DURATION=168h MAX_SSH_CERT_DURATION=168h ``` 3. Apply the configuration changes by executing the non-destructive update command: ```shellscript just update ca ``` {% hint style="info" icon="notes" %} **Note:** Updated validity periods take effect upon the next authentication. Existing sessions maintain the current expiration until the next sign-in. {% endhint %} #### Enrol BlueRock Host Log in to the BlueRock VM and execute the enrollment command using the generated CA URL: ```shellscript $ sudo bluedev-bouncer enroll --ca https://:443#fp= --passoword ``` Enter the `BOUNCER_PASSWORD` when prompted {% hint style="info" icon="notes-sticky" %} **Note:** `` accepts either the domain name or raw **Public IP address** of your StepCA server. {% endhint %} ### Configure Microsoft Entra ID Provisioner 1. Create an OIDC Desktop App using App Registrations in the Azure Portal to enable Microsoft Entra ID integration.\ \ To create a Microsoft Entra ID app: 1. Access the **Azure Portal** and navigate to **Microsoft Entra ID**. 2. Select **App registrations**, then select **New registration**. 3. Define the application name and select the supported organizational directory account types. 4. Set the **Platform** to **Public client (mobile & desktop)**. 5. Set the Redirect URI to `http://127.0.0.1`. 6. Select **Register** and copy the generated Application (client) ID. {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** For detailed architectural context, refer to the official [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-overview). {% endhint %} 2. Create and edit `entra.env`: 
$ cd providers/
   $ vi entra.env
3. Configure the required parameters: ```shellscript PROVISIONER_NAME=entra ISSUER_URL=https://login.microsoftonline.com//v2.0/.well-known/openid-configuration CLIENT_ID= ADMINS= DOMAIN_RESTRICT= BLUEDEV_DOMAINS= DEFAULT_SSH_CERT_DURATION=8h MAX_SSH_CERT_DURATION=24h ``` **Entra ID Provisioner Configuration Variables** Review and define the following variables carefully before executing the provisioner setup script. Incorrect values will prevent successful host enrollment and developer authentication. | Variable | Description | Notes | | --------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- | | `PROVISIONER_NAME` | The internal identifier for the OIDC provisioner within the StepCA configuration. | Example: `entra` | | `ISSUER_URL` | The OpenID Connect discovery endpoint for the Microsoft Entra ID tenant. | Replace `` with the exact Entra tenant ID. | | `CLIENT_ID` | The Application (client) ID generated during the Entra ID app registration process. | Located in the Entra ID application overview panel. | | `ADMINS` | A comma-separated list of administrator email addresses authorized to manage the CA. | Example: `admin@domain.com` | | `DOMAIN_RESTRICT` | The specific email domain authorized to authenticate via this OIDC provisioner. | Example: `bluerock.io` | | `BLUEDEV_DOMAINS` | The domain name utilized for generating the SSH principal mapping. | Typically matches the `DOMAIN_RESTRICT` value. | | `DEFAULT_SSH_CERT_DURATION` | The standard time-to-live (TTL) validity period assigned to issued SSH certificates. | Example: `8h` | | `MAX_SSH_CERT_DURATION` | The absolute maximum validity period permitted for issued SSH certificates. | Example: `24h` | #### Bring-Up Service Register the Entra ID provider and start services: ```shellscript $ just add entra $ just up ``` #### Retrieve Fingerprint and Enroll Host 1. Get the host enrollment string: ```shellscript $ just fingerprint --auto ``` \ Expected output: ```shellscript https://:443#fp= ``` 2. Log in to the target BlueRock VM and execute enrollment: ```shellscript $ sudo bluedev-bouncer enroll --ca https://:443#fp= --password ``` \ Enter the `BOUNCER_PASSWORD` when prompted ### Unenroll a BlueRock Host If the BlueRock Identity Service was previously configured on a host instance, the bouncer must be unenrolled to prevent configuration conflicts before switching to a different authentication method (such as SSH Key Trust) or decommissioning the environment. To reverse a host enrollment and clear the Certificate Authority (CA) trust configuration, execute the following command directly on the BlueRock host instance terminal: ```shellscript $ sudo bluedev-bouncer unenroll ``` Command Actions: The `unenroll` command reverses the `enroll` process. Upon execution, it performs the following system modifications: * Removes the bouncer SSH configuration file (`/etc/ssh/sshd_config.d/51-bluedev-bouncer-ca.conf`). * Deletes the CA public key located at `/etc/bluedev/user_ca.pub` (unless the `--keep-ca-pubkey` flag is specified). * Removes all host-certificate files (unless the `--keep-host-cert` flag is specified). ### Bluedev Bouncer CLI Reference The `bluedev-bouncer` runs directly on the target BlueRock host to handle system setup and CA trust enrollment. Below is the complete command-line interface surface for operator reference. ```shellscript $ sudo bluedev-bouncer --help ``` Expected output: ```shellscript CLI surface of the bouncer. The binary has exactly two shapes: - **Session mode** — sshd `ForceCommand` runs the binary with empty argv; clap parses no subcommand; the bouncer reads the verb from `SSH_ORIGINAL_COMMAND` and routes through the wire verb allowlist (`crates/verbs`). The wire cannot reach any operator surface. - **Operator mode** — one of the [`Command`] subcommands. All host-mutation and diagnostic verbs go here for a single uniform surface. Plan 08 (`plans/08-install-subcommand.md`) drove the lifecycle half; `self-check` / `print-paths` / `build-catalog` / `install-catalog-packages` were promoted alongside so the operator-facing CLI doesn't mix flag-style and subcommand-style modes. Usage: bluedev-bouncer [OPTIONS] [COMMAND] Commands: install Install bluedev-bouncer on this host. Performs the host setup: useradd, conffile placement, state-dir creation, sshd snippet two-phase commit, tmpfiles, systemctl reload. Idempotent; requires root uninstall Uninstall bluedev-bouncer. Reverses `install`. Catalog and packages dirs are preserved unless `--purge` enroll Opt-in CA trust + (optional) host-cert signing via a CA provisioner. Writes `/etc/bluedev/user_ca.pub`, optionally signs the host's SSH host keys, writes `/etc/ssh/sshd_config.d/51-bluedev-bouncer-ca.conf`. Trust-only path and JWK signing path are both wired unenroll Reverse of `enroll`. Removes the `51-*` snippet, the CA pubkey at `/etc/bluedev/user_ca.pub` (unless `--keep-ca-pubkey`), and every host-cert file (unless `--keep-host-cert`) doctor Read-only health probe. Reports install + enroll status, host-cert expiry warnings (<7 days = warn; expired = error), `sshd -t` cleanliness, allowlist shape validity. Exit 0 = clean; 1 = warnings; 2 = errors self-check Operator health probe. Verifies docker daemon reachability, devcontainer CLI on PATH, `git >= 2.25`, allowlist files present, scratch perms, etc. Exit codes per check print-paths Print resolved `[paths]` values from the config file as shell-eval-safe `KEY='value'` lines on stdout. One parser (this binary) owns the TOML schema; downstream scripts read from here build-catalog Pre-build every devcontainer template under `[paths] catalog_root` so subsequent `up` invocations skip the slow image-build step. Writes to `bluedev-primed/:latest` install-catalog-packages Bake every template's `[paths] packages_root` `.deb`/`.rpm` contents into the primed image. Skips `devcontainer build` — `--install-catalog-packages` invokes it internally — so subsequent `up` skips both build AND runtime package install link Serve one protocol-v2 link connection over stdin/stdout. The v2 sshd `ForceCommand` entry point: reads the handshake from stdin, authenticates from the SSH session environment, and runs the multiplexed dispatch loop until the link closes help Print this message or the help of the given subcommand(s) Options: --config Path to the bouncer's main config file. Applies to every subcommand that loads config (session mode included) [default: /etc/bluedev/bouncer.toml] -h, --help Print help (see a summary with '-h') ``` ### View Active `bluedev-bouncer` Sessions Execute the `bluedev-bouncer sessions` command to display all containers managed by the `bluedev-bouncer` and view active client sessions on the BlueRock host: ```bash $ sudo bluedev-bouncer sessions CONTAINER ID NAME WORKSPACE OWNER IMAGE STATE SESSIONS CLIENTS 9e224510d573 coral-claude-ar-c1 claude-workload- @.com bluedev-primed/coral-claudedesktop:latest running 1 (11m) 5f19294b67f5 ubuntu-bluerock ubuntu-bluerock- @.com bluedev-primed/ubuntu-bluerock:latest running 1 (15s) 8c998a803c05 ubuntu-bluerock-ar-c2 ubuntu-bluerock- @.com bluedev-primed/ubuntu-bluerock:latest running 2 (10m), (3m) ``` # BlueRock Connector for VS Code The BlueRock Connector extension authenticates to connect to and execute the BlueRock instance VM, and to run Sandbox containers from VS Code. This document details the configuration, authentication, and access requirements for the BlueRock Connector VS Code extension. #### Setup and Configuration Workflow Follow the complete deployment path below, or jump directly to the required phase: 1. [**Prerequisites**](#prerequisites) 2. [**Host Enrollment**](#host-enrollment) 3. [**VS Code Identity Configuration**](#setting-up-the-identity) 1. [BlueRock Identity Service](#bluerock-identity-service) 2. [SSH Key Trust](#ssh-key-trust) 4. [**Working with Containers**](#working-with-containers) 1. [Creating a Container using Catalog](#creating-a-container-using-catalog) 2. [Creating a Container using a Git Repo](#creating-a-container-using-a-git-repo) 5. [**Manage Containers**](#manage-containers) 6. [**OTEL Events**](#otel-events) ### Prerequisites * [VS Code](https://code.visualstudio.com/) (latest version) * Remote - SSH extension (from Microsoft VS Code Marketplace) * BlueRock Connector VS Code Extension (from Microsoft VS Code Marketplace).
{% hint style="warning" %} **Windows System Requirements:** The **BlueRock Connector** requires the **Microsoft Visual C++ Redistributable** package `VCRUNTIME140.dll` to function correctly on **Windows**. Ensure optimal performance by installing this package via the terminal before launching the connector: ```shellscript winget install Microsoft.VCRedist.2015+.x64 ``` {% endhint %} #### Host Enrollment Run the BlueRock host enrollment directly on the BlueRock instance VM before configuring the BlueRock Connector in VS Code. 1. Access the BlueRock instance VM terminal. 2. Run the following command to enroll the `bluedev-bouncer`: ```shellscript $ sudo bluedev-bouncer enroll --ca --password ``` \ Enter the `BOUNCER_PASSWORD` when prompted. 3. Construct the `` by combining the instance's Public DNS (or IP address) and the appropriate SHA256 fingerprint: ``` https://#fp= ``` 1. **Obtaining the Public DNS / IP Address** Navigate to the respective cloud provider console such as AWS, GCP, or Azure to locate the public address of the BlueRock instance: 2. **Obtaining the Fingerprint (``)** The required fingerprint depends on the chosen authentication method for the workspace: * **For BlueRock Identity Service (OIDC):** The fingerprint is the SHA-256 hash of the CA certificate. Retrieve this directly from the identity service administrator, or by running `just fingerprint --auto` on the CA host. For more details, refer to the [BlueDev Identity Development Kit](/bluedev-container/bluedev-identity-deployment-kit). * **For SSH Key Trust:** The fingerprint is the host's SSH key fingerprint. Retrieve it by running the following command on the local machine, replacing `` with the public address obtained above: Bash ```shellscript ssh-keyscan -t ed25519 | ssh-keygen -lf - ``` ### Setting up the Identity Once the BlueRock Connector extension is installed, restart VS Code. The extension will load in the left panel. In the extension, select the **Setup** button to configure the BlueRock Instance using either of the following authentication methods. 1. BlueRock Identity Service 2. SSH key trust #### BlueRock Identity Service 1. Select the **Enroll with identity service...** button.
2. Insert the [**`Bootstrap URL`**](#host-enrollment) . ```shellscript https://#fp= ``` 3. Enter the Public DNS or IP Address of the instance and select **Enroll**.
4. Select **Sign-in** and complete the authentication on the browser.
5. After successful authentication, the left panel will show the green icon next to the identity and host.
When authenticated with the identity service, the following files are created on the BlueRock instance: {% code overflow="wrap" %} ```shellscript $ ls -l .config/bluedev/identity/ total 12 -rw------- 1 bluerock bluerock 200 Jun 30 08:56 config.toml -rw------- 1 bluerock bluerock 179 Jun 30 08:57 known_hosts drwx------ 2 bluerock bluerock 4096 Jun 30 08:56 trust $ cat .config/bluedev/identity/config.toml schema_version = 1 service_url = "https://" default_provisioner = "google" tls_trust_mode = "system" [host] address = "0.101.010.0" user = "bluedev" ``` {% endcode %} #### SSH key trust {% hint style="info" icon="notes-sticky" %} **Note**: If **BlueRock Identity Service** is previously configured, then unenroll the bouncer on the host instance first to prevent configuration conflicts before switching to the **SSH Key Trust**: {% code overflow="wrap" %} ```shellscript $ sudo bluedev-bouncer unenroll ``` {% endcode %} {% endhint %} 1. Select the **Set up SSH key Trust...** button to enroll using an existing SSH key.
2. Run the following command on the local machine to get the fingerprint (`SHA256: `): 
ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1
\ Insert the Bootstrap string with the following format ``` #fp=SHA256: ``` \ For example: ``` 10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU ``` 3. Select **Verify**, and once verified, select **I have compared these and they match - Next** button.
4. Select the required key from the local `.ssh` folder or select **Use another key file...** to browse the other keys. Click the **Configure** button.
{% hint style="info" icon="notes-sticky" %} **Note:** Ensure the same key is present in the `.ssh` folder of the instance's Bluedev profile. For that, run the following commands:
```shellscript ## Switch to bluedev user $ sudo su bluedev # Create the .ssh directory with correct permissions $ mkdir -p ~/.ssh $ chmod 700 ~/.ssh # Add your local public key to authorized_keys $ vi ~/.ssh/authorized_keys # Set secure permissions for the authorized_keys file $ chmod 600 ~/.ssh/authorized_keys ``` {% endhint %} ### Working with Containers #### Creating a Container using Catalog Once the instance is successfully connected to VS Code, create containers using a pre-built template from the Catalog. These reside at the `/srv/bluedev/catalog` in the BlueRock instance with packages at `/srv/bluedev/packages`. By default, the BlueRock Instance ships the following catalog containers: * **Claude workload sandbox**:\ It’s a template specifically for the Claude IDE for dev containers. * **Fedora - BlueRock dev**:\ It’s a template with a Fedora environment for dev containers. * **Ubuntu - BlueRock dev**:\ It’s a template with an Ubuntu environment for dev containers. To launch them in VS Code, select the **Arrow** icon next to the container template. It will create the Container and connect it automatically. For example, starting an **Ubuntu - BlueRock dev** container
Then the Ubuntu Container will be created on the fly and load in a new VS Code window with all its files. While loading, click the **Connecting to Dev Container (show log)** dialog box
To trust the authors of the files and folders\ ![](/files/55xgKdcWsrSAosazHtXk) Also loads pre-installed packages such as Claude, Gemini, and Codex in the container. Authenticate the package with the required account to run within the container. For example, using Claude to create a dummy shell script in the Ubuntu container.
#### Creating a Container using a Git Repo Select the Repo tab and paste the GitHub/GitLab repo link that has `devcontainer.json` . Click **Warp**; it will fetch the `devcontainer.json`.
For the first time on a new repo, it will prompt to **Trust this repo** to build and create hooks defined in the repo.
Also, provide the Personal Access Token (PAT) of your GitLab/GitHub account once prompted. Select the Container based on the options from the `devcontainer.json` file.
Then it will clone the repo, create the container, and open it in a new VS Code window. ### Manage Containers Select the **Containers** tab to manage the Containers created with different icons. * **Arrow** icon to attach the container in a new VS Code window. * **Pen** icon to rename the container. * **Square** icon to stop the running container. * **Bin** icon to destroy the container and its content from VS Code and the host.
### OTEL Events In CloudWatch, all events are captured for all actions triggered on any Container from VS Code. \ \ For example, the following CloudWatch OTEL log shows an OTEL event of `sensor_startup` lifecycle event emitted by `bluerockd` when the identity monitoring agent binary initializes on a host. {% code overflow="wrap" %} ```json { "body": { "file_path": "/opt/bluerock/bin/blueclaude", "pid": 00000, "principal": "@.com" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "sensor_startup", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 0, "type": "sensor_lifecycle" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
Another example is an OTEL event `claude_hook` event emitted by `bluerockd` when a new Claude session (`SessionStart`) initializes within a user's workspace context. {% code overflow="wrap" %} ```json { "body": { "context": { "process": { "pid": 00000 } }, "cwd": "/home//", "hook_event_name": "SessionStart", "session_id": "xxx-xxx-xxx-xxx-xxx", "source": "startup", "transcript_path": "/home//.claude/projects/xxx/xxx.jsonl" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "claude_hook", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 1, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
# BlueRock Connector for Cursor IDE The BlueRock Connector extension authenticates to connect to and execute the BlueRock instance VM and to run Sandbox containers from Cursor. This document details the configuration, authentication, and access requirements for the BlueRock Connector Cursor extension. ### Install BlueRock Connector on Cursor #### Install from Cursor Marketplace Execute the following steps to install the BlueRock Connector extension directly from the Cursor IDE: 1. Open **Cursor** and click the **IDE** button in the index window. To open the Cursor IDE.
2. Navigate to the **Extensions** view by clicking the Extensions icon in the Activity Bar, or utilize the keyboard shortcut (`Ctrl` + `Shift` + `X` on Windows/Linux, Cmd + Shift + X on macOS). 3. Enter BlueRock Connector into the search bar.
4. Locate the official BlueRock Connector extension within the search results and click **Install**. #### Export Extension from VS Code 1. Open **Cursor** and click the **IDE** button in the index window. To open the Cursor IDE.
2. In the Cursor IDE, press Ctrl + Shift + P (for macOS Cmd + Shift + P ), and select **Import VS Code Extensions and Settings**.
3. All VS Code settings and extensions will be transferred to your Cursor IDE, and displaythe BlueRock Connector extension will be displayed Cmd ) the BlueRock Connector extension in the left pane.
### Extension Usage and Configuration The BlueRock Connector extension functions identically across both the VS Code and Cursor environments. For comprehensive instructions on configuring the SSH host, executing Sandbox containers, and managing active sessions, refer to the core [VS Code Usage Guide](/bluedev-container/bluerock-connector-for-vs-code#setting-up-the-identity). # BlueRock Connector for Claude and Codex IDE BlueRock Connector is available for both Windows and macOS, acting as a secure bridge between local AI IDEs ([Claude Code](https://claude.com/product/claude-code) or [Codex](https://openai.com/codex/)) and the remote BlueRock sandbox. It enables a fully remote coding workspace by launching and managing the `bluedev-container` on the BlueRock Host VM. Additionally, the application handles local port forwarding and supports secure SSH logging into the remote container using Sign in with BlueRock or SSH key-based authentication. ### Key Capabilities * **Secure Enrollment:** \ Authenticates securely using Sign in with BlueRock or SSH keys. * **Environment Management:** \ Creates, stops, restarts, or destroys the remote BlueRock sandbox directly from the local system tray or menu bar. * **Seamless IDE Integration:** \ Automatically configures local listener ports (e.g., port 2259) to bridge the local workspace with the remote container. {% hint style="info" icon="notes" %} **Note:** Core functionality and workflows remain identical across both Windows and macOS, despite adapting to the native operating system interface. {% endhint %} ### Supported Platforms Select the operating system to view the complete guide on getting started and working with the Connector: * [Windows](/bluedev-container/bluerock-connector-for-claude-and-codex-ide/bluerock-connector-windows) * [macOS](/bluedev-container/bluerock-connector-for-claude-and-codex-ide/bluerock-connector-macos) # BlueRock Connector - Windows The BlueRock Connector application for Windows establishes a secure bridge between local AI IDEs ([Claude Code](https://claude.com/product/claude-code) or [Codex](https://openai.com/codex/)) and the remote BlueRock sandbox. The application natively handles SSO and SSH key authentication, local port forwarding, and container lifecycle management to enable a fully remote coding workspace. ## Prerequisites ### Software and Client Applications * **IDEs**: * [Claude Code IDE](https://claude.com/product/claude-code) * [Codex](https://openai.com/codex/) * **BlueRock Connector App**: \ Contact [BlueRock support](https://www.bluerock.io/contact) to obtain `BlueRock_Connector_win64.exe`. * **OpenSSH Client**: \ The client must be installed and added to the system PATH (e.g., `C:\Windows\System32\OpenSSH\`). {% hint style="info" icon="notes" %} **Note:** The OpenSSH Client is an optional Windows feature and is frequently removed from hardened corporate images. {% endhint %} ### System Requirements **Operating System**: Windows 11 (24H2 or later) is required for file transfers between the local machine and the BlueRock environment. {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** Install the application strictly in the user's context. Do not install the application machine-wide or via "Run as administrator," because the Connector stores identity locally in the user profile. {% endhint %} ### Network and Security * **Virtual Private Network (VPN):** \ If the BlueRock instance resides on a private network, active VPN connectivity is required to reach the instance. * **Endpoint Protection:** \ On desktop clients running firewalls or security software, allow port `2259` for inbound connections. The BlueRock Connector application runs a listener service on port 2259 and the loopback interface. The traffic is internal and never leaves the device. ## Installation Locate the `BlueRock_Connector_win64.exe` application and double-click to run it. {% hint style="info" icon="notes" %} **Note:** Windows will display a standard publisher notification warning message because the application is not from Microsoft. Proceed through the prompt to install and run the application. {% endhint %} ## Authentication and Enrollment 1. Once the application opens, select the **Set Up Connector** button. 2. Select **Continue** on the welcome screen.
3. Choose one of the following authentication methods: 1. Sign in with BlueRock\ *Also, known as Single Sign On (SSO) login option.* 1. Select the **Sign in with BlueRock** option then select **Next**.
2. Provide the bootstrap string URL in the **Enrollment URL** field and enter the public DNS or IP address of the BlueRock host in the **Dev host** field. Click **Sign in**.
3. Complete the sign-in flow in the web browser to authorize the application.
2. SSH Key 1. Select the **SSH key** option then select **Next**.
2. Run the following command on the local machine to obtain the fingerprint: ```shellscript $ ssh-keyscan -T 10 -t ed25519 | ssh-keygen -lf - 2>&1 ``` 3. Enter the Bootstrap string in the application using the following format: `#fp=SHA256:` (For example: `10.101.01.101#fp=SHA256:0x0x...`) 4. Click **Browse**, select the required SSH private key, and click **Install Key**.
{% hint style="info" icon="notes" %} **Note:** Ensure the same SSH public key is present in the `.ssh` folder of the instance's Bluedev profile. Run the following commands on the BlueRock instance to configure the key: ```shellscript sudo su sudo su bluedev mkdir -p ~/.ssh chmod 700 ~/.ssh vi ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` {% endhint %} 4. Then click **Close and Continue to Connector** to proceed working with the connector app.
## Environment Lifecycle Management ### Create Sandbox Select the **Create sandbox** button to initialize the remote container.
### Stop Sandbox Click **Stop Sandbox** to halt the running container.
### Destroy Environment Click **Destroy Sandbox** to completely purge and delete the container instance from the host.
Click **Destroy Sandbox - confirm** buttong in the prompt to destrory the sandbox and its files completely.
## Connecting AI Tools and Workspace Integration ### Connecting to Claude Code IDE 1. Select the **Connect Claude** button in the Connector app.
2. Select **Open Claude Desktop** and follow the instructions given on the screen.
3. In the Claude Code IDE: 1. Click the **Code** menu option. 2. Select **Local** > **SSH** > **Add SSH Host...**
3. Enter `cobalt-59` only in the **SSH Host** field, with the other details as per the requirements, and click **Add SSH Connection**.
Then Claude Code will SSH into the instance, and any tasks or development scripts created inside this window will now execute directly inside your active remote `bluedev` Docker container.
{% hint style="info" icon="notes-sticky" %} **Note:** OTEL events are generated by the `blueclaude_sensor` for all the actions done by the coding agent running inside the remote container. {% endhint %} ### Connecting to Codex 1. Select the **Connect Codex** button in the Connector app.
2. Follow the on-screen dialog instructions and click the provided link to authenticate. A one-time code is also present to enter while setting up an OpenAI account.
3. Authenticate with the OpenAI/ChatGPT account in the default browser.
4. Enter the one-time code and select **Continue**.
5. Upon completion of OpenAI account setup, the BlueRock Connector app gives a new prompt to **Open Codex Settings**.
6. In Codex, navigate to **Connections** > select **SSH** > click **Add**.
7. Select **Remote** and click **Next** to create a new remote project.
8. Select `cobalt-59` and click **Add.** Add the connection as a project to the Codex workspace.
9. In the New Remote Project pane, select **cobalt-59** from the Remote dropdown and select **Add Project**.
Once the project connects successfully, it will be added in the SSH section.
Then use it as a project in the Codex workspace.
### Verifying Session Execution and Script Output 1. In the connected Claude IDE or Codex environment, provide a prompt to create a basic "**Hello World**" Python script to verify the session. 2. Review and verify the script output directly within the IDE's terminal or shell.
### Browsing Remote Sandbox Files via System File Explorer 1. In the BlueRock Connector application, select the **Browse Files** option.
2. View and interact with the remote files directly within **Windows Explorer**.
\ The `bluedev` container mounts natively on the Windows file system under **Network Locations**.
## Maintenance and Troubleshooting ### Exporting Connector Logs To troubleshoot issues, export the application logs directly from the system tray. Right-click the **BlueRock Connector** icon in the System Tray and select **Export Logs...**. Save the generated log file to a preferred location.
### Resetting Connector Configuration Select **Reset** in the **Sandbox** dialog box.
Then confirm the prompt to clear the current configuration.
#### **Re-authenticating After Reset or Expiration** When a session expires or after stopping/destroying containers and resetting configuration, remote network locations automatically unmount, and Docker containers terminate. Re-run Authentication and Sandbox Creation to establish a new session. * After stopping the container
* After destroying the container
# BlueRock Connector - macOS The BlueRock Connector application for macOS establishes a secure bridge between local AI IDEs ([Claude Code](https://claude.com/product/claude-code) or [Codex](https://openai.com/codex/)) and the remote BlueRock sandbox. The application natively handles SSO and SSH key authentication, local port forwarding, and container lifecycle management to enable a fully remote coding workspace. Here is the complete documentation content tailored specifically for the macOS sub-page. ## Prerequisites ### Software and Client Applications * I**DEs:** * [Claude Code IDE](https://claude.com/product/claude-code) * [Codex](https://openai.com/codex/) * **BlueRock Connector App**: \ Contact [BlueRock support](https://www.bluerock.io/contact) to obtain the `BlueRock-Connector-notarized.zip` file. ### System Requirements * **Operating System**: \ macOS (macOS 13 Ventura or later recommended). {% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** Install the application strictly in the user's context. Do not install the application system-wide or as the root user, because the Connector stores identity locally in the user profile. {% endhint %} ### Network and Security * **Virtual Private Network (VPN)**: \ If the BlueRock instance resides on a private network, active VPN connectivity is required to reach the instance. * **Endpoint Protection**: \ On desktop clients running firewalls or security software, allow port `2259` for inbound connections. The BlueRock Connector application runs a listener service on port `2259` and the loopback interface. The traffic is internal and never leaves the device. ## Installation 1. Locate and unzip the `BlueRock-Connector-notarized.zip` file to extract the application. 2. Double-click the extracted application to run it. {% hint style="info" icon="notes" %} **Note:** When launching the application, macOS might display a warning indicating that the application was downloaded from the internet. Click **Open** to proceed. {% endhint %} Access the BlueRock Connector from the Menu Bar (Status Menus) as well.
## Authentication and Enrollment 1. Once the application opens, select the **Set Up Connector** button. 2. Select **Continue** on the welcome screen.
3. Choose one of the following authentication methods: 1. Sign in with BlueRock:
1. Select the Sign in with BlueRock option. 2. Provide the bootstrap string URL in the **Enrollment URL** field and enter the public DNS of the BlueRock host in the **Dev host** field. Click **Sign in**.
3. Complete the sign-in flow in the web browser to authorize the application. 2. SSH Key
1. Select the **SSH key** option. 2. Run the following command on the local machine to obtain the fingerprint: ```shellscript $ ssh-keyscan -T 10 -t ed25519 | ssh-keygen -lf - 2>&1 ``` 3. Enter the **Bootstrap string** in the application using the following format: `#fp=SHA256:` (For example: 10.101.01.101#fp=SHA256:0x0x...) 4. Click **Browse**, select the required SSH private key, and click **Install Key**.
{% hint style="info" icon="notes" %} **Note:** Ensure the same SSH public key is present in the `.ssh` folder of the instance's Bluedev profile. Run the following commands on the BlueRock instance to configure the key: ```shellscript sudo su sudo su bluedev mkdir -p ~/.ssh chmod 700 ~/.ssh vi ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` {% endhint %} 4. Then click **Close and Continue to Connector** to proceed working with the connector app.
## Environment Lifecycle Management ### Create Sandbox Select the **Create sandbox** button to initialize the remote container. *(Insert macOS Create Sandbox screenshot here)* ### Stop Sandbox Click **Stop Sandbox** to halt the running container. *(Insert macOS Stop Sandbox screenshot here)* ### Destroy Environment Click Destroy Sandbox to completely purge and delete the container instance from the host. *(Insert macOS Destroy Sandbox screenshot here)* ## Connecting AI Tools and Workspace Integration ### Connecting to Claude Code IDE 1. Select the Connect Claude button in the Connector app. \ \ *(Insert macOS Connect Claude screenshots here)* 2. In the Claude IDE, click the Code menu option and select Local. \ \ *(Insert macOS Claude Local option screenshot here)* 3. Select Add SSH Host. \ \ *(Insert macOS Claude Add SSH screenshot here)* 4. Enter `cobalt-59` in the SSH Host field and click Add SSH Connection. \ \ *(Insert macOS Claude Add Connection sequence screenshots here)* ### Connecting to Codex 1. Select the Connect Codex button in the Connector app. \ \ *(Insert macOS Connect Codex screenshot here)* 2. Follow the on-screen dialog instructions and click the provided link to authenticate. \ \ *(Insert macOS Codex Auth sequence screenshots here)* 3. In Codex, navigate to Connections > select SSH > click Add. \ \ *(Insert macOS Codex Add SSH screenshot here)* 4. Select Remote and click Next. \ \ *(Insert macOS Codex Remote configuration screenshot here)* 5. Select `cobalt-59` and click Add. Add the connection as a project to the Codex workspace. \ \ *(Insert macOS Codex Add Project screenshot here)* ### Verifying Session Execution and Script Output 1. In the connected Claude IDE or Codex environment, provide a prompt to create a basic "Hello World" Python script to verify the session.\ \ *(Insert screenshot of Claude Code IDE of prompting to create the hello world in the IDE)* 2. Review and verify the script output directly within the IDE's terminal or shell. \ \ *(Insert screenshot of Claude/Codex terminal output here)* ### Browsing Remote Sandbox Files via System File Explorer 1. In the BlueRock Connector application, select the **Browse Files** option.\ \ *(Insert screenshot of Browse Files in the connector app)* 2. View and interact with the remote files directly within macOS Finder. The `bluedev` container mounts natively on the macOS file system under shared network locations. \ \ *(Insert macOS Finder screenshot here)* ## Maintenance and Troubleshooting ### Exporting Connector Logs To troubleshoot issues, export the application logs directly from the Menu Bar. Click the **BlueRock Connector icon** in the Menu Bar and select **Export Logs...**. Save the generated log file to a preferred location. *(Insert macOS Menu Bar Export Logs screenshot here)* ### Resetting Connector Configuration Select Reset in the Sandbox dialog box, then confirm the prompt to clear the current configuration. *(Insert macOS Reset screenshots here)* ### Handling Session Expiration When a session expires, or after stopping or destroying containers and resetting the configuration, remote network locations automatically unmount from the macOS file system and Docker containers terminate. Complete the Authentication and Sandbox Creation steps again to establish a new session. *(Insert macOS Finder screenshots showing unmounted drives after stopping/destroying here)* # Copy of BlueRock Connector for Claude and Codex IDE BlueRock Connector ships the application for [Windows](#prerequisites) and [macOS](#prerequisites) both, which enables a remote coding workspace from Claude Desktop IDE by launching and managing `bluedev-container` onto the BlueRock Host VM and supports SSH logging to the remote `bluedev-container` using SSO or SSH key-based authentication. #### Setup and Configuration Workflow Follow the complete deployment path below, or jump directly to the required phase: 1. [Prerequisites](#prerequisites) 1. [Software and Client Applications](#software-and-client-applications) 2. [System Requirements](#system-requirements) 3. [Network and Security](#network-and-security) 2. [Installation (Windows)](#installation-windows) 3. [Installation (macOS)](#installation-macos) 4. [Authentication & Enrollment](#authentication-and-enrollment) 1. [SSO (Google OAuth or Microsoft Entra ID)](#sso-google-oauth-or-microsoft-entra-id) 2. [SSH Key](#ssh-key) 5. [Environment Lifecycle Management](#environment-lifecycle-management) 6. [Connecting AI Tools & Workspace Integration](#connecting-ai-tools-and-workspace-integration) 1. [Connecting to Claude Code IDE](#connecting-to-claude-code-ide) 2. [Connecting to Codex](#connecting-to-codex) 3. [Verifying Session Execution & Script Output](#verifying-session-execution-and-script-output) 4. [Browsing Remote Sandbox files via System File Explorer](#browsing-remote-sandbox-files-via-system-file-explorer) 7. [Maintenance & Troubleshooting](#maintenance-and-troubleshooting) ### Prerequisites #### **Software and Client Applications** * **IDEs:** * [Claude Code](https://claude.com/product/claude-code) * [Codex](https://openai.com/codex/) * **BlueRock Connector application:** \ Contact BlueRock support to obtain the installation files. * Windows: `BlueRock_Connector_win64.exe` * macOS: `BlueRock-Connector-notarized.zip` * **OpenSSH Client:** \ The client must be installed and added to the user's PATH (e.g., `C:\Windows\System32\OpenSSH\`). {% hint style="info" %} **Note:** The OpenSSH Client is an optional Windows feature and is frequently removed from hardened corporate images. {% endhint %} #### **System Requirements** * **Operating System (OS) version:** * **Windows:**\ Windows 11 (24H2 or later) is required for file transfers between the laptop and the BlueRock environment. * **macOS:**\ Fully supported for standard Connector features on the latest macOS versions. {% hint style="success" %} **Important:** Install the application strictly in the user's context. Do not install the application machine-wide or via "Run as administrator" (for Windows) or root (for macOS), because the Connector stores identity locally in the user's profile. {% endhint %} #### **Network and Security** * **Virtual Private Network (VPN) connectivity:** \ If the BlueRock instance resides on a private network, each laptop requires active VPN connectivity to reach the instance. * **Endpoint protection:** \ On desktop clients running firewalls or security software, allow port 2259 for inbound connections. The BlueRock Connector application runs a listener service on port 2259 and the loopback interface. The traffic is internal and never leaves the device. ### Installation (Windows) Locate the `BlueRock_Connector_win64.exe` application and double-click to run it. {% hint style="info" icon="notes-sticky" %} **Note:** Windows will display a standard publisher notification warning message because the application is not from Microsoft. Proceed through the prompt to install and run the application. {% endhint %} Access the BlueRock Connector from the **System Tray** as well.
### Installation (macOS) Locate and unzip the `BlueRock-Connector-notarized.zip` to extract the application and double-click to run it.
{% hint style="info" icon="notes-sticky" %} **Note:** When launching the app, macOS may warn that it was downloaded from the internet. Click Open to proceed. ![](/files/iyTS5qTRmhUMNPfunvlT) {% endhint %} Access the BlueRock Connector from the Menu Bar (Status Menus) as well.
{% hint style="success" icon="lightbulb-exclamation-on" %} **Important:** While the installation prompts differ between operating systems, the functionality and performance of BlueRock Connector are the same on both Windows and macOS. {% endhint %} ### Authentication & Enrollment Once the application opens, select the **Set Up Connector** button. Then select **Continue** on the next screen
Log in and enroll using one of two methods: * **Sign in with BlueRock** * **SSH Key**
#### Sign in with BlueRock Run the following command on the instance to enroll the `bluedev-bouncer` before clicking on the **Sign in with BlueRock**: {% code overflow="wrap" %} ```shellscript $ sudo bluedev-bouncer enroll --ca --password ## Enter the BOUNCER_PASSWORD when prompted ``` {% endcode %} 1. Select the **Sign in with BlueRock** option.
2. Provide the bootstrap string URL in the **Sign-in URL** field in the following format: `https://.com#fp=`, and enter the public DNS of the BlueRock host in the **Sandbox host** field. Then click **Sign in.** 3. This action automatically redirects to a web browser for authentication. 4. Complete the sign-in flow in the browser to bring up and authorize. Once successfully authenticated, the following screen appears. ![](/files/tncJD29kw5NAr5sqJVkQ)
#### SSH Key Select the **SSH key** login option.
1. Run the following command on the local machine to get the fingerprint (`SHA256: `): 
ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1
2. Insert the Bootstrap string in the following format: ```shellscript #fp=SHA256: ``` \ For example: ```shellscript 10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU ```
\ **Browse** and select the required **SSH private key,** and select **Install Key**. {% hint style="info" icon="notes-sticky" %} **Note:** Ensure the same SSH key is present in the `.ssh` folder of the instance's Bluedev profile. For that, run the following commands: {% code overflow="wrap" %} ```shellscript ## Switch to root user $ sudo su ## Then switch to bluedev user $ sudo su bluedev # Create the .ssh directory with correct permissions $ mkdir -p ~/.ssh $ chmod 700 ~/.ssh # Add your local public key to authorized_keys $ vi ~/.ssh/authorized_keys # Set secure permissions for the authorized_keys file $ chmod 600 ~/.ssh/authorized_keys ``` {% endcode %} {% endhint %} After this, the app will validate and authenticate based on the SSH Key.
### Environment Lifecycle Management {% hint style="info" icon="notes-sticky" %} **Note:** BlueRock Connector app supports a single container environment only. {% endhint %} * **Creating and Initializing a BlueRock Sandbox**\ Select the **Create sandbox** button to create a sandbox.
* **Monitoring Active Sandbox Status and Session Expiration**\ Verify that it is running by executing `docker ps` directly on your BlueRock instance.
* **Extend session duration**\ In the Create Sandbox dialog box, click **Extend** the signed-in session.
* **Stop Sandbox**: \ Click **Stop Sandbox** to halt your running container. Verifying the container status on the BlueRock instance will confirm that it has stopped.
\ **Restart Container**: \ If an environment has been stopped but not destroyed, a **Start Sandbox** option is available to restart the existing container and preserve its state.\ ![](/files/Icp0slpniJsqKzFhP4s0) * **Destroy Environment**: \ Click **Destroy Sandbox** to completely purge and delete the container instance from the host.
\ It will prompt to confirm destroying the sandbox completely.
### Connecting AI Tools & Workspace Integration #### Connecting to Claude Code IDE To bridge your local Claude IDE environment with the remote container, follow these configuration steps: 1. Select the **Connect Claude** button.
\ For macOS:
2. Select Open Claude Desktop and follow the instructions given on the screen.
\ For macOS:
3. In the Claude IDE: 1. Click on the **Code** menu option. 2. Select **Local**.
3. Select **Add SSH Host**.
4. Enter `cobalt-59` in the **SSH Host** field in the hostname prompt.
5. Click **Add SSH Connection**. Any tasks or development scripts created inside this window will now execute directly inside your active remote `bluedev` Docker container.
{% hint style="info" icon="notes-sticky" %} **Note:** OTEL events are generated by the `blueclaude_sensor` for all the actions done by the coding agent running inside the remote container. {% endhint %} #### Connecting to Codex To bridge your local Codex environment with the remote container, follow these configuration steps: 1. Select the **Connect Codex** button.
2. Follow the instructions given in the dialog screen. Click the link given here. On this screen, a one-time code is also present to enter while setting up an OpenAI account.
3. Authenticate with the OpenAI/ChatGPT account on the default browser.
4. Enter the one-time code and select **Continue**.
5. Upon completion of OpenAI account setup, the BlueRock Bridge app gives a new prompt to **Open Codex Settings**.
6. In Codex, navigate to **Connections** > select **SSH** > click **Add**.
7. Select Remote and click Next.
8. Select **cobalt-59** and click Add.
9. In the New Remote Project pane, select **cobalt-59** from the Remote dropdown and select Add Project.\ ![](/files/WlYg6Vlo01fO8y39dDyF) Once the project connetos successfully, it will be added in the SSH section
Then use it as a project in the Codex workspace.
#### Verifying Session Execution & Script Output In the Claude IDE or Codex, give a prompt to create a hello Python script to verify the session.
Example of verifying the script output in the Claude desktop shell
#### Browsing Remote Sandbox Files via System File Explorer Select Browse Files
In **Windows Explorer,** it will open the files
The bluedev Container mounts on the Windows file system under **Network Location.**
### Maintenance & Troubleshooting * **Resetting BlueRock Connector Configuration:**\ Reset the BlueRock Connector with the **Reset** option in the Sandbox dialog box.
\ Then confirm the reset.
* **Re-authenticating After Reset or Expiration**\ When a session expires or after stopping/destroying containers and resetting configuration, remote network locations automatically unmount, and Docker containers terminate. Re-run Authentication and Sandbox Creation to establish a new session.\ \ On the Windows file system, * After stopping the container
* After destroying the container
* Access the BlueRock Connector from the System Tray as well.
* **Exporting Connector Logs:**\ To troubleshoot issues, export the application logs directly from the system tray. Right-click the **BlueRock Connector** icon in the System Tray (or Menu Bar for macOS) and select **Export Logs...**
# Archive (v26.23.0) 📁 ### Archive (v23.26.0) {% hint style="warning" icon="clipboard-list-check" %} **Important:** The documentation within this section applies specifically to **BlueRock v26.23.0**. For active deployments, navigate to the [current BlueRock v26.23.1 Documentation](/bluedev-container/bluedev-container-introduction). {% endhint %} This section maintains **BlueRock's BlueDev v26.23.0** deployment and configuration guides for backward compatibility and reference. The instructions contained herein do not apply to [**BlueRock's BlueDev v23.26.1** environments](/bluedev-container/bluedev-container-introduction). ### **Available v26.23.0 Documentation** Select a document below to view the v26.24.0 instructions: * [Bluedev/X - VS Code extension (for v26.23.0)](/bluedev-container/archive-v26.23.0/bluedev-x-vs-code-extension-manual-installation) * [BlueRock Bridge Connector (for v26.23.0)](/bluedev-container/archive-v26.23.0/bluerock-bridge-connector-26.23.0) # Bluedev/X - VS Code extension (manual installation) {% hint style="warning" %} **Important:** The **Bluedev/X** extension for VS Code (with manual `.vsix` package installation) supports platform version **26.23.0** only. For environments running platform version **26.23.1** or higher, refer to the [**BlueRock Connector for VS Code (26.23.1** **)** documentation](/bluedev-container/bluerock-connector-for-vs-code) for the updated installation steps. {% endhint %} The Bluedev/X extension authenticates to connect to and execute the BlueRock instance VM from VS Code and to run Sandbox containers from VS Code. This document details the configuration, authentication, and access requirements for the Bluedev/X VS Code extension. ### Prerequisites * [VS Code](https://code.visualstudio.com/) (supported version up to 1.126 or below) * [Docker CLI](https://www.docker.com/products/cli/) * [Dev Containers Extension (from Microsoft VS Code Marketplace)](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) * Bluedev/X VS Code Extension (contact [BlueRock support](https://www.bluerock.io/contact) for the VS Code extension file).
File NameDescription / Target Platform
bluedevx-win32-x64-0.1.0.vsixManual Bluedev/X VS Code extension package for Windows (64-bit architecture).
bluedevx-linux-x64-0.1.0.vsixManual Bluedev/X VS Code extension package for Linux (x64 architecture).
bluedevx-linux-arm64-0.1.0.vsixManual Bluedev/X VS Code extension package for Linux (ARM64 architecture).
bluedevx-darwin-x64-0.1.0.vsixManual Bluedev/X VS Code extension package for macOS (Intel x64 architecture).
bluedevx-darwin-arm64-0.1.0.vsixManual Bluedev/X VS Code extension package for macOS (Apple Silicon / ARM64 architecture).
{% hint style="warning" %} **Windows System Requirement:** The **Bluedev/X extension** on **Windows** depends on the **Microsoft Visual C++ Redistributable** package `VCRUNTIME140.dll`. To ensure smooth execution, install this dependency by running the following command in a terminal before installing the file: ```shellscript winget install Microsoft.VCRedist.2015+.x64 ``` {% endhint %} ### Install .vsix file 1. Open VS Code. 2. Select **Extensions** on the left pane and click the **Install from VISX...** option in the meatball menu.
3. Browse and locate the required `.vsix` file based on the OS and architecture requirements. 4. Restart VS Code to load the extension in the left pane. #### Host Enrollment Run the BlueRock host enrollment directly on the BlueRock instance VM before configuring the BlueRock Connector in VS Code. 1. Access the BlueRock instance VM terminal. 2. Run the following command to enroll the `bluedev-bouncer`: ```shellscript $ sudo bluedev-bouncer enroll --ca --password ``` \ Enter the `BOUNCER_PASSWORD` when prompted. 3. Construct the `` by combining the instance's Public DNS (or IP address) and the appropriate SHA256 fingerprint: ```shellscript https://#fp= ``` 1. **Obtaining the Public DNS / IP Address** Navigate to the respective cloud provider console such as AWS, GCP, or Azure to locate the public address of the BlueRock instance: 2. **Obtaining the Fingerprint (``)** The required fingerprint depends on the chosen authentication method for the workspace: * For BlueRock Identity Service (OIDC): The fingerprint is the SHA-256 hash of the CA certificate. Retrieve this directly from the identity service administrator, or by running `just fingerprint --auto` on the CA host. For more details, refer to the [BlueDev Identity Development Kit](/bluedev-container/bluedev-identity-deployment-kit). * For SSH Key Trust: The fingerprint is the host's SSH key fingerprint. Retrieve it by running the following command on the local machine, replacing `` with the public address obtained above: Bash ```shellscript ssh-keyscan -t ed25519 | ssh-keygen -lf - ``` ### Setting up the Identity Once the Bluedev/X extension is installed, restart VS Code. The extension will load in the left panel. In the extension, select the **Setup** button to configure the BlueRock Instance using either of the following authentication methods. 1. BlueRock identity service 2. SSH key trust #### BlueRock Identity Service 1. Select the **Enroll with identity service...** button.
2. Insert the [**`Bootstrap URL`**](#host-enrollment) : ```shellscript https://#fp= ```
3. Enter the Public DNS or IP Address of the instance and select **Enroll**.
4. Select **Sign-in** and complete the authentication on the browser.
5. After successful authentication, the left panel will show the green icon next to the identity and host.
When authenticated with the identity service, the following files are created on the BlueRock instance: {% code overflow="wrap" %} ```shellscript $ ls -l .config/bluedev/identity/ total 12 -rw------- 1 bluerock bluerock 200 Jun 30 08:56 config.toml -rw------- 1 bluerock bluerock 179 Jun 30 08:57 known_hosts drwx------ 2 bluerock bluerock 4096 Jun 30 08:56 trust $ cat .config/bluedev/identity/config.toml schema_version = 1 service_url = "https://" default_provisioner = "google" tls_trust_mode = "system" [host] address = "0.101.010.0" user = "bluedev" ``` {% endcode %} #### SSH key trust {% hint style="info" icon="notes-sticky" %} **Note**: If **BlueRock Identity Service** is previously configured, then unenroll the bouncer on the host instance first to prevent configuration conflicts before switching to the **SSH Key Trust**: {% code overflow="wrap" %} ```shellscript $ sudo bluedev-bouncer unenroll ``` {% endcode %} {% endhint %} 1. Select the **Set up SSH key Trust...** button to enroll using an existing SSH key.
2. Run the following command on the local machine to get the fingerprint (`SHA256: `): 
ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1
\ Insert the Bootstrap string with the following format ``` #fp=SHA256: ``` \ For example: ``` 10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU ``` 3. Select **Verify**, and once verified, select **I have compared these and they match - Next** button.
4. Select the required key from the local `.ssh` folder or select **Use another key file...** to browse the other keys. Click the **Configure** button.
{% hint style="info" icon="notes-sticky" %} **Note** Ensure the same key is present in the `.ssh` folder of the instance's Bluedev profile. For that, run the following commands:
```shellscript ## Switch to bluedev user $ sudo su bluedev # Create the .ssh directory with correct permissions $ mkdir -p ~/.ssh $ chmod 700 ~/.ssh # Add your local public key to authorized_keys $ vi ~/.ssh/authorized_keys # Set secure permissions for the authorized_keys file $ chmod 600 ~/.ssh/authorized_keys ``` {% endhint %} ### Working with Containers #### Creating a Container using Catalog Once the instance is successfully connected to VS Code, create containers using a pre-built template from the Catalog. These reside at the `/srv/bluedev/catalog` in the BlueRock instance with packages at `/srv/bluedev/packages`. By default, the BlueRock Instance ships the following catalog containers: * **Claude workload sandbox**:\ It’s a template specifically for the Claude IDE for dev containers. * **Fedora - BlueRock dev**:\ It’s a template with a Fedora environment for dev containers. * **Ubuntu - BlueRock dev**:\ It’s a template with an Ubuntu environment for dev containers. To launch them in VS Code, select the **Arrow** icon next to the container template. It will create the Container and connect it automatically. For example, starting an **Ubuntu - BlueRock dev** container
Then the Ubuntu Container will be created on the fly and load in a new VS Code window with all its files. While loading, click the **Connecting to Dev Container (show log)** dialog box
To trust the authors of the files and folders\ ![](/files/55xgKdcWsrSAosazHtXk) Also loads pre-installed packages such as Claude, Gemini, and Codex in the container. Authenticate the package with the required account to run within the container. For example, using Claude to create a dummy shell script in the Ubuntu container.
#### Creating a Container using a Git Repo Select the Repo tab and paste the GitHub/GitLab repo link that has `devcontainer.json` . Click **Warp**; it will fetch the `devcontainer.json`.
For the first time on a new repo, it will prompt to **Trust this repo** to build and create hooks defined in the repo.
Also, provide the Personal Access Token (PAT) of your GitLab/GitHub account once prompted. Select the Container based on the options from the `devcontainer.json` file.
Then it will clone the repo, create the container, and open it in a new VS Code window. ### Manage Containers Select the **Containers** tab to manage the Containers created with different icons. * **Arrow** icon to attach the container in a new VS Code window. * **Pen** icon to rename the container. * **Square** icon to stop the running container. * **Bin** icon to destroy the container and its content from VS Code and the host.
### OTEL Events In CloudWatch, all events are captured for all actions triggered on any Container from VS Code. \ \ For example, the following CloudWatch OTEL log shows an OTEL event of `sensor_startup` lifecycle event emitted by `bluerockd` when the identity monitoring agent binary initializes on a host. {% code overflow="wrap" %} ```json { "body": { "file_path": "/opt/bluerock/bin/blueclaude", "pid": 00000, "principal": "@.com" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "sensor_startup", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 0, "type": "sensor_lifecycle" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
Another example is an OTEL event `claude_hook` event emitted by `bluerockd` when a new Claude session (`SessionStart`) initializes within a user's workspace context. {% code overflow="wrap" %} ```json { "body": { "context": { "process": { "pid": 00000 } }, "cwd": "/home//", "hook_event_name": "SessionStart", "session_id": "xxx-xxx-xxx-xxx-xxx", "source": "startup", "transcript_path": "/home//.claude/projects/xxx/xxx.jsonl" }, "severity_number": 9, "severity_text": "INFO", "attributes": { "component_id": "default/xxx-xxx-xxx-xxx-xxx", "domain": "gyro", "event_name": "claude_hook", "hostid": "ip-", "origin": "blueclaude", "sensor_id": 0000, "source_event_id": 1, "type": "event" }, "scope": { "name": "bluerockd" }, "resource": { "service.name": "bluerock" } } ``` {% endcode %} OTEL event in AWS CloudWatch:
# BlueRock Bridge Connector (26.23.0) {% hint style="warning" %} **Important:** This guide for BlueRock Bridge Connector is for version **26.23.0** only. For environments running platform version **26.23.1**, refer to the [**BlueRock Bridge Connector (26.23.1** **)** documentation](/bluedev-container/bluerock-connector-for-claude-and-codex-ide) for the updated installation steps. {% endhint %} BlueRock Bridge ships the Cobalt application, which enables a remote coding workspace from Claude Desktop IDE by launching and managing `bluedev containers` onto the BlueRock Host VM and supports SSH logging to the remote `bluedev container` using SSO or SSH key-based authentication. ### Pre-requisites * [Claude Code IDE](https://claude.com/product/claude-code) * BlueRock Bridge app `Cobalt` (Contact [BlueRock support](https://www.bluerock.io/contact) to get the Cobalt app) * For Windows: `BlueRock_Cobalt_win64.exe` * For macOS: `BlueRock_Cobalt_macOS.app.zip` ### Installation (Windows) Locate Cobalt's `BlueRock_Cobalt_win64.exe` application and double-click to run it. {% hint style="info" icon="notes-sticky" %} **Note:** Windows will display a standard publisher notification warning message because the application is not from Microsoft. Proceed through the prompt to install and run the application. {% endhint %}
### Authentication & Enrollment Once the application opens, select the **Login** button at the bottom.
You can log in and enroll using one of two methods: * **SSO** (recommended) * **SSH Key**
#### SSO (Google OAuth or Microsoft Entra ID) Run the following command on the instance to enroll the bluedev bouncer before clicking on the **SSO (recommended)**: {% code overflow="wrap" %} ```shellscript $ sudo bluedev-bouncer enroll --ca --password ## Enter the BOUNCER_PASSWORD when prompted ``` {% endcode %} 1. Select the **SSO (Recommended)** option within Cobalt. 2. Provide the bootstrap string URL in the **Bootstrap URL** field.\ In the following format, and click **Sign in**: 
https://<identity-example>.com#fp=<sha256-hex>
3. Click the **Enroll** command inside Cobalt. This action automatically redirects you to your web browser for authentication. 4. Complete the sign-in flow in your browser to bring up and authorize Cobalt. Once Cobalt is successfully authenticated, the following log appears.
#### SSH Trust Auth Select the **SSH key** login option.
1. Run the following command on the local machine to get the fingerprint (`SHA256: `): 
ssh-keyscan -T 10 -t ed25519 <host-ip> | ssh-keygen -lf - 2>&1
2. Insert the Bootstrap string with the following format: ``` #fp=SHA256: ``` \ For example: ``` 10.101.01.101#fp=SHA256:0x0x0xx00xxx0xx0000x000xxx000000xx0x0x00x00xx0x000x0000xx000x00x/mU ``` \ Browse and select the required **SSH private key.**
{% hint style="info" icon="notes-sticky" %} **Note:** Ensure the same SSH key is present in the `.ssh` folder of the instance's Bluedev profile. For that, run the following commands: {% code overflow="wrap" %} ```shellscript ## Switch to bluedev user $ sudo su bluedev # Create the .ssh directory with correct permissions $ mkdir -p ~/.ssh $ chmod 700 ~/.ssh # Add your local public key to authorized_keys $ vi ~/.ssh/authorized_keys # Set secure permissions for the authorized_keys file $ chmod 600 ~/.ssh/authorized_keys ``` {% endcode %} {% endhint %} ### Environment Lifecycle Management {% hint style="info" icon="notes-sticky" %} **Note:** BlueRock Bridge (Cobalt) supports a single container environment only. {% endhint %}
* **Setup Environment**: \ Click **Setup Environment** to pull and spin up the designated Docker container. Verify that it is running by executing `docker ps` directly on your BlueRock instance. * **Stop Environment**: \ Click **Stop Environment** to halt your running container. Verifying the container status on the BlueRock instance will confirm that it has stopped. * **Start Container**: \ If an environment has been stopped but not destroyed, a **Start Container** option will be available to restart the existing container and preserve its state. * **Destroy Environment**: \ Click **Destroy Environment** to completely purge and delete the container instance from the host. #### System Tools
* **Status**: \ Click this button to view diagnostic metadata regarding the active container, including its current state and container ID. * **Show Files**: \ Selecting this option mounts the remote container directory to your local Windows filesystem. This exposes the file structure inside **This PC** as if it were a local directory. * **Clear Log**: \ Functions similarly to a terminal `clear` command. It empties the visual logging output console view within Cobalt. * **Reload**: \ Used when shifting workloads from one BlueRock environment to another (for example, transitioning from Instance A to Instance B). If the dashboard interface hangs on a cached IP address from a previous session after re-enrolling, clicking **Reload** manually refreshes the configuration and pulls down the updated public IP address and configuration settings. The bluedev Container mounts on the Windows file system under **Network Location**:
### Connecting to Claude Code IDE To bridge your local Claude IDE environment with the remote container, follow these configuration steps: 1. Manually open your **Claude ID** application. 2. Click on the **Code** menu option. 3. Select **Local**.
4. Select **Add SSH Host**.
5. Enter `cobalt-59` in the **SSH Host** field in the hostname prompt.
6. Click **Add SSH Connection**. Any tasks or development scripts created inside this window will now execute directly inside your active remote `bluedev` Docker container.
{% hint style="info" icon="notes-sticky" %} **Note:** OTEL events are generated by the `blueclaude_sensor` for all the actions done by the coding agent running inside the remote container. {% endhint %} # BlueRock 26.23.1 (2.6.1) ### Purpose of this Document This is a living document and is updated with each release. This document provides information about the features, enhancements, and known issues in BlueRock Release 26.23.1 (2.6.1). It applies to both new deployments and upgrades from earlier versions. This release focuses on delivering an improved user interface for the BlueRock Connector application and expanding accessibility by making the BlueRock Connector plugins officially available in the VS Code and Cursor marketplaces. #### Revision History | **Release Version** | **Release Date** | | ------------------- | ---------------- | | v26.23.1 (2.6.1) | | ### Supported Platforms / Distributions BlueRock Release 26.23.1 supports deployment across major public cloud providers. The following operating systems have been validated for this release. #### AWS | **Distribution** | **Kernel** | | ----------------------------------- | ---------- | | Amazon Linux 2023 | 6.12.89 | | Amazon Linux 2023 (Kubernetes 1.34) | 6.12.89 | #### GCP | **Distribution** | **Kernel** | | ---------------- | ---------- | | Ubuntu 24.04 | 6.12.89 | #### Azure | **Distribution** | **Kernel** | | ---------------- | ---------- | | Ubuntu 24.04 | 6.12.89 | ## New Features and Enhancements This release introduces targeted improvements to the BlueRock Connector ecosystem and the BlueRock Identity Kit, focusing on user experience, deployment flexibility, and simplified installation workflows. ### BlueRock Connector Application (for Claude and Codex Desktop IDEs) * **Improved User Interface:**\ The BlueRock Connector Application has been updated with a refined and optimized UI. These UX improvements streamline navigation, making it easier for users to manage secure remote development workspaces, configure SSH connections, and oversee file sharing between local systems and remote containers. * **Claude and Codex Integration:**\ Introduces enhanced integration support for Claude and Codex Desktop IDEs, allowing users to seamlessly connect and utilize their AI coding assistants within secure remote environments. * **Flexible Hosting Support:**\ The application now fully supports managing remote development workspaces on both self-hosted BlueRock host deployments and the managed BlueRock PaaS. ### BlueRock Connector Extensions (for VS Code and Cursor) * **Marketplace Availability:**\ To simplify the installation and onboarding process, the BlueRock Connector Extensions are now officially published and available directly from the [Microsoft VS Code](https://marketplace.visualstudio.com/items?itemName=BlueRock.bluerock-connector) and [Cursor extension marketplaces](https://open-vsx.org/extension/BlueRock/bluerock-connector). Automatic updates are fully supported. * **Client-Side Docker Independence:**\ The BlueRock Connector Extensions for VS Code and Cursor now utilize the standard Remote-SSH extension, completely removing the requirement for any Docker dependency on the client machine. ### BlueRock Identity Kit Improvements * **Private Deployment Support:** \ The identity kit now supports fully private deployments, ensuring that the identity enrollment URL is exposed exclusively to internal users. * **Simplified Provisioning:** \ Deploying the BlueRock Identity server is now significantly easier with a new Terraform script, which provides out-of-the-box support for AWS, GCP, and Azure environments. * **Certificate Lifecycle Stability:** \ Applied vital stability fixes addressing edge cases around certificate expiration and the automated refresh workflow. # Licensing ### Overview This page lists the third-party and open-source software components included in **BlueRock Release 26.23.1 (2.6.1)**, along with their associated license information. The licensing information on this page is specific to **BlueRock Release 26.23.1 (2.6.1)**. The list of components, versions, and licenses may change in future releases. *** ### Release Information | Property | Value | | --------- | -------------------------------- | | Release | BlueRock Release 26.23.1 (2.6.1) | | Generated | 2026-07-31T09:27:18.072448 | ### Open Source Components This release includes **193 third-party and open-source software components**. The following table lists each component together with its corresponding license and version. | **Name** | **License** | **Version** | | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | [@anthropic-ai/sdk](https://github.com/anthropics/anthropic-sdk-typescript) | [MIT](https://github.com/anthropics/anthropic-sdk-typescript/blob/HEAD/LICENSE-MIT) | 0.96.0 | | [@google/generative-ai](https://github.com/google/generative-ai-js) | [Apache-2.0](https://github.com/google/generative-ai-js/blob/HEAD/LICENSE-APACHE) | 0.24.1 | | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) | [MIT](https://github.com/modelcontextprotocol/typescript-sdk/blob/HEAD/LICENSE-MIT) | 1.7.0 | | [@napi-rs/cli](https://github.com/napi-rs/napi-rs) | [MIT](https://github.com/napi-rs/napi-rs/blob/HEAD/LICENSE-MIT) | 2.18.4 | | [@types/escape-html](https://github.com/DefinitelyTyped/DefinitelyTyped) | [MIT](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/LICENSE-MIT) | 1.0.4 | | [@types/mocha](https://github.com/DefinitelyTyped/DefinitelyTyped) | [MIT](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/LICENSE-MIT) | 10.0.0 | | [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped) | [MIT](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/LICENSE-MIT) | 20.16.0 | | [@types/vscode](https://github.com/DefinitelyTyped/DefinitelyTyped) | [MIT](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/LICENSE-MIT) | 1.85.0 | | [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint) | [MIT](https://github.com/typescript-eslint/typescript-eslint/blob/HEAD/LICENSE-MIT) | 8.59.1 | | [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint) | [MIT](https://github.com/typescript-eslint/typescript-eslint/blob/HEAD/LICENSE-MIT) | 8.59.1 | | [@vscode/test-electron](https://github.com/Microsoft/vscode-test) | [MIT](https://github.com/Microsoft/vscode-test/blob/HEAD/LICENSE-MIT) | 2.4.0 | | [annotated-types](https://github.com/annotated-types/annotated-types) | [MIT License](https://github.com/annotated-types/annotated-types/blob/HEAD/LICENSE) | 0.7.0 | | [annotated-types](https://github.com/annotated-types/annotated-types) | [MIT](https://github.com/annotated-types/annotated-types/blob/HEAD/LICENSE-MIT) | 0.8.0 | | [anyhow](https://github.com/dtolnay/anyhow) | [Apache-2.0](https://github.com/dtolnay/anyhow/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/dtolnay/anyhow/blob/HEAD/LICENSE-MIT) | 1.0.104 | | [appdirs](http://github.com/ActiveState/appdirs) | [MIT](http://github.com/ActiveState/appdirs/blob/HEAD/LICENSE-MIT) | 1.4.4 | | [async-trait](https://github.com/dtolnay/async-trait) | [Apache-2.0](https://github.com/dtolnay/async-trait/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/dtolnay/async-trait/blob/HEAD/LICENSE-MIT) | 0.1.89 | | [aws-config](https://github.com/smithy-lang/smithy-rs) | [Apache-2.0](https://github.com/smithy-lang/smithy-rs/blob/HEAD/LICENSE-APACHE) | 1.10.1 | | [aws-credential-types](https://github.com/smithy-lang/smithy-rs) | [Apache-2.0](https://github.com/smithy-lang/smithy-rs/blob/HEAD/LICENSE-APACHE) | 1.3.0 | | [aws-sdk-s3](https://github.com/awslabs/aws-sdk-rust) | [Apache-2.0](https://github.com/awslabs/aws-sdk-rust/blob/HEAD/LICENSE-APACHE) | 1.140.0 | | [aws-sdk-sts](https://github.com/awslabs/aws-sdk-rust) | [Apache-2.0](https://github.com/awslabs/aws-sdk-rust/blob/HEAD/LICENSE-APACHE) | 1.110.0 | | [base64](https://github.com/marshallpierce/rust-base64) | [Apache-2.0](https://github.com/marshallpierce/rust-base64/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/marshallpierce/rust-base64/blob/HEAD/LICENSE-MIT) | 0.22.1 | | [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/bs4/) | [MIT License](https://spdx.org/licenses/MIT.html) | 4.15.0 | | [bs4](https://pypi.org/project/bs4) | [MIT License](https://pypi.org/project/bs4#license) | 0.0.2 | | [bytecode](https://pypi.org/project/bytecode) | [MIT License](https://pypi.org/project/bytecode#license) | 0.18.1 | | [bytes](https://github.com/tokio-rs/bytes) | [MIT](https://github.com/tokio-rs/bytes/blob/HEAD/LICENSE-MIT) | 1.11.1 | | [bytes](https://github.com/tokio-rs/bytes) | [MIT](https://github.com/tokio-rs/bytes/blob/HEAD/LICENSE-MIT) | 1.12.0 | | [cached-property](https://github.com/pydanny/cached-property) | [BSD](https://github.com/pydanny/cached-property/blob/HEAD/LICENSE) | 2.0.1 | | [certifi](https://github.com/certifi/python-certifi) | [MPL-2.0](https://github.com/certifi/python-certifi/blob/HEAD/LICENSE-MPL) | 2026.7.22 | | [cffi](http://cffi.readthedocs.org/) | [MIT License](https://spdx.org/licenses/MIT.html) | 1.17.1 | | [cffi](https://pypi.org/project/cffi) | [MIT-0](https://pypi.org/project/cffi#license) | 2.1.0 | | [ch.qos.logback:logback-classic](https://mvnrepository.com/artifact/ch.qos.logback/logback-classic) | [Eclipse Public License - v 1.0](https://spdx.org/licenses/Eclipse%20Public%20License%20-%20v%201.0.html) AND [GNU Lesser General Public License](https://spdx.org/licenses/GNU%20Lesser%20General%20Public%20License.html) | 1.5.15 | | [charset-normalizer](https://pypi.org/project/charset-normalizer) | [MIT](https://pypi.org/project/charset-normalizer#license) | 3.4.9 | | [chrono](https://github.com/chronotope/chrono) | [Apache-2.0](https://github.com/chronotope/chrono/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/chronotope/chrono/blob/HEAD/LICENSE-MIT) | 0.4.44 | | [clang](http://clang.llvm.org/) | [Apache-2.0 with LLVM exception](https://spdx.org/licenses/Apache-2.0-WITH-LLVM-exception.html) | 21.1.7 | | [clap](https://github.com/clap-rs/clap) | [Apache-2.0](https://github.com/clap-rs/clap/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/clap-rs/clap/blob/HEAD/LICENSE-MIT) | 4.6.1 | | [com.fasterxml.jackson.core:jackson-databind](https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 2.19.1 | | [commons-io:commons-io](https://mvnrepository.com/artifact/commons-io/commons-io) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 2.19.0 | | [cryptography](https://github.com/pyca/cryptography) | [Apache Software License; BSD License](https://github.com/pyca/cryptography/blob/HEAD/LICENSE) | 43.0.3 | | [cryptography](https://pypi.org/project/cryptography) | [Apache-2.0](https://pypi.org/project/cryptography#license), [BSD-3-Clause](https://pypi.org/project/cryptography#license) | 50.0.0 | | [cssselect](https://github.com/scrapy/cssselect) | [BSD-3-Clause](https://github.com/scrapy/cssselect/blob/HEAD/LICENSE-BSD) | 1.5.0 | | [dirs](https://github.com/soc/dirs-rs) | [Apache-2.0](https://github.com/soc/dirs-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/soc/dirs-rs/blob/HEAD/LICENSE-MIT) | 5.0.1 | | [dirs](https://github.com/soc/dirs-rs) | [Apache-2.0](https://github.com/soc/dirs-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/soc/dirs-rs/blob/HEAD/LICENSE-MIT) | 6.0.0 | | [eframe](https://github.com/emilk/egui/tree/main/crates/eframe) | [Apache-2.0](https://github.com/emilk/egui/tree/main/crates/eframe/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/emilk/egui/tree/main/crates/eframe/blob/HEAD/LICENSE-MIT) | 0.34.2 | | [egui\_extras](https://github.com/emilk/egui) | [Apache-2.0](https://github.com/emilk/egui/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/emilk/egui/blob/HEAD/LICENSE-MIT) | 0.34.2 | | [egui\_kittest](https://github.com/emilk/egui) | [Apache-2.0](https://github.com/emilk/egui/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/emilk/egui/blob/HEAD/LICENSE-MIT) | 0.34.2 | | [embed-resource](https://github.com/nabijaczleweli/rust-embed-resource) | [MIT](https://github.com/nabijaczleweli/rust-embed-resource/blob/HEAD/LICENSE-MIT) | 3.0.9 | | [esbuild](https://github.com/evanw/esbuild) | [MIT](https://github.com/evanw/esbuild/blob/HEAD/LICENSE-MIT) | 0.28.0 | | [escape-html](https://github.com/component/escape-html) | [MIT](https://github.com/component/escape-html/blob/HEAD/LICENSE-MIT) | 1.0.3 | | [eslint](https://github.com/eslint/eslint) | [MIT](https://github.com/eslint/eslint/blob/HEAD/LICENSE-MIT) | 10.3.0 | | [fake-useragent](https://github.com/fake-useragent/fake-useragent) | [Apache-2.0](https://github.com/fake-useragent/fake-useragent/blob/HEAD/LICENSE-APACHE) | 2.2.0 | | [fdt](https://github.com/molejar/pyFDT) | [Apache 2.0](https://github.com/molejar/pyFDT/blob/HEAD/LICENSE-APACHE) | 0.3.3 | | [flate2](https://github.com/rust-lang/flate2-rs) | [Apache-2.0](https://github.com/rust-lang/flate2-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/rust-lang/flate2-rs/blob/HEAD/LICENSE-MIT) | 1.1.9 | | [fs2](https://github.com/danburkert/fs2-rs) | [Apache-2.0](https://github.com/danburkert/fs2-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/danburkert/fs2-rs/blob/HEAD/LICENSE-MIT) | 0.4.3 | | [futures](https://github.com/rust-lang/futures-rs) | [Apache-2.0](https://github.com/rust-lang/futures-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/rust-lang/futures-rs/blob/HEAD/LICENSE-MIT) | 0.3.32 | | [github.com/aws/aws-sdk-go-v2/config](https://github.com/aws/aws-sdk-go-v2/config) | [Apache-2.0](https://github.com/aws/aws-sdk-go-v2/config/blob/HEAD/LICENSE-APACHE) | v1.32.3 | | [github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs](https://github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs) | [Apache-2.0](https://github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs/blob/HEAD/LICENSE-APACHE) | v1.62.0 | | [github.com/spf13/cobra](https://github.com/spf13/cobra) | [Apache-2.0](https://github.com/spf13/cobra/blob/HEAD/LICENSE-APACHE) | v1.8.1 | | [glob](https://github.com/isaacs/node-glob) | [BlueOak-1.0.0](https://github.com/isaacs/node-glob/blob/HEAD/LICENSE) | 13.0.0 | | [go.uber.org/zap](https://pkg.go.dev/go.uber.org/zap) | [MIT](https://spdx.org/licenses/MIT.html) | v1.27.1 | | [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) | [MIT](https://spdx.org/licenses/MIT.html) AND [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) | v3.0.1 | | [http](https://github.com/hyperium/http) | [Apache-2.0](https://github.com/hyperium/http/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/hyperium/http/blob/HEAD/LICENSE-MIT) | 1.4.0 | | [httparse](https://github.com/seanmonstar/httparse) | [Apache-2.0](https://github.com/seanmonstar/httparse/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/seanmonstar/httparse/blob/HEAD/LICENSE-MIT) | 1.10.1 | | [idna](https://github.com/kjd/idna) | [BSD-3-Clause](https://github.com/kjd/idna/blob/HEAD/LICENSE-BSD) | 3.18 | | [importlib-metadata](https://github.com/python/importlib_metadata) | [Apache-2.0](https://github.com/python/importlib_metadata/blob/HEAD/LICENSE-APACHE) | 9.0.0 | | [iniconfig](https://github.com/pytest-dev/iniconfig) | [MIT](https://github.com/pytest-dev/iniconfig/blob/HEAD/LICENSE-MIT) | 2.1.0 | | [io.modelcontextprotocol.sdk:mcp](https://mvnrepository.com/artifact/io.modelcontextprotocol.sdk/mcp) | [MIT License](http://www.opensource.org/licenses/mit-license.php) | 0.14.1 | | [io.projectreactor:reactor-core](https://mvnrepository.com/artifact/io.projectreactor/reactor-core) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.6.10 | | [io.projectreactor:reactor-test](https://mvnrepository.com/artifact/io.projectreactor/reactor-test) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.6.10 | | [io.quarkiverse.mcp:quarkus-mcp-server-sse](https://mvnrepository.com/artifact/io.quarkiverse.mcp/quarkus-mcp-server-sse) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 1.5.0 | | [io.quarkus:quarkus-junit5](https://mvnrepository.com/artifact/io.quarkus/quarkus-junit5) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.26.0 | | [io.quarkus:quarkus-qute](https://mvnrepository.com/artifact/io.quarkus/quarkus-qute) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.26.0 | | [io.quarkus:quarkus-rest-client-jackson](https://mvnrepository.com/artifact/io.quarkus/quarkus-rest-client-jackson) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.26.0 | | [javax.servlet.jsp:javax.servlet.jsp-api](https://mvnrepository.com/artifact/javax.servlet.jsp/javax.servlet.jsp-api) | [CDDL + GPLv2 with classpath exception](https://bluerocksecurity.atlassian.net/wiki/spaces/EN/pages/2652536834/BRU+Open+Source+Components+-+bru-release-26.23.1#) | 2.3.3 | | [javax.servlet:javax.servlet-api](https://mvnrepository.com/artifact/javax.servlet/javax.servlet-api) | [CDDL + GPLv2 with classpath exception](https://glassfish.dev.java.net/nonav/public/CDDL+GPL.html) | 3.1.0 | | [json-with-comments](https://github.com/n-takumasa/json-with-comments) | [MIT License](https://github.com/n-takumasa/json-with-comments/blob/HEAD/LICENSE) | 1.2.10 | | [json5](https://github.com/callum-oakley/json5-rs) | [ISC](https://github.com/callum-oakley/json5-rs/blob/HEAD/LICENSE-ISC) | 0.4.1 | | [libfuzzer-sys](https://github.com/rust-fuzz/libfuzzer) | [(Apache-2.0](https://github.com/rust-fuzz/libfuzzer/blob/HEAD/LICENSE), [MIT)](https://github.com/rust-fuzz/libfuzzer/blob/HEAD/LICENSE), [NCSA](https://github.com/rust-fuzz/libfuzzer/blob/HEAD/LICENSE) | 0.4.13 | | [lxml](https://github.com/lxml/lxml) | [BSD-3-Clause](https://github.com/lxml/lxml/blob/HEAD/LICENSE-BSD) | 6.1.1 | | [markdown](https://github.com/Python-Markdown/markdown) | [BSD-3-Clause](https://github.com/Python-Markdown/markdown/blob/HEAD/LICENSE-BSD) | 3.10.3 | | [mocha](https://github.com/mochajs/mocha) | [MIT](https://github.com/mochajs/mocha/blob/HEAD/LICENSE-MIT) | 11.1.0 | | [napi](https://github.com/napi-rs/napi-rs) | [MIT](https://github.com/napi-rs/napi-rs/blob/HEAD/LICENSE-MIT) | 2.16.17 | | [napi-build](https://github.com/napi-rs/napi-rs) | [MIT](https://github.com/napi-rs/napi-rs/blob/HEAD/LICENSE-MIT) | 2.3.2 | | [napi-derive](https://github.com/napi-rs/napi-rs) | [MIT](https://github.com/napi-rs/napi-rs/blob/HEAD/LICENSE-MIT) | 2.16.13 | | [net.bytebuddy:byte-buddy](https://mvnrepository.com/artifact/net.bytebuddy/byte-buddy) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 1.17.6 | | [netaddr](https://github.com/netaddr/netaddr/) | [BSD License](https://github.com/netaddr/netaddr/blob/HEAD/LICENSE) | 1.3.0 | | [nix](https://github.com/nix-rust/nix) | [MIT](https://github.com/nix-rust/nix/blob/HEAD/LICENSE-MIT) | 0.29.0 | | [nix](https://github.com/nix-rust/nix) | [MIT](https://github.com/nix-rust/nix/blob/HEAD/LICENSE-MIT) | 0.31.3 | | [openai](https://github.com/openai/openai-node) | [Apache-2.0](https://github.com/openai/openai-node/blob/HEAD/LICENSE-APACHE) | 6.37.0 | | [org.apache.commons:commons-compress](https://mvnrepository.com/artifact/org.apache.commons/commons-compress) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 1.27.1 | | [org.apache.logging.log4j:log4j-core](https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-core) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 2.20.0 | | [org.apache.struts:struts2-convention-plugin](https://mvnrepository.com/artifact/org.apache.struts/struts2-convention-plugin) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 6.3.0.1 | | [org.apache.struts:struts2-core](https://mvnrepository.com/artifact/org.apache.struts/struts2-core) | [The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 6.3.0.1 | | [org.apache.taglibs:taglibs-standard-impl](https://mvnrepository.com/artifact/org.apache.taglibs/taglibs-standard-impl) | [The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt) | 1.2.5 | | [org.assertj:assertj-core](https://mvnrepository.com/artifact/org.assertj/assertj-core) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) | 3.24.2 | | [org.junit.jupiter:junit-jupiter](https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter) | [Eclipse Public License v2.0](https://www.eclipse.org/legal/epl-v20.html) | 5.9.2 | | [org.projectlombok:lombok](https://mvnrepository.com/artifact/org.projectlombok/lombok) | [The MIT License](https://projectlombok.org/LICENSE) | 1.18.34 | | [org.slf4j:slf4j-api](https://mvnrepository.com/artifact/org.slf4j/slf4j-api) | [MIT License](http://www.opensource.org/licenses/mit-license.php) | 2.0.16 | | [org.springframework.boot:spring-boot-starter-security](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-security) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 3.3.4 | | [org.springframework.boot:spring-boot-starter-test](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-test) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 3.3.4 | | [org.springframework.boot:spring-boot-starter-webflux](https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-webflux) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 3.3.4 | | [org.springframework.security:spring-security-core](https://mvnrepository.com/artifact/org.springframework.security/spring-security-core) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 6.3.3 | | [org.springframework.security:spring-security-test](https://mvnrepository.com/artifact/org.springframework.security/spring-security-test) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 6.3.3 | | [org.springframework.security:spring-security-web](https://mvnrepository.com/artifact/org.springframework.security/spring-security-web) | [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) | 6.3.3 | | [packaging](https://github.com/pypa/packaging) | [Apache Software License; BSD License](https://github.com/pypa/packaging/blob/HEAD/LICENSE) | 25.0 | | [parse](https://pypi.org/project/parse) | [MIT](https://pypi.org/project/parse#license) | 1.22.1 | | [percent-encoding](https://github.com/servo/rust-url/) | [Apache-2.0](https://github.com/servo/rust-url/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/servo/rust-url/blob/HEAD/LICENSE-MIT) | 2.3.2 | | [pluggy](https://github.com/pytest-dev/pluggy) | [MIT License](https://github.com/pytest-dev/pluggy/blob/HEAD/LICENSE) | 1.5.0 | | [prettier](https://github.com/prettier/prettier) | [MIT](https://github.com/prettier/prettier/blob/HEAD/LICENSE-MIT) | 3.8.3 | | [proptest](https://github.com/proptest-rs/proptest) | [Apache-2.0](https://github.com/proptest-rs/proptest/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/proptest-rs/proptest/blob/HEAD/LICENSE-MIT) | 1.11.0 | | [prost](https://github.com/tokio-rs/prost) | [Apache-2.0](https://github.com/tokio-rs/prost/blob/HEAD/LICENSE-APACHE) | 0.13.5 | | [prost-build](https://github.com/tokio-rs/prost) | [Apache-2.0](https://github.com/tokio-rs/prost/blob/HEAD/LICENSE-APACHE) | 0.13.5 | | [protoc-bin-vendored](https://github.com/stepancheg/rust-protoc-bin-vendored/) | [MIT](https://github.com/stepancheg/rust-protoc-bin-vendored/blob/HEAD/LICENSE-MIT) | 3.2.0 | | [pycparser](https://github.com/eliben/pycparser) | [BSD License](https://github.com/eliben/pycparser/blob/HEAD/LICENSE) | 2.22 | | [pycparser](https://github.com/eliben/pycparser) | [BSD-3-Clause](https://github.com/eliben/pycparser/blob/HEAD/LICENSE-BSD) | 3.0 | | [pydantic](https://github.com/pydantic/pydantic) | [MIT](https://github.com/pydantic/pydantic/blob/HEAD/LICENSE-MIT) | 2.13.4 | | [pydantic](https://github.com/pydantic/pydantic) | [MIT](https://github.com/pydantic/pydantic/blob/HEAD/LICENSE-MIT) | 2.9.2 | | [pydantic-core](https://github.com/pydantic/pydantic/tree/main/pydantic-core) | [MIT](https://github.com/pydantic/pydantic/tree/main/pydantic-core/blob/HEAD/LICENSE-MIT) | 2.47.0 | | [pydantic\_core](https://github.com/pydantic/pydantic-core) | [MIT License](https://github.com/pydantic/pydantic-core/blob/HEAD/LICENSE) | 2.23.4 | | [pyee](https://github.com/jfhbrook/pyee) | [MIT](https://github.com/jfhbrook/pyee/blob/HEAD/LICENSE-MIT) | 13.0.1 | | [pyelftools](https://github.com/eliben/pyelftools.git) | [Public domain](https://github.com/eliben/pyelftools/blob/HEAD/LICENSE) | 0.33 | | [pylspci](https://tildegit.org/lucidiot/pylspci) | [GNU General Public License 3](https://spdx.org/licenses/GPL-3.0-only.html) | 0.4.3 | | [pyOpenSSL](https://pyopenssl.org/) | [Apache Software License](https://spdx.org/licenses/Apache-2.0.html) | 24.2.1 | | [pyopenssl](https://github.com/pyca/pyopenssl) | [Apache License, Version 2.0](https://github.com/pyca/pyopenssl/blob/HEAD/LICENSE) | 26.3.0 | | [pyppeteer](https://github.com/pyppeteer/pyppeteer) | [MIT](https://github.com/pyppeteer/pyppeteer/blob/HEAD/LICENSE-MIT) | 2.0.0 | | [pyquery](https://github.com/gawel/pyquery) | [BSD](https://github.com/gawel/pyquery/blob/HEAD/LICENSE) | 2.1.0 | | [pytest](https://docs.pytest.org/en/latest/) | [MIT License](https://spdx.org/licenses/MIT.html) | 8.3.5 | | [pytest](https://github.com/pytest-dev/pytest) | [MIT](https://github.com/pytest-dev/pytest/blob/HEAD/LICENSE-MIT) | 9.1.1 | | [python-dateutil](https://github.com/dateutil/dateutil) | [Dual License](https://github.com/dateutil/dateutil/blob/HEAD/LICENSE) | 2.9.0.post0 | | [PyYAML](https://pyyaml.org/) | [MIT License](https://spdx.org/licenses/MIT.html) | 6.0.2 | | [pyyaml](https://pyyaml.org/) | [MIT](https://spdx.org/licenses/MIT.html) | 6.0.3 | | [rand](https://github.com/rust-random/rand) | [Apache-2.0](https://github.com/rust-random/rand/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/rust-random/rand/blob/HEAD/LICENSE-MIT) | 0.10.1 | | [rand](https://github.com/rust-random/rand) | [Apache-2.0](https://github.com/rust-random/rand/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/rust-random/rand/blob/HEAD/LICENSE-MIT) | 0.8.6 | | [rand](https://github.com/rust-random/rand) | [Apache-2.0](https://github.com/rust-random/rand/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/rust-random/rand/blob/HEAD/LICENSE-MIT) | 0.9.4 | | [rapidfuzz](https://github.com/rapidfuzz/RapidFuzz.git) | [MIT](https://github.com/rapidfuzz/RapidFuzz/blob/HEAD/LICENSE-MIT) | 3.14.5 | | [requests](https://github.com/psf/requests) | [Apache-2.0](https://github.com/psf/requests/blob/HEAD/LICENSE-APACHE) | 2.34.2 | | [requests-html](https://github.com/kennethreitz/requests-html) | [MIT](https://github.com/kennethreitz/requests-html/blob/HEAD/LICENSE-MIT) | 0.10.0 | | [reqwest](https://github.com/seanmonstar/reqwest) | [Apache-2.0](https://github.com/seanmonstar/reqwest/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/seanmonstar/reqwest/blob/HEAD/LICENSE-MIT) | 0.11.27 | | [reqwest](https://github.com/seanmonstar/reqwest) | [Apache-2.0](https://github.com/seanmonstar/reqwest/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/seanmonstar/reqwest/blob/HEAD/LICENSE-MIT) | 0.12.28 | | [rfd](https://github.com/PolyMeilex/rfd) | [MIT](https://github.com/PolyMeilex/rfd/blob/HEAD/LICENSE-MIT) | 0.17.2 | | [russh](https://github.com/warp-tech/russh) | [Apache-2.0](https://github.com/warp-tech/russh/blob/HEAD/LICENSE-APACHE) | 0.61.2 | | [rustix](https://github.com/bytecodealliance/rustix) | [Apache-2.0](https://github.com/bytecodealliance/rustix/blob/HEAD/LICENSE-APACHE), [Apache-2.0 WITH LLVM-exception](https://github.com/bytecodealliance/rustix/blob/HEAD/LICENSE), [MIT](https://github.com/bytecodealliance/rustix/blob/HEAD/LICENSE-MIT) | 1.1.4 | | [rustls](https://github.com/rustls/rustls) | [Apache-2.0](https://github.com/rustls/rustls/blob/HEAD/LICENSE-APACHE), [ISC](https://github.com/rustls/rustls/blob/HEAD/LICENSE-ISC), [MIT](https://github.com/rustls/rustls/blob/HEAD/LICENSE-MIT) | 0.23.40 | | [serde](https://github.com/serde-rs/serde) | [Apache-2.0](https://github.com/serde-rs/serde/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/serde-rs/serde/blob/HEAD/LICENSE-MIT) | 1.0.228 | | [serde](https://github.com/serde-rs/serde) | [Apache-2.0](https://github.com/serde-rs/serde/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/serde-rs/serde/blob/HEAD/LICENSE-MIT) | 1.0.229 | | [serde\_json](https://github.com/serde-rs/json) | [Apache-2.0](https://github.com/serde-rs/json/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/serde-rs/json/blob/HEAD/LICENSE-MIT) | 1.0.149 | | [serde\_json](https://github.com/serde-rs/json) | [Apache-2.0](https://github.com/serde-rs/json/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/serde-rs/json/blob/HEAD/LICENSE-MIT) | 1.0.150 | | [serde\_json](https://github.com/serde-rs/json) | [Apache-2.0](https://github.com/serde-rs/json/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/serde-rs/json/blob/HEAD/LICENSE-MIT) | 1.0.151 | | [serde\_yaml\_bw](https://github.com/bourumir-wyngs/serde-yaml-bw) | [Apache-2.0](https://github.com/bourumir-wyngs/serde-yaml-bw/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/bourumir-wyngs/serde-yaml-bw/blob/HEAD/LICENSE-MIT) | 2.5.6 | | [sha2](https://github.com/RustCrypto/hashes) | [Apache-2.0](https://github.com/RustCrypto/hashes/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/RustCrypto/hashes/blob/HEAD/LICENSE-MIT) | 0.10.9 | | [sha2](https://github.com/RustCrypto/hashes) | [Apache-2.0](https://github.com/RustCrypto/hashes/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/RustCrypto/hashes/blob/HEAD/LICENSE-MIT) | 0.11.0 | | [shlex](https://github.com/comex/rust-shlex) | [Apache-2.0](https://github.com/comex/rust-shlex/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/comex/rust-shlex/blob/HEAD/LICENSE-MIT) | 1.3.0 | | [shlex](https://github.com/comex/rust-shlex) | [Apache-2.0](https://github.com/comex/rust-shlex/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/comex/rust-shlex/blob/HEAD/LICENSE-MIT) | 2.0.1 | | [signal-hook](https://github.com/vorner/signal-hook) | [Apache-2.0](https://github.com/vorner/signal-hook/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/vorner/signal-hook/blob/HEAD/LICENSE-MIT) | 0.3.18 | | [six](https://github.com/benjaminp/six) | [MIT](https://github.com/benjaminp/six/blob/HEAD/LICENSE-MIT) | 1.17.0 | | [soupsieve](https://github.com/facelessuser/soupsieve) | [MIT](https://github.com/facelessuser/soupsieve/blob/HEAD/LICENSE-MIT) | 2.9.1 | | [Sphinx](https://www.sphinx-doc.org/) | [BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html) | 8.2.3 | | [sphinx-jsonschema](https://github.com/lnoor/sphinx-jsonschema) | [GNU General Public License v3 (GPLv3)](https://github.com/lnoor/sphinx-jsonschema/blob/HEAD/LICENSE) | 1.19.1 | | [sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/) | [MIT License](https://spdx.org/licenses/MIT.html) | 3.0.2 | | [sphinxcontrib-confluencebuilder](https://github.com/sphinx-contrib/confluencebuilder) | [BSD License](https://github.com/sphinx-contrib/confluencebuilder/blob/HEAD/LICENSE) | 2.12.0 | | [ssh-key](https://github.com/RustCrypto/SSH/tree/master/ssh-key) | [Apache-2.0](https://github.com/RustCrypto/SSH/tree/master/ssh-key/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/RustCrypto/SSH/tree/master/ssh-key/blob/HEAD/LICENSE-MIT) | 0.6.7 | | [ssh-key](https://github.com/RustCrypto/SSH) | [Apache-2.0](https://github.com/RustCrypto/SSH/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/RustCrypto/SSH/blob/HEAD/LICENSE-MIT) | 0.7.0-rc.10 | | [syslog](https://github.com/Geal/rust-syslog) | [MIT](https://github.com/Geal/rust-syslog/blob/HEAD/LICENSE-MIT) | 6.1.1 | | [tempfile](https://github.com/Stebalien/tempfile) | [Apache-2.0](https://github.com/Stebalien/tempfile/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/Stebalien/tempfile/blob/HEAD/LICENSE-MIT) | 3.27.0 | | [thiserror](https://github.com/dtolnay/thiserror) | [Apache-2.0](https://github.com/dtolnay/thiserror/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/dtolnay/thiserror/blob/HEAD/LICENSE-MIT) | 1.0.69 | | [thiserror](https://github.com/dtolnay/thiserror) | [Apache-2.0](https://github.com/dtolnay/thiserror/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/dtolnay/thiserror/blob/HEAD/LICENSE-MIT) | 2.0.18 | | [time](https://github.com/time-rs/time) | [Apache-2.0](https://github.com/time-rs/time/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/time-rs/time/blob/HEAD/LICENSE-MIT) | 0.3.47 | | [tokio](https://github.com/tokio-rs/tokio) | [MIT](https://github.com/tokio-rs/tokio/blob/HEAD/LICENSE-MIT) | 1.52.2 | | [tokio](https://github.com/tokio-rs/tokio) | [MIT](https://github.com/tokio-rs/tokio/blob/HEAD/LICENSE-MIT) | 1.52.3 | | [tokio](https://github.com/tokio-rs/tokio) | [MIT](https://github.com/tokio-rs/tokio/blob/HEAD/LICENSE-MIT) | 1.53.1 | | [tokio-stream](https://github.com/tokio-rs/tokio) | [MIT](https://github.com/tokio-rs/tokio/blob/HEAD/LICENSE-MIT) | 0.1.18 | | [tokio-util](https://github.com/tokio-rs/tokio) | [MIT](https://github.com/tokio-rs/tokio/blob/HEAD/LICENSE-MIT) | 0.7.18 | | [toml](https://github.com/toml-rs/toml) | [Apache-2.0](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-MIT) | 0.8.23 | | [toml](https://github.com/toml-rs/toml) | [Apache-2.0](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-MIT) | 1.1.2+spec-1.1.0 | | [toml\_edit](https://github.com/toml-rs/toml) | [Apache-2.0](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/toml-rs/toml/blob/HEAD/LICENSE-MIT) | 0.22.27 | | [tqdm](https://pypi.org/project/tqdm) | [MPL-2.0](https://pypi.org/project/tqdm#license) AND [MIT](https://pypi.org/project/tqdm#license) | 4.70.0 | | [tracing](https://github.com/tokio-rs/tracing) | [MIT](https://github.com/tokio-rs/tracing/blob/HEAD/LICENSE-MIT) | 0.1.44 | | [tracing-subscriber](https://github.com/tokio-rs/tracing) | [MIT](https://github.com/tokio-rs/tracing/blob/HEAD/LICENSE-MIT) | 0.3.23 | | [typescript](https://github.com/microsoft/TypeScript) | [Apache-2.0](https://github.com/microsoft/TypeScript/blob/HEAD/LICENSE-APACHE) | 5.6.0 | | [typing-extensions](https://github.com/python/typing_extensions) | [PSF-2.0](https://github.com/python/typing_extensions/blob/HEAD/LICENSE) | 4.16.0 | | [typing\_extensions](https://github.com/python/typing_extensions) | [Python Software Foundation License](https://github.com/python/typing_extensions/blob/HEAD/LICENSE) | 4.12.2 | | [typing\_extensions](https://github.com/python/typing_extensions) | [PSF-2.0](https://github.com/python/typing_extensions/blob/HEAD/LICENSE) | 4.16.0 | | [ulid](https://github.com/dylanhart/ulid-rs) | [MIT](https://github.com/dylanhart/ulid-rs/blob/HEAD/LICENSE-MIT) | 1.2.1 | | [urllib3](https://pypi.org/project/urllib3) | [MIT](https://pypi.org/project/urllib3#license) | 2.7.0 | | [uuid](https://github.com/uuid-rs/uuid) | [Apache-2.0](https://github.com/uuid-rs/uuid/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/uuid-rs/uuid/blob/HEAD/LICENSE-MIT) | 1.23.1 | | [vitest](https://github.com/vitest-dev/vitest) | [MIT](https://github.com/vitest-dev/vitest/blob/HEAD/LICENSE-MIT) | 4.1.7 | | [w3lib](https://github.com/scrapy/w3lib) | [BSD-3-Clause](https://github.com/scrapy/w3lib/blob/HEAD/LICENSE-BSD) | 2.4.1 | | [webbrowser](https://github.com/amodm/webbrowser-rs) | [Apache-2.0](https://github.com/amodm/webbrowser-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/amodm/webbrowser-rs/blob/HEAD/LICENSE-MIT) | 1.2.1 | | [websockets](https://github.com/python-websockets/websockets) | [BSD-3-Clause](https://github.com/python-websockets/websockets/blob/HEAD/LICENSE-BSD) | 17.0.1 | | [wiremock](https://github.com/LukeMathWalker/wiremock-rs) | [Apache-2.0](https://github.com/LukeMathWalker/wiremock-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/LukeMathWalker/wiremock-rs/blob/HEAD/LICENSE-MIT) | 0.6.5 | | [wrapt](https://github.com/GrahamDumpleton/wrapt) | [BSD-2-Clause](https://github.com/GrahamDumpleton/wrapt/blob/HEAD/LICENSE-BSD) | 2.3.0 | | [xz2](https://github.com/alexcrichton/xz2-rs) | [Apache-2.0](https://github.com/alexcrichton/xz2-rs/blob/HEAD/LICENSE-APACHE), [MIT](https://github.com/alexcrichton/xz2-rs/blob/HEAD/LICENSE-MIT) | 0.1.7 | | [zipp](https://github.com/jaraco/zipp) | [MIT](https://github.com/jaraco/zipp/blob/HEAD/LICENSE-MIT) | 4.1.0 | | [zstd](https://github.com/gyscos/zstd-rs) | [MIT](https://github.com/gyscos/zstd-rs/blob/HEAD/LICENSE-MIT) | 0.13.3 | {% hint style="info" icon="notes-sticky" %} **Note:** * This licensing information applies only to **BlueRock Release 26.23.1 (2.6.1)**. * Third-party components and license information may change in future releases. {% endhint %} # BlueRock 26.23.0 #### Purpose of this Document This is a living document and is updated with each release. This document provides information about the features, enhancements, and known issues in **BlueRock Release 26.23.0**. It applies to both new deployments and upgrades from earlier versions. This release focuses on simplifying BlueRock Runtime deployment and configuration, improving sandbox networking and container runtime capabilities, expanding observability for AI coding agents, and introducing secure remote development workflows through the Bluedev VSCode Extension and Cobalt application. These enhancements improve deployment, security, and developer productivity while providing greater visibility into AI-assisted development activities. *** #### Revision History | Release Version | Release Date | | --------------- | ------------ | | V26.23.0 | | #### Supported Platforms / Distributions BlueRock Release 26.23.0 supports deployment across major public cloud providers. The following operating systems have been validated for this release. **AWS** | Distribution | Kernel | | ----------------------------------- | ------- | | Amazon Linux 2023 | 6.12.89 | | Amazon Linux 2023 (Kubernetes 1.34) | 6.12.89 | **GCP** | Distribution | Kernel | | ------------ | ------- | | Ubuntu 24.04 | 6.12.89 | **Azure** | Distribution | Kernel | | ------------ | ------- | | Ubuntu 24.04 | 6.12.89 | *** ### New Features and Enhancements This release introduces significant improvements to BlueRock Runtime deployment, sandbox networking, AI coding agent observability, and remote development workflows. Enhancements include a simplified runtime configuration model, expanded container networking capabilities, new observability sensors for AI coding assistants, and improved authentication support for remote development environments. *** #### Ease of BlueRock Runtime Deployment and Configuration The BlueRock Runtime now runs as the **bluerockd** system daemon, simplifying deployment and lifecycle management. Key enhancements include: * BlueRock Runtime is managed through the **bluerockd** system service. * Runtime configuration is centralized in `/etc/bluerock/bluerockd.toml`. * Configuration is organized into dedicated Runtime, Policy, and OTLP sections. * Policy configuration supports downloading signed policy blobs and signature verification using public keys. * OTLP event streaming is configurable, with events written to `/var/log/bluerockd/otel-event.logs` by default. *** #### BlueRock Sandbox Improvements BlueRock Sandbox has been enhanced to improve container execution and network isolation. Key enhancements include: * Support for **containerd-shim** to execute Docker images using standard Docker commands. * Ability to bind sandbox containers to Docker networks. * Network policy enforcement for ingress and egress traffic. * Expanded Seccomp policy support, including: * System call filtering * Suspicious syscall detection * Executable memory protection * File access protection * Socket monitoring * Connection monitoring * File deletion monitoring * Sensitive file access protection * Process guard enforcement If no network policy is configured, sandbox containers allow all outbound traffic while blocking all inbound traffic by default. *** #### Enhanced Network Firewall Management Network firewall configuration has been enhanced with the following behavior: * A single network firewall configuration can be associated with either standalone applications or container-based applications. * Updating network firewall policies requires restarting the `bluerockd` service. * Standalone sandbox applications automatically inherit configured firewall policies. * Docker network creation is recommended before launching standalone sandbox applications when shared networking is required. *** #### Observability for AI Coding Agents BlueRock introduces new runtime observability capabilities for AI coding assistants. The AI coding agent sensor is enabled by default and provides runtime visibility into AI coding agent activities. When AI coding agents are executed within a BlueRock Sandbox, sandbox policies are enforced. Supported AI coding agents include: * Claude * Cursor * Gemini * Codex *** #### Bluedev VSCode Extension The Bluedev VSCode Extension enables developers to securely launch remote development workspaces on BlueRock virtual machines directly from Visual Studio Code. **Key capabilities include:** * Launch secure remote development containers from a catalog of available Docker images * Clone Git repositories into remote development containers * Manage remote containers with attach, rename, pause, and destroy operations * Support for running Claude and Cursor AI coding agents inside remote development containers * SSH connectivity to remote Bluedev containers using either SSO or SSH key-based authentication * Single Sign-On (SSO) using Google Auth and Microsoft Entra ID * Support for multiple remote development workspaces *** #### Cobalt Application for Claude Desktop The Cobalt application enables Claude Desktop users to create and manage secure remote development workspaces hosted on BlueRock virtual machines. Once the remote development container is launched, Claude Desktop IDE users can run their Claude Code session securely inside the remote container. Features include: * Remote Bluedev container management * Secure SSH connectivity to remote Bluedev containers using Single Sign-On (SSO) or SSH key-based authentication * File sharing between the local filesystem and the remote container filesystem * Supported on Windows and MacOS *** #### Bluedev User Identity Management BlueRock now supports enhanced user authentication for remote development environments. BlueRock VM includes the StepCA server package and a deployment script to configure the StepCA server with Google Auth and Microsoft Entra ID provisioners for Single Sign-On (SSO). Supported authentication methods include: * **Single Sign-On (SSO)** using **Google Auth** and **Microsoft Entra ID** * SSH key-based authentication *** #### LLM Cost Monitoring BlueRock introduces LLM Cost Monitoring capabilities that provide visibility into Large Language Model (LLM) usage, estimated token consumption, and operational cost trends across AI agents and applications. Key capabilities include: • Monitor estimated LLM token usage and operational costs across AI workloads.\ • Analyze usage by agent, model, framework, team, user, application, and tag.\ • Review input and output token distribution and request outcomes.\ • Monitor containment activity and cost-related policy alerts.\ • Analyze Agent-to-Model (A2M) metrics, including call rate, latency, model utilization, and framework distribution. *** ### Resolved Issues No resolved issues in this release. *** ### Known Issues #### BC-3371 Restarting bluerockd disrupts existing sensor connections Restarting the BlueRock Control Plane service disconnects existing BlueRock sensor connections, interrupting active AI agent and MCP applications. **Workaround** Restart all affected AI agent and MCP applications after restarting the `bluerockd` service. *** #### BA-2927 SSH connection failure on macOS Monterey SSH connections to BlueRock hosts using the Bluedev VSCode Extension or the Cobalt application may fail on **macOS Monterey** because of domain socket path length limitations. **Workaround** No workaround is currently available. *** #### BC-3381 Source-address ingress firewall rules not enforced Source-address-based ingress firewall rules are not correctly enforced for BlueRock Sandbox containers. **Workaround** No workaround is currently available. *** # Licensing ### Overview This page lists the third-party and open-source software components included in **BlueRock Release 26.23.0**, along with their associated license information. The licensing information on this page is specific to **BlueRock Release 26.23.0**. The list of components, versions, and licenses may change in future releases. *** ### Release Information | Property | Value | | --------- | -------------------------- | | Release | BlueRock Release 26.23.0 | | Generated | 2026-07-14T06:27:18.072448 | ### Open Source Components This release includes **190 third-party and open-source software components**. The following table lists each component together with its corresponding license and version.
NameLicenseVersion
@anthropic-ai/sdkMIT0.96.0
@google/generative-aiApache-2.00.24.1
@modelcontextprotocol/sdkMIT1.7.0
@napi-rs/cliMIT2.18.4
@types/escape-htmlMIT1.0.4
@types/mochaMIT10.0.0
@types/nodeMIT20.16.0
@types/vscodeMIT1.85.0
@typescript-eslint/eslint-pluginMIT8.59.1
@typescript-eslint/parserMIT8.59.1
@vscode/test-electronMIT2.4.0
annotated-typesMIT License0.7.0
anyhowApache-2.0 OR MIT1.0.102
anyhowApache-2.0 OR MIT1.0.103
appdirsMIT1.4.4
async-traitApache-2.0 OR MIT0.1.89
aws-configApache-2.01.9.0
aws-credential-typesApache-2.01.3.0
aws-sdk-s3Apache-2.01.138.0
aws-sdk-stsApache-2.01.108.0
base64Apache-2.0 OR MIT0.22.1
beautifulsoup4MIT License4.15.0
bs4MIT License0.0.2
bytecodeMIT License0.18.1
bytesMIT1.11.1
bytesMIT1.12.0
cached-propertyBSD2.0.1
certifiMPL-2.02026.6.17
cffiMIT License1.17.1
cffiMIT-02.1.0
ch.qos.logback:logback-classicEclipse Public License - v 1.0 AND GNU Lesser General Public License1.5.15
charset-normalizerMIT3.4.9
chronoApache-2.0 OR MIT0.4.44
clangApache-2.0 with LLVM exception21.1.7
clapApache-2.0 OR MIT4.6.1
com.fasterxml.jackson.core:jackson-databindThe Apache Software License, Version 2.02.19.1
commons-io:commons-ioApache-2.02.19.0
cryptographyApache Software License; BSD License43.0.3
cryptographyApache-2.0 OR BSD-3-Clause49.0.0
cssselectBSD-3-Clause1.4.0
dirsApache-2.0 OR MIT5.0.1
dirsApache-2.0 OR MIT6.0.0
eframeApache-2.0 OR MIT0.34.2
egui_extrasApache-2.0 OR MIT0.34.2
egui_kittestApache-2.0 OR MIT0.34.2
embed-resourceMIT3.0.9
esbuildMIT0.28.0
escape-htmlMIT1.0.3
eslintMIT10.3.0
fake-useragentApache-2.02.2.0
fdtApache 2.00.3.3
flate2Apache-2.0 OR MIT1.1.9
fs2Apache-2.0 OR MIT0.4.3
futuresApache-2.0 OR MIT0.3.32
github.com/aws/aws-sdk-go-v2/configApache-2.0v1.32.3
github.com/aws/aws-sdk-go-v2/service/cloudwatchlogsApache-2.0v1.62.0
github.com/spf13/cobraApache-2.0v1.8.1
globBlueOak-1.0.013.0.0
go.uber.org/zapMITv1.27.1
gopkg.in/yaml.v3MIT AND Apache-2.0v3.0.1
httpApache-2.0 OR MIT1.4.0
httparseApache-2.0 OR MIT1.10.1
idnaBSD-3-Clause3.18
importlib-metadataApache-2.09.0.0
iniconfigMIT2.1.0
io.modelcontextprotocol.sdk:mcpMIT License0.14.1
io.projectreactor:reactor-coreApache License, Version 2.03.6.10
io.projectreactor:reactor-testApache License, Version 2.03.6.10
io.quarkiverse.mcp:quarkus-mcp-server-sseApache License, Version 2.01.5.0
io.quarkus:quarkus-junit5The Apache Software License, Version 2.03.26.0
io.quarkus:quarkus-quteThe Apache Software License, Version 2.03.26.0
io.quarkus:quarkus-rest-client-jacksonThe Apache Software License, Version 2.03.26.0
javax.servlet.jsp:javax.servlet.jsp-apiCDDL + GPLv2 with classpath exception2.3.3
javax.servlet:javax.servlet-apiCDDL + GPLv2 with classpath exception3.1.0
json-with-commentsMIT License1.2.10
json5ISC0.4.1
libfuzzer-sys(Apache-2.0 OR MIT) OR NCSA0.4.13
lxmlBSD-3-Clause6.1.1
markdownBSD-3-Clause3.10.2
mochaMIT11.1.0
napiMIT2.16.17
napi-buildMIT2.3.2
napi-deriveMIT2.16.13
net.bytebuddy:byte-buddyApache License, Version 2.01.17.6
netaddrBSD License1.3.0
nixMIT0.29.0
nixMIT0.31.3
openaiApache-2.06.37.0
org.apache.commons:commons-compressApache-2.01.27.1
org.apache.logging.log4j:log4j-coreApache License, Version 2.02.20.0
org.apache.struts:struts2-convention-pluginThe Apache Software License, Version 2.06.3.0.1
org.apache.struts:struts2-coreThe Apache Software License, Version 2.06.3.0.1
org.apache.taglibs:taglibs-standard-implThe Apache Software License, Version 2.01.2.5
org.assertj:assertj-coreApache License, Version 2.03.24.2
org.junit.jupiter:junit-jupiterEclipse Public License v2.05.9.2
org.projectlombok:lombokThe MIT License1.18.34
org.slf4j:slf4j-apiMIT License2.0.16
org.springframework.boot:spring-boot-starter-securityApache License, Version 2.03.3.4
org.springframework.boot:spring-boot-starter-testApache License, Version 2.03.3.4
org.springframework.boot:spring-boot-starter-webfluxApache License, Version 2.03.3.4
org.springframework.security:spring-security-coreApache License, Version 2.06.3.3
org.springframework.security:spring-security-testApache License, Version 2.06.3.3
org.springframework.security:spring-security-webApache License, Version 2.06.3.3
packagingApache Software License; BSD License25.0
parseMIT1.22.1
percent-encodingApache-2.0 OR MIT2.3.2
pluggyMIT License1.5.0
prettierMIT3.8.3
proptestApache-2.0 OR MIT1.11.0
prostApache-2.00.13.5
prost-buildApache-2.00.13.5
protoc-bin-vendoredMIT3.2.0
pycparserBSD License2.22
pycparserBSD-3-Clause3.0
pydanticMIT2.13.4
pydanticMIT2.9.2
pydantic-coreMIT2.47.0
pydantic_coreMIT License2.23.4
pyeeMIT13.0.1
pyelftoolsPublic domain0.33
pylspciGNU General Public License 30.4.3
pyOpenSSLApache Software License24.2.1
pyopensslApache License, Version 2.026.3.0
pyppeteerMIT2.0.0
pyqueryBSD2.0.1
pytestMIT License8.3.5
pytestMIT9.1.1
python-dateutilDual License2.9.0.post0
PyYAMLMIT License6.0.2
pyyamlMIT6.0.3
randApache-2.0 OR MIT0.10.1
randApache-2.0 OR MIT0.8.6
randApache-2.0 OR MIT0.9.4
rapidfuzzMIT3.14.5
requestsApache-2.02.34.2
requests-htmlMIT0.10.0
reqwestApache-2.0 OR MIT0.11.27
reqwestApache-2.0 OR MIT0.12.28
rfdMIT0.17.2
russhApache-2.00.61.2
rustixApache-2.0 OR Apache-2.0 WITH LLVM-exception OR MIT1.1.4
rustlsApache-2.0 OR ISC OR MIT0.23.40
serdeApache-2.0 OR MIT1.0.228
serde_jsonApache-2.0 OR MIT1.0.149
serde_jsonApache-2.0 OR MIT1.0.150
serde_yaml_bwApache-2.0 OR MIT2.5.6
sha2Apache-2.0 OR MIT0.10.9
sha2Apache-2.0 OR MIT0.11.0
shlexApache-2.0 OR MIT1.3.0
shlexApache-2.0 OR MIT2.0.1
signal-hookApache-2.0 OR MIT0.3.18
sixMIT1.17.0
soupsieveMIT2.8.4
SphinxBSD-2-Clause8.2.3
sphinx-jsonschemaGNU General Public License v3 (GPLv3)1.19.1
sphinx-rtd-themeMIT License3.0.2
sphinxcontrib-confluencebuilderBSD License2.12.0
ssh-keyApache-2.0 OR MIT0.6.7
ssh-keyApache-2.0 OR MIT0.7.0-rc.10
syslogMIT6.1.1
tempfileApache-2.0 OR MIT3.27.0
thiserrorApache-2.0 OR MIT1.0.69
thiserrorApache-2.0 OR MIT2.0.18
timeApache-2.0 OR MIT0.3.47
tokioMIT1.52.2
tokioMIT1.52.3
tokio-streamMIT0.1.18
tokio-utilMIT0.7.18
tomlApache-2.0 OR MIT0.8.23
tomlApache-2.0 OR MIT1.1.2+spec-1.1.0
toml_editApache-2.0 OR MIT0.22.27
tqdmMPL-2.0 AND MIT4.68.4
tracingMIT0.1.44
tracing-subscriberMIT0.3.23
typescriptApache-2.05.6.0
typing-extensionsPSF-2.04.16.0
typing_extensionsPython Software Foundation License4.12.2
typing_extensionsPSF-2.04.16.0
ulidMIT1.2.1
urllib3MIT2.7.0
uuidApache-2.0 OR MIT1.23.1
vitestMIT4.1.7
w3libBSD-3-Clause2.4.1
webbrowserApache-2.0 OR MIT1.2.1
websocketsBSD-3-Clause16.1
wiremockApache-2.0 OR MIT0.6.5
wraptBSD-2-Clause2.2.2
xz2Apache-2.0 OR MIT0.1.7
zippMIT4.1.0
zstdMIT0.13.3
### Notes * This licensing information applies only to **BlueRock Release 26.23.0**. * Third-party components and license information may change in future releases. # BlueRock 26.08.0 ## Purpose of this Document This is a living document and is updated with each release. This document provides information about the features, enhancements, and known issues in the **BlueRock Release 26.08.0**. It applies to both new deployments and upgrades from earlier versions. This focuses on expanding observability capabilities for AI agent frameworks, improving container runtime support, and enhancing the overall developer experience for MCP-based applications. These updates enable better visibility into runtime behavior and simplify deployment and execution of agentic workloads and improve the workflow for running MCP applications within the BlueRock instance. *** ## Revision History | Release Version | Release Date | | --------------- | ------------ | | V26.08.0 | | *** ## **Supported Platforms / Distributions** **AWS** BlueRock Release 26.08.0 supports deployment on AWS EC2 instances. Following Linux distributions are supported on EC2 and EKS deployments: *** **Supported Linux Distributions**
Linux DistributionOS VersionKernel Version
Amazon Linux 20232023.10.202601206.12.63
Bottlerocketv1.54.06.12.63
*** **GCP** BlueRock Release 26.08.0 supports deployment on GCP environments. #### Supported Linux Distributions | Linux Distribution | OS Version | Kernel Version | | ------------------ | ---------- | -------------- | | Ubuntu | 24.04 | NA | *** ## New Features and Enhancements This release introduces expanded platform support with GCP compatibility using Ubuntu distribution, along with enhanced observability and policy enforcement across AI agent workflows. It includes new sensors for JavaScript/TypeScript, LangChain, CrewAI, A2A, and LLM model interactions, as well as improvements to the BlueRock Sandbox with container runtime support and simplified execution. *** #### **\[BC-3044]** New JS Sensor enables runtime observability and policy enforcement for JavaScript/TypeScript MCP applications. Introduces a Node.js sensor that enables BlueRock observability for JavaScript and TypeScript MCP client and server applications with support for: * Monitoring MCP session, tool/resource and prompt usage * Enforcing protection policies to guard against unsafe executions * Capturing runtime execution events **Sample policy configuration:** ``` "js_sensor": { "mcp": { "enable": true, "remediate": false } } ``` For all sensors, the feature is enabled for observability in the default policy loaded on to the system (applicable for both Free edition and Full edition). *** #### \[BC-3665] LangChain sensor enables observability for LangChain Agent Applications Introduces a LangChain sensor that enables observability for AI Agent applications built using Python LangChain SDK. **Policy Configuration to enable sensor:** ``` { "langchain": { "enable": true } } ``` *** #### **\[BC-3266] CrewAI sensor enables observability for CrewAI agent workflows** Introduces a CrewAI sensor that enables observability for AI agent workflows built using the CrewAI framework. **Policy Configuration to enable sensor:** ``` { "crewai": { "enable": true } } ``` *** #### **\[BC-3188] Enhanced version of BlueRock Sandbox with container runtime support** Introduces an enhanced version of BlueRock Sandbox with simplified command arguments and improved support for running AI agentic applications and MCP server applications using container images. **Key enhancements include:** * Simplified command arguments for improved ease of use * Automatic mounting of required host volumes in read-only mode * Support for passing required environment variables during sandbox execution * Option to enable or disable namespace isolation * Support for wildcard characters in policy configuration (exec) **Container Support:** * Enables deployment and execution of AI agentic applications and MCP server applications as Docker containers *** #### \[BA-2762, BA-2763, BA-2764] **A2A sensor enables observability and policy enforcement for Python-based A2A applications** Introduces an A2A sensor for Python applications built using SDKs that support the Agent-to-Agent (A2A) protocol. The sensor provides observability into agent-to-agent communication by capturing runtime events such as agent card requests and server interactions during A2A workflows. It also enables policy enforcement on agent capabilities advertised via Agent Cards, with built-in protections to detect unsafe patterns in: * Agent card name * Agent card description * Agent skill descriptions *** #### \[BA-2796, BA-2797, BA-2798, BA-2799] **LLM Model sensor enables observability for LLM interactions in Python AI Agent applications** Introduces an LLM Model sensor that provides observability into interactions with Large Language Models (LLMs) across supported Python SDKs, including OpenAI and GoogleAI. The sensor captures runtime events for model invocations, including request payloads (prompts and parameters) and model responses, providing visibility into application-level interactions with LLMs. This enables traceability of model usage within AI agent workflows, including prompt execution, tool invocations, and model responses with full traceability. *** ## Resolved Issues No resolved issues in this release. *** ## Known Issues The following Known issues are present in this release. #### **\[BC-3256] Client-side tool deny policies do not remove denied tools during discovery with JavaScript MCP sensors** When client-side tool deny policies are configured, denied tools are not removed from the tool discovery (`tool/list`) response when using JavaScript or TypeScript MCP sensors. As a result, denied tools continue to appear in the discovered tool list, and associated remediation actions and violation events are not triggered. This issue affects JavaScript and TypeScript MCP servers. Python MCP sensors enforce deny policies correctly. **Workaround:** Recommended to use Server side tool filter policy. **Policy Example:** ``` "js_sensor": { "mcp": { "enable": true, "remediate": true, "server": { "enable": true, "remediate": true, "tools": { "FileAgentServer": { "deny_list": ["remove_file"] } } } } } ``` *** #### **\[BC-3252, BC-3249, BC-3282] Limitations in BlueRock Sandbox Networking and Execution** The following limitations are observed when using the **BlueRock Sandbox environment**. #### \[BC-3252] Restart Failure After Network Policy Update After updating a network policy, restarting an Agent or MCP application container in the BlueRock Sandbox may fail to start. **Workaround:**\ Restart the BlueRock control plane service, then restart the application container. ``` sudo systemctl restart uc-docker.service ``` *** #### \[BC-3249] CLI Argument Syntax Limitation The BlueRock Sandbox CLI does not support space-separated syntax for the `--network-config` argument. * **Not Supported:** ``` --network-config ``` * **Supported:** ``` --network-config= ``` **Workaround:**\ Use the equals (`=`) syntax when passing the `--network-config` argument. *** #### \[BC-3282] Host Binding Does Not Expose Application Ports When using network configuration with ingress rules in the Sandbox, application ports are not exposed to the host layer as expected. * Applications are not accessible via host IP and port * External connections fail When the sandbox is run without network configuration ingress rules, ports are correctly exposed. **Workaround:**\ Avoid configuring ingress rules. Run the sandbox without network configuration. *** #### **\[BC-3260] Python application execution hangs after repeated Ctrl+C termination when using bluepython module** When running Python applications using the BlueRock Python sensor (`bluepython module`), repeated termination of the application using `Ctrl+C` (typically after 2–3 runs) may result in subsequent executions hanging. This problem is a rare occurrence. **Workaround:** Restart the BlueRock Control Plane service: ``` sudo systemctl restart uc-docker.service ``` *** # Appendix This section contains reference configurations, scripts, and examples used across the documentation. These can be used as supporting material while following the steps described in the main sections. ## **MCP Client Script (Python)** ```shellscript import argparse import asyncio import json from fastmcp import Client from fastmcp.client.auth import BearerAuth async def main(): parser = argparse.ArgumentParser(description="Generic MCP Test Client") parser.add_argument("--mcp_server", required=True, help="URL (http/sse) or local server python script path(stdio)") parser.add_argument("--mcp_auth_token", help="Optional bearer token for authentication") subparsers = parser.add_subparsers(dest="action_cmd", required=True) tool_parser = subparsers.add_parser("tools") tool_parser.add_argument("--list", action="store_true") tool_parser.add_argument("--tool_cmd") tool_parser.add_argument("--tool_args", default="{}") res_parser = subparsers.add_parser("resources") res_parser.add_argument("--list", action="store_true") res_parser.add_argument("--resource_uri") prompt_parser = subparsers.add_parser("prompts") prompt_parser.add_argument("--list", action="store_true") prompt_parser.add_argument("--prompt_name") prompt_parser.add_argument("--prompt_args", default="{}") args = parser.parse_args() if args.mcp_server.startswith(("http://", "https://")): transport_type = "sse" if "/sse" in args.mcp_server else "http" server_config = { "transport": transport_type, "url": args.mcp_server } if args.mcp_auth_token: server_config["auth"] = BearerAuth(token=f"{args.mcp_auth_token}") else: server_config = { "transport": "stdio", "command": "node" if args.mcp_server.endswith(".js") else "python", "args": [args.mcp_server] } config = {"mcpServers": {"target_server": server_config}} client = Client(config) async with client: if args.action_cmd == "tools": if args.list: tools = await client.list_tools() print(f"Available Tools: {tools}") elif args.tool_cmd: result = await client.call_tool(args.tool_cmd, json.loads(args.tool_args)) print(f"Tool Result: {result}") elif args.action_cmd == "resources": if args.list: resources = await client.list_resources() print(f"Available Resources: {resources}") elif args.resource_uri: print(await client.read_resource(args.resource_uri)) elif args.action_cmd == "prompts": if args.list: prompts = await client.list_prompts() print(f"Available Prompts: {prompts}") elif args.prompt_name: messages = await client.get_prompt(args.prompt_name, json.loads(args.prompt_args)) print(messages) if __name__ == "__main__": asyncio.run(main()) ``` Source: [MCP Sensor Observability](broken://pages/b3mDcpONsSZH3cMufRuL#mcp-execution) *** ## **MCP File Server (HTTP) — Python** ```shellscript from fastmcp import FastMCP from fastmcp.server.auth.providers.jwt import StaticTokenVerifier import os verifier = StaticTokenVerifier(tokens={"dev-token": {"client_id": "dev-client", "scopes": ["read", "write"]}}, required_scopes=["read"]) mcp = FastMCP("FileServer", auth=verifier) WORKING_DIR = os.path.abspath("./mcp-data") os.makedirs(WORKING_DIR, exist_ok=True) @mcp.resource("config://app-settings") def get_config() -> str: return "Mode: Development; Version: 1.0.0; Allowed-Extensions: .txt, .md" @mcp.resource("folder://explorer") def list_files() -> str: files = os.listdir(WORKING_DIR) return "\n".join(files) if files else "The directory is empty." @mcp.tool() def write_file(filename: str, content: str) -> str: path = os.path.join(WORKING_DIR, filename) with open(path, "w") as f: f.write(content) return f"File '{filename}' written successfully." @mcp.tool() def remove_file(filename: str) -> str: file_path = os.path.join(WORKING_DIR, filename) extension = os.path.splitext(filename)[1] if extension.lower() == ".tmp": if os.path.exists(file_path): os.remove(file_path) return f"File '{filename}' removed successfully." else: return f"File '{filename}' not present." else: return f"File '{filename}' is not a tmp file." @mcp.prompt() def useful_helper_prompt(lang: str) -> str: return f"You are an expert in {lang}. create or update file using {lang} code." if __name__ == "__main__": mcp.run(transport="http", host="0.0.0.0", port=8001, log_level="DEBUG") ``` Source: [MCP Sensor Observability](broken://pages/b3mDcpONsSZH3cMufRuL#mcp-execution) *** ## **MCP File Server (STDIO) — Python** ```shellscript from mcp.server.fastmcp import FastMCP import os mcp = FastMCP("FileServer") WORKING_DIR = os.path.abspath("./mcp-data") os.makedirs(WORKING_DIR, exist_ok=True) @mcp.resource("config://app-settings") def get_config() -> str: return "Mode: Development; Version: 1.0.0; Allowed-Extensions: .txt, .md" @mcp.resource("folder://explorer") def list_files() -> str: files = os.listdir(WORKING_DIR) return "\n".join(files) if files else "The directory is empty." @mcp.tool() def write_file(filename: str, content: str) -> str: path = os.path.join(WORKING_DIR, filename) with open(path, "w") as f: f.write(content) return f"File '{filename}' written successfully." @mcp.tool() def remove_file(filename: str) -> str: file_path = os.path.join(WORKING_DIR, filename) extension = os.path.splitext(filename)[1] if extension.lower() == ".tmp": if os.path.exists(file_path): os.remove(file_path) return f"File '{filename}' removed successfully." else: return f"File '{filename}' not present." else: return f"File '{filename}' is not a tmp file." @mcp.prompt() def useful_helper_prompt(lang: str) -> str: return f"You are an expert in {lang}. create or update file using {lang} code." if __name__ == "__main__": mcp.run() ``` Source: [MCP Sensor Observability](broken://pages/b3mDcpONsSZH3cMufRuL#mcp-execution) ## MCP Client Script — JavaScript ```shellscript #!/usr/bin/env node import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; import yargs from "yargs"; import { hideBin } from "yargs/helpers"; async function main() { const argv = yargs(hideBin(process.argv)) .option("mcp_server", { type: "string", demandOption: true, describe: "URL (http/sse) or local server script path (stdio)", }) .option("mcp_auth_token", { type: "string", describe: "Optional bearer token for authentication", }) .command("tools", "Tool operations", (yargs) => { yargs .option("list", { type: "boolean", describe: "List available tools" }) .option("tool_cmd", { type: "string", describe: "Name of the tool to call" }) .option("tool_args", { type: "string", default: "{}", describe: "JSON string of tool arguments" }); }) .command("resources", "Resource operations", (yargs) => { yargs .option("list", { type: "boolean", describe: "List available resources" }) .option("resource_uri", { type: "string", describe: "URI of the resource to read" }); }) .command("prompts", "Prompt operations", (yargs) => { yargs .option("list", { type: "boolean", describe: "List available prompts" }) .option("prompt_name", { type: "string", describe: "Name of the prompt to fetch" }) .option("prompt_args", { type: "string", default: "{}", describe: "JSON string of prompt arguments" }); }) .demandCommand(1, "You must specify an action: tools, resources, or prompts") .help() .argv; const actionCmd = argv._[0]; const mcpServer = argv.mcp_server; const authToken = argv.mcp_auth_token; let transport; if (mcpServer.startsWith("http://") || mcpServer.startsWith("https://")) { const url = new URL(mcpServer); const authProvider = authToken ? { async tokens() { return { access_token: authToken, token_type: "Bearer" }; }, } : undefined; if (mcpServer.includes("/sse")) { transport = new SSEClientTransport(url, { authProvider }); } else { transport = new StreamableHTTPClientTransport(url, { authProvider }); } } else { const command = mcpServer.endsWith(".js") ? "node" : "python"; transport = new StdioClientTransport({ command, args: [mcpServer] }); } const client = new Client( { name: "mcp-client", version: "1.0.0" }, { capabilities: {} } ); await client.connect(transport); try { if (actionCmd === "tools") { if (argv.list) { const result = await client.listTools(); console.log("Available Tools:", JSON.stringify(result.tools, null, 2)); } else if (argv.tool_cmd) { const toolArgs = JSON.parse(argv.tool_args); const result = await client.callTool({ name: argv.tool_cmd, arguments: toolArgs }); console.log("Tool Result:", JSON.stringify(result, null, 2)); } } else if (actionCmd === "resources") { if (argv.list) { const result = await client.listResources(); console.log("Available Resources:", JSON.stringify(result.resources, null, 2)); } else if (argv.resource_uri) { const result = await client.readResource({ uri: argv.resource_uri }); console.log("Resource Content:", JSON.stringify(result, null, 2)); } } else if (actionCmd === "prompts") { if (argv.list) { const result = await client.listPrompts(); console.log("Available Prompts:", JSON.stringify(result.prompts, null, 2)); } else if (argv.prompt_name) { const promptArgs = JSON.parse(argv.prompt_args); const result = await client.getPrompt({ name: argv.prompt_name, arguments: promptArgs }); console.log("Prompt Output:", JSON.stringify(result, null, 2)); } } } finally { await client.close(); } } main().catch(console.error); ``` ## MCP File Server — JavaScript ```shellscript import express from "express"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { z } from "zod"; import fs from "fs/promises"; import fsSync from "fs"; import path from "path"; const WORKING_DIR = path.resolve("./mcp-data"); fsSync.mkdirSync(WORKING_DIR, { recursive: true }); const validTokens = { "dev-token": { client_id: "dev-client", scopes: ["read", "write"] }, }; const requiredScope = "read"; function createServer() { const server = new McpServer({ name: "FileServer", version: "1.0.0" }); server.resource( "app-settings", "config://app-settings", async () => ({ contents: [ { uri: "config://app-settings", mimeType: "text/plain", text: "Mode: Development; Version: 1.0.0; Allowed-Extensions: .txt, .md", }, ], }) ); server.resource( "explorer", "folder://explorer", async () => { const files = await fs.readdir(WORKING_DIR); const text = files.length > 0 ? files.join("\n") : "The directory is empty."; return { contents: [{ uri: "folder://explorer", mimeType: "text/plain", text }], }; } ); server.tool( "write_file", { filename: z.string().describe("Name of the file to write"), content: z.string().describe("Content to write into the file"), }, async ({ filename, content }) => { const filePath = path.join(WORKING_DIR, filename); await fs.writeFile(filePath, content, "utf8"); return { content: [{ type: "text", text: `File '${filename}' written successfully.` }], }; } ); server.tool( "read_file", { filename: z.string().describe("Name of the file to read"), }, async ({ filename }) => { const filePath = path.join(WORKING_DIR, filename); try { const content = await fs.readFile(filePath, "utf8"); return { content: [{ type: "text", text: content }] }; } catch { return { content: [{ type: "text", text: `File ${filename} not found!!` }] }; } } ); server.tool( "remove_file", { filename: z.string().describe("Name of the .tmp file to remove"), }, async ({ filename }) => { const ext = path.extname(filename).toLowerCase(); const filePath = path.join(WORKING_DIR, filename); let status; if (ext !== ".tmp") { status = `File '${filename}' is not a tmp file.`; } else { try { await fs.access(filePath); await fs.unlink(filePath); status = `File '${filename}' removed successfully.`; } catch { status = `File '${filename}' not present.`; } } return { content: [{ type: "text", text: status }] }; } ); server.prompt( "useful_helper_prompt", { lang: z.string() }, ({ lang }) => ({ messages: [ { role: "user", content: { type: "text", text: `You are an expert in ${lang}. create or update file using ${lang} code.`, }, }, ], }) ); return server; } const app = express(); app.use(express.json()); const authMiddleware = (req, res, next) => { console.log(`[${new Date().toISOString()}] Incoming ${req.method} request to ${req.path}`); const token = req.headers["authorization"]?.split(" ")[1]; const entry = token ? validTokens[token] : null; if (!entry || !entry.scopes.includes(requiredScope)) { console.warn("Auth Failed"); return res.status(403).json({ error: "Forbidden" }); } console.log(`Auth OK for ${entry.client_id}`); next(); }; app.post("/mcp", authMiddleware, async (req, res) => { const server = createServer(); try { const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); await server.connect(transport); await transport.handleRequest(req, res, req.body); } catch (error) { console.error("Request Error:", error); res.status(500).json({ error: "Internal Server Error" }); } }); const PORT = 8001; app.listen(PORT, "0.0.0.0", () => { console.log(`FileServer active at http://0.0.0.0:${PORT}/mcp | Auth: Bearer dev-token`); }); ``` ## MCP File Server (STDIO) — JavaScript ```shellscript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; import fs from "fs/promises"; import fsSync from "fs"; import path from "path"; const WORKING_DIR = path.resolve("./mcp-data"); fsSync.mkdirSync(WORKING_DIR, { recursive: true }); const server = new McpServer({ name: "FileAgentServer", version: "1.0.0" }); server.resource( "app-settings", "config://app-settings", async () => ({ contents: [ { uri: "config://app-settings", mimeType: "text/plain", text: "Mode: Development; Version: 1.0.0; Allowed-Extensions: .txt, .md", }, ], }) ); server.resource( "explorer", "folder://explorer", async () => { const files = await fs.readdir(WORKING_DIR); const text = files.length > 0 ? files.join("\n") : "The directory is empty."; return { contents: [{ uri: "folder://explorer", mimeType: "text/plain", text }], }; } ); server.tool( "write_file", { filename: z.string().describe("Name of the file to write"), content: z.string().describe("Content to write into the file"), }, async ({ filename, content }) => { const filePath = path.join(WORKING_DIR, filename); await fs.writeFile(filePath, content, "utf8"); return { content: [{ type: "text", text: `File '${filename}' written successfully.` }], }; } ); server.tool( "remove_file", { filename: z.string().describe("Name of the .tmp file to remove"), }, async ({ filename }) => { const ext = path.extname(filename).toLowerCase(); const filePath = path.join(WORKING_DIR, filename); let status; if (ext !== ".tmp") { status = `File '${filename}' is not a tmp file.`; } else { try { await fs.access(filePath); await fs.unlink(filePath); status = `File '${filename}' removed successfully.`; } catch { status = `File '${filename}' not present.`; } } return { content: [{ type: "text", text: status }], }; } ); const transport = new StdioServerTransport(); await server.connect(transport); ``` ## package.json - Javascript ```shellscript { "type": "module", "dependencies": { "@modelcontextprotocol/sdk": "^1.7.0", "bluejs": "file:..", "eventsource": "^4.1.0", "express": "^4.18.2", "zod": "^3.22.4", "glob": "^10.3.10", "yargs": "^17.7.2" } } ``` ## `chat_agent.py` {% code title="" lineNumbers="true" %} ```python import os import asyncio from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import chain template = ChatPromptTemplate.from_messages([('system', 'You are a helpful assistant'), ('human', '{question}')]) llm = ChatOpenAI(base_url="", model="", temperature=0) @chain def chatbot(values): prompt = template.invoke(values) return llm.invoke(prompt) for chunk in chatbot.stream({"question": "why is sky blue?"}): print(chunk.content) ``` {% endcode %} ## `help_agent_crewai.py` {% code title="help\_agent\_crewai.py" lineNumbers="true" %} ```python import json from crewai import LLM, Agent, Crew, Task, Process class Assistant: def help_agent(self) -> Agent: return Agent( role="Helpful assistant", goal="Helpful assistant. answer user queries", backstory="A helpful assistant. can answer any topic", llm=LLM( model="", base_url="", stream=True ), verbose=True ) def task_one(self, agent: Agent) -> Task: return Task( description="why sky is blue?", expected_output="provide more scientic answer", agent=agent # Uses the shared agent instance ) def crew(self) -> Crew: # Create a single instance of the agent to share across Task and Crew shared_agent = self.help_agent() return Crew( agents=[shared_agent], tasks=[self.task_one(shared_agent)], process=Process.sequential, verbose=True ) try: crew_output = Assistant().crew().kickoff() print(f"Raw Output: {crew_output.raw}") if crew_output.json_dict: print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}") if crew_output.pydantic: print(f"Pydantic Output: {crew_output.pydantic}") print(f"Tasks Output: {crew_output.tasks_output}") print(f"Token Usage: {crew_output.token_usage}") except Exception as err: print(f"An error occurred: {err}") ``` {% endcode %} ## `search_agent.py` {% code title="dummy\_search\_agent.py" lineNumbers="true" %} ```python import os from anthropic import Anthropic try: client = Anthropic( api_key=os.environ.get(""), base_url="") print("Agent is running!", flush=True) message = client.messages.create( model="", max_tokens=1024, messages=[ {"role": "user", "content": "Hello, Claude. Why is the sky so blue?"} ] ) print(message.content[0].text) print("execution completed successfully", flush=True) except Exception as err: print(f"An error occurred: {err}") ``` {% endcode %} ## `search_agent_gemini.py` {% code title="search\_agent\_gemini.py" lineNumbers="true" %} ```python import asyncio from google.adk.agents import Agent from google.adk.tools import google_search from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService from google.genai import types QUERY = "why is the sky blue?" agent = Agent( name="search_agent", model="", instruction="Helpful assistant. Answer user queries using web search.", tools=[google_search], ) async def main(): try: session_service = InMemorySessionService() session = await session_service.create_session( app_name="", user_id="" ) runner = Runner( agent=agent, app_name="", session_service=session_service ) message = types.Content(role="user", parts=[types.Part(text=QUERY)]) print("Agent is running!", flush=True) async for event in runner.run_async( user_id="", session_id=session.id, new_message=message ): if event.is_final_response() and event.content: print(event.content.parts[0].text) print("execution completed successfully", flush=True) except Exception as err: print(f"An error occurred: {err}") if __name__ == "__main__": asyncio.run(main()) ``` {% endcode %} ## `hello_world_oai.py` {% code title="hello\_world\_oai.py" lineNumbers="true" %} ```python import os from openai import OpenAI try: client = OpenAI( # Defaults to the standard environment variable api_key=os.environ.get(""), base_url="" ) print("Agent is running!", flush=True) response = client.chat.completions.create( model="", messages=[{"role": "user", "content": "Hello world, using the Python SDK!"}], ) print(response.choices[0].message.content) print("execution completed successfully", flush=True) except Exception as err: print(f"An error occurred: {err}") ``` {% endcode %} ## `search_agent_litellm.py` {% code title="search\_agent\_litellm.py" lineNumbers="true" %} ```python import os from litellm import completion # Ensure the API key environment variable is set # It can be set in the terminal or within the script like this: # os.environ[""] = "api-key-here" messages = [{ "content": "Hello, what is a rainbow?", "role": "user" }] # Call the completion function # To use a different provider, change the 'model' parameter to the provider's format try: print("Agent is running!", flush=True) response = completion( api_base="", api_key=os.environ.get(""), model="", messages=messages ) # Print the response content print(response.choices[0].message.content) print("execution completed successfully", flush=True) except Exception as err: print(f"An error occurred: {err}") ``` {% endcode %}