> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Installation

1. Install the module dependencies:

   **`Ubuntu`**

   ```shell Ubuntu
   apt update && apt install -y libcurl4 libapr1 libjansson4 libaprutil1 bzip2
   ```

   **`Centos`**

   ```shell Centos
   yum update && yum install -y jansson libcurl apr apr-util pcre
   ```

2. Extract the module:

   ```shell
   bunzip2 envoy.bz2
   ```

3. Copy the new Envoy binary to `/usr/local/bin/ folder`:

   ShellShell

   ```shell
   cp envoy /usr/local/bin/
   ```

4. In your `config.yaml` file add, a new filter in the `http_filters`section:

   YAMLYAML

   ```yaml
   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:

* **app\_id** - The HUMAN application id in the format of PX\_\_. The application id can be found at [**Platform Settings** -> **Applications** section](https://console.humansecurity.com/botDefender/applications).
* **cookie\_secret** - The key used by the cookie signing page. The Cookie Key is generated in the [**Platform Settings** -> **Policies** section](https://console.humansecurity.com/botDefender/policies).
* **auth\_token** - The JWT token for REST API. The Authentication Token is generated in the [**Platform Settings** -> **Applications** section](https://console.humansecurity.com/botDefender/applications).

5. Add a new "clusters" section, replace your "appID" values in "sapi-\[REPLACE with appID].perimeterx.net"

```yaml
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](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:

* `vX.X.X`: is Envoy version (Currently only v1.32 is available)
* `Y.Y.Y`: is HUMAN Enforcer version (ChangeLog: [/applications/envoy/changelog](/applications/envoy/changelog)). `latest` tag always contains the latest stable HUMAN Enforcer version.

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:

```yaml
          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](https://docs.humansecurity.com/applications-and-accounts/docs/envoy-configuration-options)

2. Add a new "clusters" section, replace your "appID" values in `sapi-[REPLACE with appID].perimeterx.net`:

```yaml
  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:

```yaml
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
```