# OX Runtime Sensor

> **Note:** This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support.

Runtime Sensor is an OX capability for Kubernetes environments that collects runtime signals from your applications and turns them into actionable insights in OX.

Runtime Sensor detects which third-party libraries are actually loaded in memory at runtime. When a known vulnerability affects a library in your codebase, knowing whether that library is loaded gives you a stronger indication of urgency during triage.

Supported runtimes and package types:

* JavaScript (Node.js)
* Python
* Java\*
* PHP
* Ruby
* C#
* Native packages (shared libraries)

\* Standard JARs only, fat/uber JARs have limited support.

Insights appear in OX in the Active Issues page as severity factors. You can see whether a dependency is loaded at runtime or not, with evidence you can review. This context lets you prioritize fixes that reduce real, current risk in your running services.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-267a1ea37e63bb3938349471919fadbcbebb85e8%2FRuntime_active%20_issues%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

In the [SBOM page](https://docs.ox.security/inventory-with-ox-bom/sbom) you can view the runtime status of each asset.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-592038b7ffc54785d709802ed752727cb4e72c5d%2FRuntime_SBOM1.png?alt=media" alt=""><figcaption></figcaption></figure>

The OX Runtime Sensor runs as a Kubernetes DaemonSet (one pod per node). It uses eBPF to observe file access at the kernel level, no code changes, no sidecars, no application restarts required.

The sensor authenticates to OX with an API key over outbound TLS. It does not write data to the node and does not require persistent storage. CPU, memory, and disk usage are minimal.

The following is the runtime installation and connection process. For advanced configuration, security requirements, and deployment customization, see [Runtime Sensor Advanced Configuration](https://docs.ox.security/secure-runtime/ox-runtime-sensor/runtime-sensor-advanced-configuration).

## Prerequisites

* **Technology:** Kubernetes (EKS / AKS / GKE)
* **Kubernetes version:** v1.20 and later
* **Linux kernel:** v5.10 and later with BTF enabled (any Linux distribution)
* **Network:** Outbound HTTPS (port 443) access to `api.cloud.ox.security`. If your environment routes traffic through a proxy, see Proxy configuration

## Step 1: Create a new API key

1. From the left pane of **OX dashboard**, select **Settings > API Key Settings**.
2. In the **API Key Settings** window, select **CREATE API KEY**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-7e81b28f5c0ff11132bf749b7a737e69b3905b09%2FRuntime%20API%20key.png?alt=media" alt="" width="358"><figcaption></figcaption></figure>

3. In the **Create API Key** box, set the following and select **CREATE**:

* **API Key Name:** Add a meaningful name that is easy to identify. It is good practice to include the key's intended purpose in the name.
* **API Key Type:** Select **K8 Inspector/Runtime Sensor Integration**.
* **Expiration Date:** Until when you can use this key.

4. Copy the key that appears and save the key in a safe location. This is the only time when you can see and copy the actual key.
5. Select **CLOSE**. The new key appears in the **API Key Settings** page.

## Step 2: Install OX Runtime Sensor with Helm

Install the Runtime Sensor using Helm. The default installation creates the required namespace and API key secret automatically.

If you need to manage secrets externally or customize the setup, you can create these resources manually before installing the sensor.

**To install using Helm:**

1. Add the Helm repository and update it:

```
helm repo add ox-runtime-sensor-repo https://charts.cloud.ox.security
helm repo update
```

2. Install the sensor:

```
helm install ox-runtime-sensor ox-runtime-sensor-repo/ox-runtime-sensor \
  --namespace ox-runtime --create-namespace \
  --set secret.create=true \
  --set secret.apiKey="<API_KEY>" \
  --set cluster.name="<CLUSTER_NAME>" \
  --set cluster.account_id="<ACCOUNT_ID>" \
  --set cluster.cloud_provider="<CLOUD_PROVIDER>" \                                                                                                                                                                                                                     
--set cluster.region="<REGION>"
```

| Placeholder        | Description                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `<API_KEY>`        | The API key you previously generated                                                                                      |
| `<CLUSTER_NAME>`   | Name of the Kubernetes cluster where Runtime Sensor will run                                                              |
| `<ACCOUNT_ID>`     | Cloud provider account identifier (AWS Account ID, Azure Subscription ID, or GCP Project ID, e.g. `123456789012` for AWS) |
| `<CLOUD_PROVIDER>` | Cloud provider where the cluster is running (`aws`, `gcp`, or `azure`)                                                    |
| `<REGION>`         | Cloud region where the Kubernetes cluster is running (for example, `us-east-1`, `europe-west1`, `westeurope`)             |

> **Note:** For production environments, it is recommended to manage secrets externally using tools such as External Secrets Operator, Sealed Secrets, or HashiCorp Vault rather than passing the API key directly via Helm values. See External secret management below.

3. Verify that the sensor pods are running:

```
kubectl -n ox-runtime get pods
```

**To install using an existing secret:**

1. Create the namespace:

```
kubectl create namespace ox-runtime
```

2. Create the API key secret:

```
kubectl -n ox-runtime create secret generic ox-runtime-sensor-secret \
  --from-literal=api-key=<API_KEY>
```

3. Install the sensor:

```
helm install ox-runtime-sensor ox-runtime-sensor-repo/ox-runtime-sensor \
  --namespace ox-runtime \
  --set cluster.name="<CLUSTER_NAME>" \
  --set cluster.account_id="<ACCOUNT_ID>" \
  --set cluster.cloud_provider="<CLOUD_PROVIDER>" \                                                                                                                                                                                                                     
--set cluster.region="<REGION>"
```

4. If your existing secret uses a different name or key field, update the Helm command:

> If you use an external secret manager, make sure the secret already exists in the `ox-runtime` namespace before you install the sensor.\
> If your secret uses a different secret name or key field, update the Helm command accordingly.

```
helm install ox-runtime-sensor ox-runtime-sensor-repo/ox-runtime-sensor \
  --namespace ox-runtime \
  --set secret.name=my-existing-secret \
  --set secret.apiKeyField=my-api-key-field \
  --set cluster.name="<CLUSTER_NAME>" \
  --set cluster.account_id="<ACCOUNT_ID>" \
  --set cluster.cloud_provider="<CLOUD_PROVIDER>" \                                                                                                                                                                                                                     
--set cluster.region="<REGION>"
```

## Step 3: Connect to OX Runtime Sensor

> **Note:** Before connecting, a DevOps team member must ensure that the CronJob is running in your environment.

1. In the OX platform, go to the **Connectors** page.
2. Select **Add Connector** and search for **OX Runtime Sensor**.
3. In the **Configure your OX Runtime Sensor credentials** dialog, select **CONNECT**.

<figure><img src="https://884876233-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdK3XMLdV8zRg847RmGmZ%2Fuploads%2Fgit-blob-639cd751b81fdc06e5bd05864256351d7ffb42a9%2FRuntime%20connect.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

[To use eBPF programs, OX complies with the GPL.](https://docs.ox.security/secure-runtime/ox-runtime-sensor/gpl-licensed-components-and-source-availability)