Install With Helm using Webhook

The installation steps on this page apply to following supported open-appsec integrations:

• Istio Ingress Controller (currently in beta)

• Kong, new integration using native, Lua-based open-appsec attachment plugin (currently in beta)

For all other open-appsec integrations on Kubernetes see: Install Using Helm - new flow (beta)

Let us know if you have any feedback regarding these beta programs or require technical assistance: mailto://[email protected]

The open-appsec integration with Kong as shown on this page is for the newer, more flexible version of the Kong open-appsec integration which is based on using a Lua plugin. This is a more native integration than the traditional plugin (also still available, but will be deprecated in the future) and is following the official Kong plugin guidelines.

As this is a regular Kong plugin, you must make sure to also configure the plugin to apply to your traffic (e.g. all traffic, specific routes, etc.), as otherwise the open-appsec agent will not receive the traffic for inspection. You find all required info below in the documentation

The steps described on this page explain how to deploy and integrate open-appsec on Kubernetes:

• with an existing Istio Ingress Gateway already deployed on Kubernetes

• with an existing Kong API Gateway already deployed on Kubernetes

Prerequisites

• Kubernetes 1.16.0+ cluster with RBAC enabled with Cluster admin permissions

• Helm 3 Package Manager installed on your local machine

• kubectl and wget command-line tools installed on the system that you use to access the Kubernetes cluster

• For Istio:

  • An existing deployment of Istio Ingress Gateway. Supported versions: 1.23 - 1.26

  • You should have an understanding of Istio Kubernetes CRD types "Virtual Service" and "Gateway"

• For Kong:

  • An existing deployment of Kong API Gateway.

  • You should have an understanding of Kubernetes "Ingress"

Optional (Recommended)

To use the open-appsec central management web UI for managing your open-appsec WAF deployment — either centrally via WebUI (SaaS) or locally with optional read-only WebUI monitoring — follow these steps (not required if you plan to manage your deployment only locally, declaratively):

• Sign Up / Log In Go to https://my.openappsec.io and sign up or log in to access the WebUI.

Sign-Up and Login to Portal

• Create a Deployment Profile Once logged in, create a new deployment profile for your open-appsec setup. Important: After completing policy installation, copy the profile token—you’ll need it in the installation steps that follow.

Create a Profile

Installation

Step 1: Add the Helm Repo

Please note that this new installation flow with helm uses a different helm chart.

helm repo add openappsec https://charts.openappsec.io
helm repo update

Step 2: Deployment

Istio

Run the following command to deploy the open-appsec helm chart into your Istio Ingress Controller namespace:

helm install open-appsec-webhook openappsec/open-appsec-injector \
--set webhook.objectSelector.labelValue=istio-ingress \
--set webhook.objectSelector.labelName=app \
--set kind=istio \
--set appsec.persistence.enabled=false \
--set gateways.istio-ingressgateway.service.externalTrafficPolicy=Local \
--set appsec.userEmail=<your-email-address> \
--set appsec.agentToken= \
-n [istio ingress gateway namespace]

Before running the installation command, make sure to update the placeholders according to your environment:

• istio ingress gateway namespace - Replace this with the namespace of your existing Istio ingress gateway deployment.

• appsec.agentToken - If you are connecting to the central WebUI, add the profile token you received after creating a deployment profile in the WebUI.

  • For standalone deployments leave parameter empty

• appsec.userEmail - Replace <your-email-address> with your own email address.

open-appsec will now be deployed into the existing namespace of your istio ingress gateway.

If you have persistent storage available in your cluster please set the --set appsec.persistence.enabled=false parameter in the following command to true to allow open-appsec to use persistent storage for the learning. This is only shown for maximum compatibility reasons.

Optional open-appsec helm install parameters

• -n <istio ingress gateway namespace>: select the existing namespace name of the istio ingress gateway deployment to which open-appsec should be added and integrated with.

The open-appsec-waf-injector is using a label in the istio ingress gateway deployment to identify those pods, to which the open-appsec agent container should be automatically added (via mutating webhook). In addition it adds and loads our attachment module as a filter in the istio ingress gateway container, allowing the open-appsec agent to inspect traffic arriving at the istio ingress gateway. In case of the default value an open-appsec agent container will e.g. be added to each istio ingress gateway pod which has the following label set: app: istio-ingress Two parameters are available that allow you to customize the name and value of that label.

• --set kind: specify the integration you want to deploy, for Istio make sure to select istio as value.

• --set webhook.objectSelector.labelName : specify the name of the label (default name is app) which is used to identify the deployment istio ingress gateway deployment to which the open-appsec attachment should be automatically injected.

• --set webhook.objectSelector.labelValue : specify the value of the label (default is istio-ingress) which is used to identify the istio ingress gateway deployment to which the open-appsec attachment should be automatically injected.

• --set appsec.userEmail: allows you to associate your email address with your specific deployment by replacing <your-email-address> 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.

• --set appsec.persistence.enabled: persistent volume includes machine learning information, if this is set to false then machine learning information is lost when the appsec container is stopped/restarted.

  • true: default is true

  • false

  If this value is set to true (default, when not overriding with false) you must also specify appsec.persistence.learning.storageClass

• --set appsec.persistence.learning.storageClass: Specify storage class to be used for the learning pod. Note: storageClass name specified here must support ReadWriteMany (like AWS EFS or Azure Files).

• --set appsec.agentToken: set the deployment profile token from central management WebUI (SaaS) to connect your open-appsec deployment to the central WebUI (SaaS), see here how to get the token: create a profile in web UI. If you don't set this then your deployment will be in standalone mode.

• --set gateways.istio-ingressgateway.service.externalTrafficPolicy=Local recommended for preserving original IP address by making sure that traffic for the loadbalancer service is only routed to pods on the same node.

For additional available configuration values please check the values.yaml within the downloaded Helm chart and the Ingress Ingress Gateways documentation available here.

Kong

Step 3: Enable open-appsec Injection to the existing deployment

To allow open-appsec to inspect the traffic through your existing Istio Ingress or Kong gateway, it must be attached to the existing deployment. This happens automatically if the proper labels are set and the deployment is restarted.

1. Label the Namespace Add the inject-waf-attachment=true label to the namespace of your existing reverse proxy deployment (e.g. Istio Ingress Gateway or Kong):

   kubectl label namespace [existing reverse proxy deployment namespace] inject-waf-attachment="true" --overwrite

2. Label the Deployment Ensure your current reverse proxy deployment has the required labels set as configured in your webhook.objectSelector:

   • webhook.objectSelector.labelName

   • webhook.objectSelector.labelValue

   (These labels must match what’s configured in the open-appsec Helm chart. Refer to your Helm values or the section above for details.)

3. Restart the existing reverse proxy deployment

Restart your existing deployment by using the following command:

kubectl rollout restart deployment [istio ingress gateway deployment name] -n [istio ingress gateway namespace]

Here's what happens when you restart the deployment:

• The inject-waf-attachment label enables open-appsec to patch the existing deployment.

• An open-appsec agent container is injected additionally into each pod using a Kubernetes mutating webhook.

• In case of Istio: During restart, the open-appsec attachment is injected into the existing ingress gateway container.

If you want to remove the agent (Istio or Kong) and injected attachment (Istio only) later again, you can set inject-waf-attachment to false and perform another rollout restart of the deployment so it gets removed again.

Step 4: Validate that open-appsec is installed and running

kubectl get pods -n [reverse proxy deployment namespace]

The READY column should now show an additional container running in your proxy pod and should show 1/1 for each of the following pods: waf injector, learning deployment (only in standalone deployment), shared storage deployment (only in standalone deployment).

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

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.

They apply to the following two cases:

• You do not want to connect to central WebUI at all (you didn't provide a deployment profile token earlier)

• You provided deployment profile token earlier for a WebUI profile set to mode "Declarative Management"

If you are not managing your deployment locally, scroll down to Install With Helm using Webhook

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, choose the CRD version you want to use. 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 you plan to centrally manage open-appsec from central WebUI and not manage it locally using CRDs.

Deploy the CRDs using the following command:

For the v1beta2 CRDs:

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 (beta) 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 (beta):

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

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

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)!

1. In case of Istio: Generate some traffic to one of the services defined by your Istio Gateway and VirtualService resources In case of Kong: Generate some traffic to e.g. the web resource specified in your K8s ingress resource.

2. Run this command to see logs:

Note the name of an Istio ingress gateway pod by running:

kubectl get pods -n [reverse proxy deployment namespace]

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

kubectl logs [reverse proxy deployment pod name] -c open-appsec -n [reverse proxy deployment namespace]