OX Broker

OX Broker is a secure, containerized service that enables communication between your environment and OX Security services, enabling connection to your internal resources.

The broker component reverses the typical connection pattern. Instead of customers opening inbound ports to OX and adding OX IPs to their whitelist, a broker runs in the customer's environment and initiates a secure outbound connection to OX. This improves security and simplifies the integration process, particularly for customers with strict security policies.

Supported Connectors

• GitLab

• GitHub

• Azure TFS

• Harbor

• GitLab Container Registry

• JFrog Artifactory

• Bitbucket Data Center or Server

• Jira

Prerequisites

Before you begin, contact an OX Security Customer Success representative for feature enablement.

OX Broker can be installed using Docker Compose on a Linux host or using a Helm chart on a Kubernetes cluster. Ensure your environment meets the following requirements based on your chosen method:

Requirement Type	Details
Operating System	Ubuntu 22.04 or later, RHEL 9
Hardware	Minimum: 4 GB RAM, 2 CPU cores, 10 GB of available disk space
Network Requirements	Connectivity to your internal connectors. Outgoing traffic on port 443 to the address provided by OX. Outgoing traffic to Docker Hub for pulling container images. Share the public IP address of the OX Broker host with OX Security. Proxy: If your traffic is routed through a proxy, ensure port 443 HTTPS is allowed for outbound communication to the OX environment. Share the proxy IP address with OX Security.

Docker Compose requirements

Requirement Type	Details
Software	Docker Engine and Docker Compose V2
Access	Root access or sudo available

To verify your machine is configured correctly, download and run the readiness script:

curl -fsSL https://installer.broker.ox.security/universal/oxbroker_readiness.sh -o oxbroker_readiness.sh
chmod +x oxbroker_readiness.sh
sudo ./oxbroker_readiness.sh

Helm requirements

Requirement Type	Details
Kubernetes	Access to a Kubernetes cluster
Software	Helm version 3 or later, kubectl configured for the target cluster

Installing OX Broker

Choose the method that matches your deployment environment and follow the relevant installation procedure:

• Docker Compose on a Linux host or virtual machine

• Helm chart on a Kubernetes cluster

Install OX Broker Using Docker Compose

To install OX Broker using Docker Compose:

1. Request the installation script URL from the OX Security support team.

2. Download the script to your machine.

3. Add permissions to run the script.

chmod +x install.sh

1. Run the script as Admin.

sudo -E ./install.sh

The installation script runs, generating asymmetric keys and OXBroker credentials. The private key is saved on your system automatically, and the public key you need to OX Security support team.

1. Send the public key to OX Security support.

2. Save the credentials in your environment in a safe location.

3. To proceed with the installation, press p and follow the on-screen instructions.

4. When asked about the TLS configuration, reply yes.

5. If relevant, when asked about the Proxy configuration, reply yes.

Install OX Broker Using Helm

This installation method deploys OX Broker into a Kubernetes cluster using a Helm chart.

To install OX Broker using Helm:

1. Add the OX Security Helm repository and update it.

helm repo add ox https://charts.cloud.ox.security
helm repo update

1. Verify the chart is available.

helm search repo ox/ox-broker

1. Generate authentication keys locally.

ssh-keygen -q -t rsa -b 4096 -f oxbroker-key -N "" -C "oxbroker@k8s" && cat oxbroker-key.pub

1. Send the public key (oxbroker_key.pub) to OX Security and wait for confirmation and the assigned OX Broker server address.

2. Create a Kubernetes namespace and secret containing the authentication keys.

kubectl create namespace oxbroker
kubectl create secret generic oxbroker-keys -n oxbroker \
  --from-file=private-key=oxbroker_key \
  --from-file=public-key=oxbroker_key.pub

1. Install the Helm chart using the broker server address provided by OX Security.

helm install oxbroker ox/ox-broker -n oxbroker \
  --set oxbroker.remoteHost=<BROKER_SERVER_ADDRESS>

To configure proxy settings, add the following:

  --set proxy.enabled=true \
  --set proxy.host=<PROXY_HOST> \
  --set proxy.port=<PROXY_PORT>s

Note: <PROXY_HOST> must be the FQDN only, for example, proxy.company.com. Do not include the protocol or port.

Verifying OX Broker

To confirm that OX Broker is running:

• For Docker Compose installations:

docker compose ps

• For Helm installations:

kubectl get pods -n oxbroker

Configuring OX Broker

After installation completes, use with either method:

1. Log in to the OX Security portal.

2. Go to the relevant connector.

3. Select Broker as the connection method.

Provide the following details:

Field	Details
Internal resource URL	Provide the connector URL
Token	Add your connector token
User	The user that was generated by the OX script
Password	The password that was generated by the OX script
Bypass SSL Verification (not recommended)	Enable this option if your environment lacks a proper certificate or uses a self-signed certificate

Maintaining OX Broker

Docker Compose

Task	Command
Check service status	docker compose ps
View logs	docker compose logs -f
Restart services	docker compose restart

Helm

Use standard Kubernetes and Helm commands to manage the deployment.

Uninstall OX Broker

Docker Compose

cd oxbroker
docker compose down -v

Helm

helm uninstall oxbroker -n oxbroker
kubectl delete namespace oxbroker