Skip to main content
Cequence eBPF Sensor

Search

Installing the eBPF sensor on Linux

© 2024 Cequence Security. All Rights Reserved.

Installing the eBPF sensor on Linux

  • Updated on
  • ~ minute read
Download PDF

This guide walks you through deploying Cequence's eBPF sensor and bridge components using Docker Compose. The eBPF sensor monitors network traffic at the kernel level, while the Cequence Bridge component forwards collected data to your Cequence UAP (Unified API Protection) platform for analysis.

System requirements

Your deployment environment needs the following minimum specifications to run the Cequence sensor effectively:

  • Hardware: 2GB RAM minimum, 2 vCPU cores
  • Permissions: Root access or sudo privileges for container operations
  • Network: Internet connectivity for downloading container images and communicating with UAP

Software dependencies

The deployment requires Docker Engine and Docker Compose to manage the containerized services. You'll need Docker Engine (latest stable version) and Docker Compose version 1.29.0 or higher.

Install Docker Engine for your operating system:

Security configuration notes

For Amazon Linux and Red Hat Enterprise Linux systems, SELinux can interfere with container permissions. Disable SELinux or set it to permissive mode before deployment:

sudo setenforce 0

Authentication setup

Before deploying the sensor, you need to obtain credentials from your UAP portal and configure access to the GitLab container registry.

Obtain UAP credentials

The sensor requires authentication credentials to communicate with your UAP platform. To retrieve these credentials:

  1. Log into your Cequence UAP portal using your administrator credentials.`
  2. From the UAP portal interface, navigate to Settings > General Settings > Clients.
  3. From the Clients page, either click Create New Client to generate new credentials or select an existing client entry.
  4. Copy both the Client ID and Client Secret values - you'll need these for configuration.
  5. Note your UAP subdomain from your portal URL. For example, if your UAP URL is https://ui.cqai.yourcompany.com, your subdomain is cqai.yourcompany.com.

Configure registry access

The deployment uses container images stored in GitLab's registry. Your Cequence SE will provide GitLab credentials for accessing these images.

To authenticate with the GitLab registry:

docker login registry.gitlab.com

When prompted, enter your GitLab username and access token. After successful authentication, verify you can access the required images:

docker pull registry.gitlab.com/cequence/releases/dataplane/ebpf:2.0.0
docker pull registry.gitlab.com/cequence/releases/dataplane/bridge:5.6.5

Configuration setup

The deployment uses environment variables and Docker Compose to manage configuration. You'll create two files: an environment file containing your credentials and a Docker Compose file defining the services.

Create environment configuration

Create a .env file in your deployment directory containing your UAP authentication details.

# Cequence UAP Authentication

CLIENT_ID= <your client ID>
CLIENT_SECRET= <your client secret>

# UAP subdomain (For example, if the URL is ui.yourcompany.cequence.ai,
# your subdomain is yourcompany.cequence.ai)

UAP_SUBDOMAIN=your-uap-subdomain

# Image versions (optional - defaults shown)

SENSOR_TAG=5.6.5
BRIDGE_TAG=5.6.2

Replace the placeholder values with your actual credentials obtained from the UAP portal.

Create Docker Compose configuration

Create a docker-compose.yml file in the same directory as your .env file. This file defines both the eBPF sensor and bridge services with their required configurations:

version: '3.8'
services:
  ebpf-sensor:
    image: registry.gitlab.com/cequence/releases/dataplane/ebpf-sensor:2.0.0
    container_name: ebpf-sensor
    restart: always
    privileged: true
    network_mode: host
    pid: host
    cap_add:
      - SYS_ADMIN
      - NET_ADMIN
      - PERFMON
    environment:
      - LIBBPFGO_OSRELEASE_FILE=/etc/os-release-host
      - LOG_LEVEL=INFO
      - CAPTURE_CONTAINER_EVENTS=true
      - CAPTURE_HOST_EVENTS=true
      - K8S_APP_IDENTIFIERS_ENABLED=true
      - CACHE_ENABLED=true
      - CACHE_SIZE_MB=64
      - SENSOR_NAMESPACE_FILTERS={"exclude":[],"include":[]}
      - BRIDGE_PROTOCOL=http
      - BRIDGE_PORT=8443
      - BRIDGE_HOST=127.0.0.1
      - BRIDGE_PATH=/api-transactions
      - BRIDGE_SKIP_TLS_VERIFY=false
      - BRIDGE_BATCHING_ENABLED=true
      - BRIDGE_BATCH_SIZE_KB=1024
      - BRIDGE_BATCH_FLUSH_INTERVAL_MS=5000
      - ENABLE_METRICS=false
      - EBPF_PERF_BUFFER_SIZE=16384
      - EBPF_BLOB_PERF_BUFFER_SIZE=32768
      - EBPF_PIPELINE_CHANNEL_SIZE=62500
      - CONTAINER_RUNTIME_SOCKET=/run/containerd/containerd.sock 
    volumes:
      - /sys/kernel/debug:/sys/kernel/debug
      - /sys/kernel/tracing:/sys/kernel/tracing
      - /sys/fs/bpf:/sys/fs/bpf
      - /lib/modules:/lib/modules:ro
      - /sys:/sys:ro
      - /etc/os-release:/etc/os-release-host:ro
      - /usr/src:/usr/src
      - /tmp/cequence:/tmp/cequence
      - /run/containerd/containerd.sock:/run/containerd/containerd.sock:ro
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1024M
        reservations:
          cpus: '0.5'
          memory: 256M    
    depends_on:
      - cequence-bridge
  cequence-bridge:
    image: registry.gitlab.com/cequence/releases/dataplane/cequence-bridge:5.6.5
    container_name: cequence-bridge
    restart: always
    ports:
      - "8443:8443"
    environment:
      - INSTANCE_ID=cequence-bridge
      - LOG_OUTPUT=stdout
      - LOG_LEVEL=error
      - CEQUENCE_BRIDGE_MODE=external
      - READER_TYPE=http
      - INPUT_FORMAT_TYPE=unified
      - AUTH_ENABLED=false
      - DISABLE_SSL_VERIFY=true
      - SENSOR_CONNECTOR_DATA_FORMAT=unified
      - APIEDGE_CLIENT_ID=${CLIENT_ID}
      - APIEDGE_CLIENT_SECRET=${CLIENT_SECRET}
      - APIEDGE_HOST_PORT="edge.${UAP_SUBDOMAIN}"
      - APIEDGE_TOKEN_URL="https://auth.${UAP_SUBDOMAIN}/auth/realms/cequence/protocol/openid-connect/token"
      - READER_PORT=8443
      - READER_USE_SSL=false
    volumes:
      - bridge-ephemeral:/opt/cequence/sensor/data
    user: "1000:1000"
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.2'
          memory: 256M
volumes:
  bridge-ephemeral:
    driver: local

Deployment process

With your configuration files in place, you can deploy the Cequence sensor stack and verify its operation.

Start the services

From the directory containing your .env and docker-compose.yml files, start the services in detached mode:

docker-compose up -d

Monitor and verify deployment

After starting the services, monitor the deployment progress and verify proper operation:

# View real-time logs from both services
docker-compose logs -f

# Check the status of running services
docker-compose ps

# Test the bridge endpoint connectivity
curl -k -X POST http://localhost:8443/api-transactions -H "Content-Type: application/json" -d '{"url":"google.com", "key2":"test"}'

Verify sensor functionality

To confirm the sensor is capturing and forwarding traffic data to UAP, generate some HTTP traffic:

curl http://google.com

When the eBPF sensor is functioning properly, this request appears in your UAP console within a few minutes, confirming successful integration between the sensor and your UAP platform.

Support resources

If you encounter issues during deployment or operation:

  • Review the official Cequence UAP documentation for detailed troubleshooting guidance
  • Contact Cequence Security support for technical assistance
  • Check sensor container logs using docker-compose logs for detailed error messages

Version information

This deployment guide covers the following component versions:

  • eBPF Sensor: 2.0
  • Bridge: 5.6.5
  • Docker Compose: 3.8
Was this article helpful?
Japanese (Japan)