BlueRock AWS CloudFormation Deployment

Introduction

The following is a guide that shows how to create and deploy a BlueRock Node using a CloudFormation template in AWS.

Architecture Diagram

Above is the architecture created by the CloudFormation Template. It contains the following components:

• The BlueRock Node Instance. This instance and its workloads are protected by BlueRock, it contains the following:

  • BlueRock Rule Processing Engine: This container manages the node's policy and collects information about the node for rule enforcement. BlueRock policies can be configured for application and container runtime as well as process and file level controls.

  • Trex: Trex is an internal tool that turns simple json policy files into signed BlueRock consumable policy files. After writing a new policy file it needs to be processed by Trex before being uploaded to the policy bucket

  • OTel Collector: BlueRock manages its logs using Open Telemetry Receivers, Processors and Collectors. An intermediate collector has been placed as a container on this instance to allow for ease of access in the log management for this marketplace listing. All BlueRock Logs are sent through this intermediary collector on their way to Cloudwatch.

• Additional AWS services: This template utilizes additional Amazon services for configuration and event monitoring

  • Amazon S3: This service is used to store signed policies in a BlueRock Policy S3 Bucket

  • Amazon CloudWatch: BlueRock sends events to a CloudWatch Log Group via the OTel Collector

Installation

Prerequisites

The following NodeInstanceTypes are supported with BlueRock. Larger instance sizes should also be compatible, but the below list has been validated:

t3.2xlarge	
t3.xlarge	
t3.large	
t3.medium	
t3.micro	
t3.nano	
t3.small	
m5.2xlarge	
m5.xlarge	
m5.large	
r5.2xlarge	
r5.xlarge	
r5.large	
r5n.2xlarge	
r5n.xlarge	
r5n.large	
i4i.2xlarge	
i4i.xlarge	
i4i.large	
d3.2xlarge	
d3.xlarge

The BlueRock Installation requires customers launch the BlueRock EC2 deployment from AWS Marketplace. Free private offers can be made available upon request.

• The BlueRock Amazon Linux 2023 EC2 listing can be found here.

IAM Role and Policy Documentation

This CloudFormation template creates an IAM role (InstanceRole) and an associated IAM policy (InstancePolicy). The purpose of these resources is to grant specific permissions to an Amazon EC2 instance, allowing it to interact with other AWS services in a secure and controlled manner.

---

InstanceRole

The InstanceRole is an IAM role designed to be assumed by an Amazon EC2 instance.

• Purpose: This role grants the EC2 instance the necessary permissions to perform its designated tasks by allowing it to assume this role.

• Trusted Entity: The role's trust policy specifies that only the EC2 service (ec2.amazonaws.com) can assume this role. This is a standard practice for creating IAM roles for EC2 instances.

• Managed Policies: This role includes two AWS managed policies:

  • arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess: This policy grants read-only access to Amazon EC2 resources. This allows the instance to describe EC2 resources, which can be useful for inventory or monitoring purposes without allowing any modifications.

  • arn:aws:iam::aws:policy/AWSMarketplaceManageSubscriptions: This policy provides permissions to manage AWS Marketplace subscriptions. This allows the instance to subscribe to and unsubscribe from AWS Marketplace products.

---

InstancePolicy

The InstancePolicy is a custom IAM policy that grants additional, more specific permissions to the InstanceRole.

• Purpose: This policy defines fine-grained permissions required by the application running on the EC2 instance to interact with Amazon S3 and Amazon CloudWatch Logs.

• Permissions: The policy contains the following statements:

  • Statement 1: General Permissions

    • s3:ListBucket: This permission allows the instance to list the objects within an S3 bucket. This is often required to iterate through the contents of a bucket.

    • s3:PutObject: This permission allows the instance to upload new objects to an S3 bucket.

    • logs:PutLogEvents: This permission allows the instance to upload log events to a CloudWatch Logs stream. This is essential for applications that need to centralize their logging.

    • Resource: The resource is set to *, which means these actions are allowed on all resources of the respective service. While this provides broad access, the subsequent statement narrows down the s3:PutObject permission.

  • Statement 2: Specific S3 Upload Permissions

    • s3:PutObject: This part of the policy further refines the PutObject permission. It restricts the upload of specific files to a designated S3 bucket (${PolicyBucket.Arn}). The files that can be uploaded are:

      • bluerock_pub_key.pem

      • config.toml

      • policy.json

      • policy.json.sha256

      • policy.json.sig

    • Resource: The permissions are scoped to the specific S3 bucket and the exact file names, following the principle of least privilege by ensuring the instance can only write these specific files to the intended location.

To use this Cloud Formation template, ensure that the calling entity has the permissions necessary to call for CAPABILITY_NAMED_IAM capabilities. Additionally, ensure that an AWS managed ssh key is present in the region. As a parameter of the template, a key managed by the EC2 service is needed for developers to access the nodes. Developers should have access to the name of their key and the private and public key files.

Using CloudFormation

Through the AWS Web Console

1. Navigate to the CloudFormation Service Page

2. Select Create stack → With new resources (standard)

3. Select Choose an existing template

   1. Specify template source by selecting the Upload a template file

4. Upload the BlueRock CloudFormation Template

5. Select Next

6. Fill in all template parameters (see Parameter table below)

7. Select Next

8. Under Capabilities Acknowledge the creation of IAM Roles / Policies (see Policy Table Below)

9. Select Next

10. Confirm Stack creation and Submit

Through the AWS CLI

Make sure the CLI is installed and has privileges to specify CAPABILITY_NAMED_IAM

Call create-stack specifying the parameter file, template file and capabilities

aws cloudformation create-stack \
  --stack-name bluerock-ec2-stack \
  --template-body file://al2023/bluerock-bru-aws-ec2-template-25.31.0.yaml \
  --parameters \
    ParameterKey=AllowIp,ParameterValue=0.0.0.0/0 \
    ParameterKey=NodeInstanceType,ParameterValue=t3.large \
    ParameterKey=Prefix,ParameterValue=bluerock-prod \
    ParameterKey=SampleHostName,ParameterValue=prod-bru-host \
    ParameterKey=SshKeyName,ParameterValue=your-key-name \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

Example Parameters File

[
  {
    "ParameterKey": "AllowIp",
    "ParameterValue": "<your_ip_address>/32"
  },
  {
    "ParameterKey": "NodeInstanceType",
    "ParameterValue": "t3.xlarge"
  },
  {
    "ParameterKey": "Prefix",
    "ParameterValue": "unplugged-single-1"
  },
  {
    "ParameterKey": "SampleHostName",
    "ParameterValue": "bru-host"
  },
  {
    "ParameterKey": "SshKeyName",
    "ParameterValue": "my-ssh-key"
  }
]

CloudFormation Template Parameters

Parameter Name	Description
AllowIp	Developer’s IP address to whitelist in the BlueRock Instance for SSH access
NodeInstanceType	Size of BlueRock node to be created.
Prefix	Unique Identifier appended to AWS resource names
SampleHostName	Unique Identifier for BlueRock UC Container name
SshKeyName	Name of AWS managed SSH key, used for authorizing access to the BlueRock Instance

This stack takes about 2-5 minutes to build.

Installation Validation Checks

SSH into BlueRock Instance

Once the stack has completed, select it (CloudFormation → <Stack-Name>) and view the Resources tab. Here you can search for the NodeInstance instance. Connect to NodeInstance via an SSH command using the key specified in SshKeyName.

SSH Command

ssh -i <priv-key> ec2-user@<instance-pub-ip>

Check Services

The BlueRock Services are initialized through the uc-docker.service service. Ensure that the service and the Rule Engine container are running and enabled. Additionally, use the provided script to view the logs exported by the Rule Engine.

$sudo systemctl status uc-docker.service
$ docker ps
CONTAINER ID   IMAGE                                                        COMMAND                  CREATED       STATUS       PORTS     NAMES
5b5e00d1881f   ultracontrol:latest                                          "/opt/bluerock/sbin/…"   7 hours ago   Up 7 hours             uc
e0186c875227   public.ecr.aws/aws-observability/aws-otel-collector:latest   "/awscollector --con…"   7 hours ago   Up 7 hours             otel-collector

$/opt/bluerock/bin/uc-docker.sh logs

Finally, ensure the OTEL collector service is running and enabled.

$docker logs otel-collector

Once connected, navigate to /opt/bluerock/trex where a sample policy (bru_policy.json) with all protection mechanisms set to observe mode is present. Once the policy is modified we need to sign it using Trex.

Ensure that the bru-venv is activated when using any python commands

$ source /home/ec2-user/build/bru-venv/bin/activate

$ source /home/ec2-user/build/bru-venv/bin/activate

$ cd /opt/bluerock/trex
$ python3 /opt/bluerock/trex/trex.py ./bru_policy.json
$ tar xvf bru_policy.tar

This will generate a tar file containing the new policy, the policy’s signature and a sha256 sum of the policy. All three of these files need to be uploaded to the BlueRock Policy Bucket. Note that these steps will need to be done each time the policy is modified

Now you can sync the files to the S3 bucket.

aws s3 sync . s3://${PolicyBucket} --exclude "*" --include "policy.json*"

These policy files take up to ~5 mins to propagate to each node.

Refer to the Configuring BlueRock Security Policies section for instructions on editing and tuning policies.