Integrate with Envoy Gateway

Integration of open-appsec with Envoy Gateway is currently available as "alpha". Please share your feedback with us and let us know if you encounter any issues: [email protected]

Prerequisites

Kubernetes 1.16.0+ cluster with RBAC enabled with Cluster admin permissions
Existing Envoy Gateway deployment on Kubernetes
Current Deployment must be based on using Envoy Gateway Operator using EnvoyProxy CRD. As a result of this there should be an EnvoyProxy resource deployed in your K8s cluster.

At this time in the current alpha release, we only support open-appsec deployment in scenarios where the Envoy Gateway is deployed using the Envoy Gateway Operator (often preferred in large environments).

We also plan to support integration in scenarios where Envoy Gateway is deployed using helm charts soon as well, in case this is critical for you, please let us know at mailto:[email protected] .

The Envoy Proxy container must be using the contrib image: envoyproxy/envoy:contrib-<version> Make sure that <version> specified is one of the following supported Envoy Proxy versions: 1.32 - 1.34 (Mandatory to allow loading the open-appsec "attachment" filter for envoy, which is golang-based)
Make sure that enableEnvoyPatchPolicy is enabled in your Envoy Gateway via config map setting or Helm value, as an EnvoyPatchPolicy resource will be used to insert the go "attachment" filter for open-appsec to the Envoy configuration.
Sign-Up and Login to open-appsec central web UI portal Follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io, so you can create a deployment profile for the new deployment This allows you to either centrally manage your open-appsec WAF deployment via WebUI (SaaS) OR to locally manage your open-appsec WAF deployment but still connect to central WebUI for viewing the local configuration (in read-only), central monitoring, logging and reporting:

Sign-Up and Login to Portal

Local-only standalone deployments are not supported yet, we plan to add support for these as well soon, in case this is critical for you, please let us know at mailto:[email protected] .

Create deployment profile for the open-appsec deployment in WebUI Portal After you signed-up and logged in to the WebUI Portal (see prerequisite above), now follow the instructions below to create a new deployment profile of type "Kubernetes" for your open-appsec deployment. When you configure the profile, make sure to select the correct subtype "Envoy Gateway Application Security". Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below.

Create a Profile

Known Limitations

As this is an alpha version there are are some limitations which will be resolved in future versions.

Support for Helm-based installation: Currently only installations with Envoy Gateway Operator are supported
No support for standalone deployments: You must provide token to connect to central web UI. You currently have two management options available to be used with central web UI:
- Declarative mode (set management mode to "Declarative configuration" in web UI profile), here you manage your open-appsec deployment locally using custom resources/CRDs and see your current configuration represented in read-only also in the central web UI, as well as status monitoring and optional central security logging/reporting.
- Centrally managed mode (set management mode to "This management" in web UI profile), here you manage your configuration centrally, have central status monitoring and optional central security logging/reporting.

Deployment

The integration has two key components:

open-appsec "attachment" filter, this lightweight Envoy filter must be present on the Envoy Proxy, as it's providing the traffic to the open-appsec agent for security inspection, then receives the decisions (e.g. allow or block) from the agent and finally enforces these decisions accordingly.
open-appsec "agent", the agent, running in K8s as a side-car container to the Envoy Proxy container, receives traffic from the "attachment", performs the actual security inspection using the contextual machine learning engine and takes decisions whether HTTP requests are malicious or benign. It then notifies the "attachment" about those decisions.

The deployment of the attachment is performed using an init container which deliver the files for the attachment filter to a shared volume which the envoy proxy container can then access.

When using the deployment instructions below the official envoy contrib image remains unchanged!

Step 1: Create a patch file in your Kubernetes environment

Create an envoyproxy-deployment-patch.yaml patch file in your Kubernetes environment with the following contents:

envoyproxy-deployment-patch.yaml

spec:
  provider:
    kubernetes:
      envoyDeployment:
        patch:
          type: StrategicMerge
          value:
            spec:
              template:
                spec:
                  initContainers:
                    - name: envoy-attachments
                      image: ghcr.io/openappsec/openappsec-envoy-filters:latest
                      imagePullPolicy: Always
                      command: ["/prepare_attachment.sh"]
                      env:
                        - name: ENVOY_VERSION
                          value: "1.34"
                      volumeMounts:
                        - name: attachment-shared
                          mountPath: /envoy/attachment/shared
                  containers:
                    - name: envoy
                      env:
                        - name: LD_LIBRARY_PATH
                          value: /usr/lib/attachment
                      volumeMounts:
                        - name: attachment-shared
                          mountPath: /usr/lib/attachment
                    - name: openappsec-agent
                      image: ghcr.io/openappsec/agent:1.1.29
                      imagePullPolicy: IfNotPresent
                      command:
                        - /cp-nano-agent
                      env:
                        - name: AGENT_TOKEN
                          value: <token>
                        - name: registered_server
                          value: "Envoy Gateway"
                        - name: user_email
                          value: "<your-email-address>"
                      volumeMounts:
                        - name: agent-config
                          mountPath: /etc/cp/conf
                        - name: agent-data
                          mountPath: /etc/cp/data
                        - name: agent-logs
                          mountPath: /var/log/nano_agent
                      resources:
                        limits:
                          cpu: 200m
                          memory: 256Mi
                        requests:
                          cpu: 100m
                          memory: 128Mi
                      securityContext:
                        runAsUser: 0
                  volumes:
                    - name: attachment-shared
                      emptyDir: {}
                    - name: agent-config
                      emptyDir: {}
                    - name: agent-data
                      emptyDir: {}
                    - name: agent-logs
                      emptyDir: {}

Step 2: Adjust the patch file configuration

Adjust the following parameters in the patch file:

<your-email-address> allows you to associate your email address with your specific deployment by replace this with your own email address.

This allows us to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

<token> (mandatory in the current alpha version of this integration) set the deployment profile token from central management WebUI (SaaS) to connect your open-appsec deployment to the central WebUI (SaaS), which you created according to the instructions in the prerequisites section at the top of this page. (You can see here how to get the token: create a profile in web UI)

ENVOY_VERSION allows adjustment of the Envoy Proxy version which is set with the key of the ENVOY_VERSION environment variable.

Step 3: Patch the envoyProxy resource to add open-appsec agent and attachment filter

Now apply the patch file to your deployment of envoy gateway after adjusting the parameters (see below):

kubectl patch envoyproxy <envoyProxy resource name> --namespace <envoy gateway namespace> --type=merge --patch-file envoyproxy-patch.yaml

Replace the following parameters with your own values:

<envoyProxy resource name> replace with the name of the envoyProxy resource of the envoy gateway to which you want to add open-appsec to

<envoy gateway namespace> replace with the name of the namespace of your envoy gateway namespace

Step 4: Patch the envoy configuration to load the open-appsec attachment filter

Ensure that enableEnvoyPatchPolicy is enabled in your Envoy Gateway config map or Helm values. This is required in order to apply the EnvoyPatchPolicy resource.

Create a file EnvoyPatchPolicy.yaml with the content below:

EnvoyPatchPolicy.yaml

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyPatchPolicy
metadata:
  name: insert-go-filter
  namespace: <gateway resource namespace>
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: <gateway resource name>
  type: JSONPatch
  jsonPatches:
    - type: type.googleapis.com/envoy.config.listener.v3.Listener
      name: <gateway resource namespace>/<gateway resource name>/http
      operation:
        op: add
        path: "/default_filter_chain/filters/0/typed_config/http_filters/0"
        value:
          name: envoy.filters.http.golang
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
            library_id: cp_nano_filter
            plugin_name: cp_nano_filter
            library_path: /usr/lib/attachment/libenvoy_attachment.so
            plugin_config:
              "@type": type.googleapis.com/xds.type.v3.TypedStruct
              value:
                prefix_localreply_body: "hello from go filter"

Replace the following parameters in the EnvoyPatchPolicy.yaml file with your own values:

<gateway resource namespace> replace with the name of the namespace of the gateway resource

<gateway resource name> replace with the name of the gateway resource

Apply the adjusted EnvoyPatchPolicy.yaml file:

kubectl apply -f EnvoyPatchPolicy.yaml -n <gateway resource namespace>

Replace the following parameter in the command with your own value: <gateway resource namespace> replace with the name of the namespace of your envoy gateway resource

Step 5: If you connected to central WebUI AND configured your deployment profile in the WebUI to "This management" mode for centrally managing open-appsec configuration:

Create one or more assets in the WebUI which represent web applications and/or Web APIs which you want to be protected by open-appsec WAF and allows you to adjust the open-appsec configuration specifically for each of them. Make sure to link your assets to the specific WebUI Profile which you created earlier (General -> Profiles) and adjust the Threat Prevention mode to Detect-Learn or Prevent (Threat Prevention -> Mode), the steps are described here: Protect Additional Assets

Make sure to configure the web application URLs for your open-appsec assets for the correct ports on which the envoy container is receiving the traffic. Usually these would be: For HTTP: 10080 For HTTPS: 10443

Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective!

The following steps 6-10 are only relevant if you want to locally manage this open-appsec deployment in Kubernetes using a declarative configuration using custom resources.

This applies if you provided a deployment profile token earlier for a WebUI profile set to mode "Declarative Management".

Step 6: (only for locally-managed deployments) Download the yaml file for open-appsec CRD installation

Run the following command to obtain the yaml file containing the open-appsec CRD definitions: v1beta2 CRDs:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/crds/open-appsec-crd-v1beta2.yaml

Step 7: (only for locally-managed deployments) Create the open-appsec CRDs which add new K8s resource-types that will be used later for defining the protection policies, log settings, exceptions, user response and more.

You can skip this step if you skipped the previous step, because in that case you plan to centrally manage open-appsec from central WebUI and not manage it locally using CRDs.

Deploy the CRDs using the following command:

kubectl apply -f ./open-appsec-crd-v1beta2.yaml

Step 8: (only for locally-managed deployments) Download a default configuration for the open-appsec custom resources

Run the following command to obtain the yaml file containing the open-appsec default configuration custom resources, chose the CRD version which you have deployed in the steps above on your cluster. Default configuration for v1beta2 in detect-learn mode:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-default-config-v1beta2.yaml

The default configuration files provided above are set to detect-learn mode, which is recommended for new deployments to allow the machine learning engine sufficient learning before moving to prevent-learn mode. You can then later easily reconfigure the open-appsec-best-practice-policy custom policy resource to prevent-learn mode. If you would like to start in prevent-mode in non-critical environment for testing purposes right away, you can alternatively use these files, which are preconfigured to prevent-learn mode: Default configuration for v1beta2 in prevent-mode

wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/k8s/v1beta2/open-appsec-k8s-prevent-config-v1beta2.yaml

Step 9: (only for locally-managed deployments) Deploy default configuration for the open-appsec custom resources

To deploy the default configuration for the open-appsec custom resources perform the step below:

Default configuration for v1beta2:

kubectl apply -f ./open-appsec-k8s-default-config-v1beta2.yaml

Step 10: (only relevant for locally-managed deployments) Configure open-appsec protection using custom resources

a. Make sure to have an open-appsec Policy resource

If you followed the steps above you should now have an open-appsec-best-practice-policy custom resource deployed on your K8s cluster. You can check this with the following command which will list all open-appsec policy custom resources:

kubectl get policies.openappsec.io

If you want to check if it's set to detect-learn (default) or prevent-learn mode you can use this command (the name of the policy created by the default configuration in v1beta2 is default-policy):

kubectl get policies.openappsec.io default-policy -o yaml

If you want to create your own custom policy, you find all details here:

For v1beta2 CRDs: Configuration Using CRDs - v1beta2

b. Create a PolicyActivation resource Using a PolicyActivation custom resource you can now specify that your existing open-appsec policy (e.g. default-policy, see above) should be applied to all traffic matching the hostname example.com. (You can have multiple Policy custom resources and also multiple PolicyActivation custom resources)

Create a new file policy-activation.yaml to specify a new PolicyActivation custom resource similar to the below specification (change example.com to your own hostname, adjust default-policy if you want to reference another Policy custom resource instead of the default one):

apiVersion: openappsec.io/v1beta2
kind: PolicyActivation
metadata:
  name: policy-activation-example
spec:
  enabledPolicies:
    - name: default-policy
      hosts:
        - "example.com"

Then apply it to your Kubernetes cluster using:

kubectl apply -f policyactivation.yaml

If you want to create your own PolicyActivation custom resource, you find all details here:

For v1beta2 CRDs: Configuration Using CRDs - v1beta2

Validate the Deployment:

Your reverse proxy is now protected with open-appsec (in detect or prevent mode)!

Generate some traffic to one of the services defined by your gateway resources.
Run this command to see logs:

Note the name of your envoy gateway pod by running:

kubectl get pods -n <envoy gateway deployment namespace>

Then show the logs of the open-appsec agent container by running:

kubectl logs <envoy gateway deployment pod name> -c openappsec-agent -n <envoy gateway deployment namespace>

PreviousInstall With Helm using Webhook NextConfiguration Using CRDs

Last updated 48 minutes ago

Was this helpful?