Install Using Helm (Istio)

The steps described here to deploy open-appsec on Kubernetes with Istio integration are currently in beta.

The steps described on this page explain how to deploy and integrate open-appsec with an existing Istio Ingress Gateway deployment 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

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

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

Optional (Recommended)

To manage your open-appsec WAF deployment—either centrally via WebUI (SaaS) or locally with optional read-only WebUI monitoring—follow these steps:

• 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: Deploy open-appsec Helm Chart for Istio

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

helm install open-appsec-istio openappsec/open-appsec-istio \
--set webhook.objectSelector.labelValue=istio-ingress \
--set webhook.objectSelector.labelName=app \
--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 below.

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 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.

Step 3: Enable open-appsec Injection on Istio Ingress Gateway

To allow open-appsec to inspect traffic through your Istio ingress 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 Istio ingress gateway:

   kubectl label namespace [istio ingress gateway namespace] inject-waf-attachment="true" --overwrite

2. Label the Deployment Ensure your Istio ingress deployment has the required labels as configured in your webhook.objectSelector:

   • webhook.objectSelector.labelKey

   • 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 Istio Ingress Deployment The restart injects the open-appsec attachment into the istio ingress gateway container, and open-appsec agent container into all existing istio ingress gateway pods, by using a Kubernetes mutating webhook to adjust the deployment.

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

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

• During restart, the open-appsec attachment is injected into the existing ingress gateway container.

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

If you want to remove the attachment later again, you can set inject-waf-attachment to false and perform another rollout restart of the deployment.

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

kubectl get pods -n [istio ingress gateway namespace]

The READY column should show 2/2 for each istio ingress gateway pod and 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 Using Helm (Istio)

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 Istio ingress gateway is now protected with open-appsec (in detect or prevent mode)!

1. Generate some traffic to one of the services defined by your Istio Gateway and VirtualService resources.

2. Run this command to see logs:

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

kubectl get pods -n [istio ingress gateway namespace]

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

kubectl logs [istio ingress gateway pod name] -c open-appsec -n appsec