Installation

  1. Install the module dependencies:

    apt update && apt install -y libcurl4 libapr1 libjansson4 libaprutil1 bzip2
    
    yum update && yum install -y jansson libcurl apr apr-util pcre
    
  2. Extract the module:

    bunzip2 envoy.bz2
    
  3. Copy the new Envoy binary to /usr/local/bin/ folder:

    ShellShell

    cp envoy /usr/local/bin/
    
  4. In your config.yaml file add, a new filter in the http_filterssection:

    YAMLYAML

    http_filters:
        ...
        - name: perimeterx
          typed_config:
            "@type": type.googleapis.com/udpa.type.v1.TypedStruct
            type_url: type.googleapis.com/perimeterx.Enforcer
            value:
              px_enabled: true
              px_appid: "REPLACE_WITH_YOUR_APP_ID"
              px_cookie_secret: "REPLACE_WITH_YOUR_COOKIE_SECRET"
              px_auth_token: "REPLACE_WITH_YOUR_AUTH_TOKEN"
    

Make sure to update the following required properties:

  1. Add a new "clusters" section, replace your "appID" values in "sapi-[REPLACE with appID].perimeterx.net"
clusters:
  ...
  - name: px_collector
    connect_timeout: 0.25s
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    load_assignment:
      cluster_name: px_collector
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: sapi-[REPLACE with appID].perimeterx.net
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        sni: sapi-[REPLACE with appID].perimeterx.net

HUMAN Envoy Enforcer Docker image

HUMAN Envoy Enforcer Docker image is based on envoyproxy/envoy:v1.32-latest (https://hub.docker.com/r/envoyproxy/envoy).
The only change is built-in "perimeterx" HTTP filter and installed system libraries (Enforcer dependencies).

HUMAN Envoy Enforcer Docker images are located in this repository: us-docker.pkg.dev/hmn-registry/docker-public/px-envoy

Versioning schema

All images use the following naming/versioning schema: px-envoy:vX.X.X-Y.Y.Y

Where:

To get v1.32 Envoy with the latest stable HUMAN Enforcer: docker pull us-docker.pkg.dev/hmn-registry/docker-public/px-envoy:v1.32-latest

Changes to Envoy configuration file:

  1. Add a new "http_filters" section, replace values using information from HUMAN portal:
          http_filters:
            - name: perimeterx
              typed_config:
                "@type": type.googleapis.com/udpa.type.v1.TypedStruct
                type_url: type.googleapis.com/perimeterx.Enforcer
                value:
                  px_appid: "REPLACE_WITH_YOUR_APP_ID"
                  px_cookie_secret: "REPLACE_WITH_YOUR_COOKIE_SECRET"
                  px_auth_token: "REPLACE_WITH_YOUR_AUTH_TOKEN"

Envoy Enforcer Configuration Options: https://docs.humansecurity.com/applications-and-accounts/docs/envoy-configuration-options

  1. Add a new "clusters" section, replace your "appID" values in sapi-[REPLACE with appID].perimeterx.net:
  clusters:
  - name: px_collector
    connect_timeout: 0.25s
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    load_assignment:
      cluster_name: px_collector
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: sapi-[REPLACE with appID].perimeterx.net
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        sni: sapi-[REPLACE with appID].perimeterx.net

Example of a full Envoy configuration:

admin:
  address:
    socket_address:
      protocol: TCP
      address: 0.0.0.0
      port_value: 9901
static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address:
        protocol: TCP
        address: 0.0.0.0
        port_value: 8080
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          scheme_header_transformation:
            scheme_to_overwrite: https
          stat_prefix: ingress_http

          http_filters:
            - name: perimeterx
              typed_config:
                "@type": type.googleapis.com/udpa.type.v1.TypedStruct
                type_url: type.googleapis.com/perimeterx.Enforcer
                value:
                  px_enabled: true
                  px_appid: "REPLACE"
                  px_cookie_secret: "REPLACE"
                  px_auth_token: "REPLACE"
                  px_debug: true
                  px_block_enabled: true

            - name: envoy.filters.http.router
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  prefix: "/"
                route:
                  host_rewrite_literal: www.envoyproxy.io
                  cluster: service_envoyproxy_io

  clusters:
  - name: service_envoyproxy_io
    connect_timeout: 30s
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    lb_policy: ROUND_ROBIN
    load_assignment:
      cluster_name: service_envoyproxy_io
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: www.envoyproxy.io
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        sni: www.envoyproxy.io

  - name: px_collector
    connect_timeout: 0.25s
    type: LOGICAL_DNS
    dns_lookup_family: V4_ONLY
    load_assignment:
      cluster_name: px_collector
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: sapi-REPLACE.perimeterx.net
                port_value: 443
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        sni: sapi-REPLACE.perimeterx.net