summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/release/configguide/imgs/istio_gateway.pngbin0 -> 3985370 bytes
-rw-r--r--docs/release/configguide/modsecurity_config_guide.rst294
-rw-r--r--samples/scenarios/ingressgateway_ext_authz_filter.yaml (renamed from samples/scenarios/istio_ingressgateway_envoyfilter.yaml)6
-rw-r--r--samples/scenarios/modsecurity_all_in_one.yaml65
-rw-r--r--samples/services/modsecurity/yaml/manifest.template2
-rw-r--r--samples/services/modsecurity/yaml/modsecurity-deployment.yaml1
-rw-r--r--samples/services/modsecurity/yaml/modsecurity-service.yaml1
-rw-r--r--samples/services/modsecurity/yaml/render_yaml.py4
8 files changed, 370 insertions, 3 deletions
diff --git a/docs/release/configguide/imgs/istio_gateway.png b/docs/release/configguide/imgs/istio_gateway.png
new file mode 100644
index 0000000..f96212e
--- /dev/null
+++ b/docs/release/configguide/imgs/istio_gateway.png
Binary files differ
diff --git a/docs/release/configguide/modsecurity_config_guide.rst b/docs/release/configguide/modsecurity_config_guide.rst
new file mode 100644
index 0000000..7b1c6cf
--- /dev/null
+++ b/docs/release/configguide/modsecurity_config_guide.rst
@@ -0,0 +1,294 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier CC-BY-4.0
+.. (c) Authors of Clover
+
+.. _modsecurity_config_guide:
+
+=========================================
+ModSecurity Configuration Guide
+=========================================
+
+This document provides a guide to setup the ModSecurity web application firewall
+as a security enhancement for the Istio ingressgateway.
+
+
+ModSecurity Overview
+=====================
+
+ModSecurity is an open source web application firewall. Essentially, ModSecurity
+is an Apache module that can be added to any compatible version of Apache. To
+detect threats, the ModSecurity engine is usually deployed embedded within the
+webserver or as a proxy server in front of a web application. This allows the
+engine to scan incoming and outgoing HTTP communications to the endpoint.
+
+In Clover, we deploy ModSecurity on an Apache server and running it as a
+Kubernetes service that reside in "clover-gateway" namespace.
+
+ModSecurity provides very little protection on its own. In order to become
+useful, ModSecurity must be configured with rules. Dependent on the rule
+configuration the engine will decide how communications should be handled which
+includes the capability to pass, drop, redirect, return a given status code,
+execute a user script, and more.
+
+In Clover, we choose the OWASP ModSecurity Core Rule Set (CRS) for use with
+ModSecurity.
+
+The OWASP ModSecurity Core Rule Set (CRS) is a set of generic attack detection
+rules. The CRS aims to protect web applications from a wide range of attacks,
+including the OWASP Top Ten, with a minimum of false alerts.
+
+
+Ingress traffic security enhancement
+======================================
+
+In a typical Istio service mesh, ingressgateway terminates TLS from external
+networks and allows traffic into the mesh.
+
+.. image:: imgs/istio_gateway.png
+ :align: center
+ :scale: 100%
+
+Clover enhances the security aspect of ingressgateway by redirecting all incoming
+HTTP requests through the ModSecurity WAF. To redirect HTTP traffic to the ModSecurity,
+Clover enables ext_authz (external authorization) Envoy filter on the ingressgateway.
+
+For all incoming HTTP traffic, the ext_authz filter will authenticate each ingress
+request with the ModSecurity service. To perform authentication, an HTTP subrequest
+is sent from ingressgateway to ModSecurity where the subrequest is verified. If
+the subrequest is clean, ModSecurity will return a 2xx response code, access is
+allowed; If it returns 401 or 403, access is denied.
+
+
+Deploying the ModSecurity WAF
+==============================
+
+.. _modsecurity_prerequisites:
+
+Prerequisites
+-------------
+
+The following assumptions must be met before continuing on to deployment:
+
+ * Installation of Kubernetes has already been performed.
+ * Installation of Istio and Istio client (istioctl) is in your PATH.
+
+Deploy from source
+------------------
+
+Clone the Clover git repository and navigate within the samples directory as
+shown below:
+
+.. code-block:: bash
+
+ $ git clone https://gerrit.opnfv.org/gerrit/clover
+ $ cd clover/samples/scenarios
+ $ git checkout stable/gambia
+
+To deploy the ModSecurity WAF in the "clover-gateway" Kubernetes namespace, use
+the following command:
+
+.. code-block:: bash
+
+ $ kubectl create namespace clover-gateway
+ $ kubectl apply -n clover-gateway -f modsecurity_all_in_one.yaml
+
+Verifying the deployment
+------------------------
+
+To verify the ModSecurity pod is deployed, executing the command below:
+
+.. code-block:: bash
+
+ $ kubectl get pod -n clover-gateway
+
+The listing below must include the following ModSecurity pod:
+
+.. code-block:: bash
+
+ $ NAME READY STATUS RESTARTS AGE
+ modsecurity-crs-cf5fffcc-whwqm 1/1 Running 0 1d
+
+To verify the ModSecurity service is created, executing the command below:
+
+.. code-block:: bash
+
+ $ kubectl get svc -n clover-gateway
+
+The listing below must include the following ModSecurity service:
+
+.. code-block:: bash
+
+ $ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+ modsecurity-crs NodePort 10.233.11.72 <none> 80:31346/TCP 1d
+
+To verify the ext-authz Envoy filter is created, executing the command below:
+
+.. code-block:: bash
+
+ $ istioctl get envoyfilter -n clover-gateway
+
+The listing below must include the following Envoy filter:
+
+.. code-block:: bash
+
+ $ NAME KIND NAMESPACE AGE
+ ext-authz EnvoyFilter.networking.istio.io.v1alpha3 istio-system 1d
+
+
+ModSecurity configuration
+==========================
+
+OWASP ModSecurity CRS mode
+---------------------------
+
+The OWASP ModSecurity CRS can run in two modes:
+
+* **Anomaly Scoring Mode** - In this mode, each matching rule increases an
+'anomaly score'. At the conclusion of the inbound rules, and again at the
+conclusion of the outbound rules, the anomaly score is checked, and the blocking
+evaluation rules apply a disruptive action, by default returning an error 403.
+
+* **Self-Contained Mode** - In this mode, rules apply an action instantly. Rules
+inherit the disruptive action that you specify (i.e. deny, drop, etc). The first
+rule that matches will execute this action. In most cases this will cause evaluation
+to stop after the first rule has matched, similar to how many IDSs function.
+
+By default, the CRS runs in Anomally scoring mode.
+
+You can configurate CRS mode by editing the **crs-setup.conf** in the modsecurity-crs
+container:
+
+.. code-block:: bash
+
+ $ kubectl exec -t -i -n clover-gateway [modsecurity-crs-pod-name] -c modsecurity-crs -- bash
+ $ vi /etc/apache2/modsecurity.d/owasp-crs/crs-setup.conf
+
+Alert logging
+-------------
+
+By default, CRS enables all detailed logging to the ModSecurity audit log.
+You can check the audit log using the command below:
+
+.. code-block:: bash
+
+ $ kubectl exec -t -i -n clover-gateway [modsecurity-crs-pod-name] -c modsecurity-crs -- cat /var/log/modsec_audit.log
+
+CRS Rules
+---------
+
+By default, Clover enables all OWASP CRS rules. Below is a short description of all enabled rules:
+
+* **REQUEST-905-COMMON-EXCEPTIONS**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-905-COMMON-EXCEPTIONS.conf
+
+Some rules are quite prone to causing false positives in well established software,
+such as Apache callbacks or Google Analytics tracking cookie. This file offers
+rules that will allow the transactions to avoid triggering these false positives.
+
+* **REQUEST-910-IP-REPUTATION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-910-IP-REPUTATION.conf
+
+These rules deal with detecting traffic from IPs that have previously been involved
+with malicious activity, either on our local site or globally.
+
+* **REQUEST-912-DOS-PROTECTION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-912-DOS-PROTECTION.conf
+
+The rules in this file will attempt to detect some level 7 DoS (Denial of Service)
+attacks against your server.
+
+* **REQUEST-913-SCANNER-DETECTION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-913-SCANNER-DETECTION.conf
+
+These rules are concentrated around detecting security tools and scanners.
+
+
+* **REQUEST-920-PROTOCOL-ENFORCEMENT**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf
+
+The rules in this file center around detecting requests that either violate HTTP
+or represent a request that no modern browser would generate, for instance missing
+a user-agent.
+
+* **REQUEST-921-PROTOCOL-ATTACK**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-921-PROTOCOL-ATTACK.conf
+
+The rules in this file focus on specific attacks against the HTTP protocol itself
+such as HTTP Request Smuggling and Response Splitting.
+
+* **REQUEST-930-APPLICATION-ATTACK-LFI**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf
+
+These rules attempt to detect when a user is trying to include a file that would
+be local to the webserver that they should not have access to. Exploiting this type
+of attack can lead to the web application or server being compromised.
+
+* **REQUEST-931-APPLICATION-ATTACK-RFI**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf
+
+These rules attempt to detect when a user is trying to include a remote resource
+into the web application that will be executed. Exploiting this type of attack can
+lead to the web application or server being compromised.
+
+
+* **REQUEST-941-APPLICATION-ATTACK-SQLI**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-941-APPLICATION-ATTACK-SQLI.conf
+
+Within this configuration file we provide rules that protect against SQL injection
+attacks. SQL attackers occur when an attacker passes crafted control characters
+to parameters to an area of the application that is expecting only data. The
+application will then pass the control characters to the database. This will end
+up changing the meaning of the expected SQL query.
+
+* **REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf
+
+These rules focus around providing protection against Session Fixation attacks.
+
+* **REQUEST-949-BLOCKING-EVALUATION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf
+
+These rules provide the anomaly based blocking for a given request. If you are in
+anomaly detection mode this file must not be deleted.
+
+* **RESPONSE-954-DATA-LEAKAGES-IIS**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf
+
+These rules provide protection against data leakages that may occur because of Microsoft IIS
+
+
+* **RESPONSE-952-DATA-LEAKAGES-JAVA**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf
+
+These rules provide protection against data leakages that may occur because of Java
+
+
+* **RESPONSE-953-DATA-LEAKAGES-PHP**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf
+
+These rules provide protection against data leakages that may occur because of PHP
+
+
+* **RESPONSE-950-DATA-LEAKAGES**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-950-DATA-LEAKAGES.conf
+
+These rules provide protection against data leakages that may occur genericly
+
+* **RESPONSE-951-DATA-LEAKAGES-SQL**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf
+
+These rules provide protection against data leakages that may occur from backend
+SQL servers. Often these are indicative of SQL injection issues being present.
+
+* **RESPONSE-959-BLOCKING-EVALUATION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-959-BLOCKING-EVALUATION.conf
+
+These rules provide the anomaly based blocking for a given response. If you are
+in anomaly detection mode this file must not be deleted.
+
+* **RESPONSE-980-CORRELATION**
+Configuration Path: /etc/apache2/modsecurity.d/owasp-crs/rules/RESPONSE-980-CORRELATION.conf
+
+The rules in this configuration file facilitate the gathering of data about
+successful and unsuccessful attacks on the server.
diff --git a/samples/scenarios/istio_ingressgateway_envoyfilter.yaml b/samples/scenarios/ingressgateway_ext_authz_filter.yaml
index 46f730c..0960a50 100644
--- a/samples/scenarios/istio_ingressgateway_envoyfilter.yaml
+++ b/samples/scenarios/ingressgateway_ext_authz_filter.yaml
@@ -2,7 +2,7 @@ apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
name: ext-authz
- namespace: istio-system
+ namespace: clover-gateway
spec:
workloadLabels:
app: istio-ingressgateway
@@ -18,7 +18,7 @@ spec:
filterConfig:
http_service:
server_uri:
- uri: "http://modsecurity-crs.istio-system.svc.cluster.local"
- cluster: "outbound|80||modsecurity-crs.istio-system.svc.cluster.local"
+ uri: "http://modsecurity-crs.clover-gateway.svc.cluster.local"
+ cluster: "outbound|80||modsecurity-crs.clover-gateway.svc.cluster.local"
timeout: 0.5s
failure_mode_allow: false
diff --git a/samples/scenarios/modsecurity_all_in_one.yaml b/samples/scenarios/modsecurity_all_in_one.yaml
new file mode 100644
index 0000000..aa92b13
--- /dev/null
+++ b/samples/scenarios/modsecurity_all_in_one.yaml
@@ -0,0 +1,65 @@
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+ name: modsecurity-crs
+ namespace: clover-gateway
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: modsecurity-crs
+ template:
+ metadata:
+ labels:
+ app: modsecurity-crs
+ spec:
+ containers:
+ - name: modsecurity-crs
+ image: clover/clover-ns-modsecurity-crs
+ ports:
+ - containerPort: 80
+ env:
+ - name: PARANOIA
+ value: '1'
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: modsecurity-crs
+ namespace: clover-gateway
+spec:
+ type: NodePort
+ ports:
+ - port: 80
+ name: http-modsecurity-crs
+ protocol: TCP
+ targetPort: 80
+ selector:
+ app: modsecurity-crs
+---
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+ name: ext-authz
+ namespace: clover-gateway
+spec:
+ workloadLabels:
+ app: istio-ingressgateway
+ filters:
+ - insertPosition:
+ index: FIRST
+ listenerMatch:
+ portNumber: 80
+ listenerType: GATEWAY
+ listenerProtocol: HTTP
+ filterType: HTTP
+ filterName: "envoy.ext_authz"
+ filterConfig:
+ http_service:
+ server_uri:
+ uri: "http://modsecurity-crs.clover-gateway.svc.cluster.local"
+ cluster: "outbound|80||modsecurity-crs.clover-gateway.svc.cluster.local"
+ timeout: 0.5s
+ failure_mode_allow: false
+---
diff --git a/samples/services/modsecurity/yaml/manifest.template b/samples/services/modsecurity/yaml/manifest.template
index afeb9dc..2206e6d 100644
--- a/samples/services/modsecurity/yaml/manifest.template
+++ b/samples/services/modsecurity/yaml/manifest.template
@@ -3,6 +3,7 @@ apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: {{ deploy_name }}
+ namespace: {{ deploy_namespace }}
labels:
app: {{ deploy_name }}
spec:
@@ -26,6 +27,7 @@ apiVersion: v1
kind: Service
metadata:
name: {{ deploy_name }}
+ namespace: {{ deploy_namespace }}
labels:
app: {{ deploy_name }}
spec:
diff --git a/samples/services/modsecurity/yaml/modsecurity-deployment.yaml b/samples/services/modsecurity/yaml/modsecurity-deployment.yaml
index 450ede5..1e88f30 100644
--- a/samples/services/modsecurity/yaml/modsecurity-deployment.yaml
+++ b/samples/services/modsecurity/yaml/modsecurity-deployment.yaml
@@ -2,6 +2,7 @@ apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: modsecurity-crs
+ namespace: clover-gateway
spec:
replicas: 1
selector:
diff --git a/samples/services/modsecurity/yaml/modsecurity-service.yaml b/samples/services/modsecurity/yaml/modsecurity-service.yaml
index 8548dca..7432630 100644
--- a/samples/services/modsecurity/yaml/modsecurity-service.yaml
+++ b/samples/services/modsecurity/yaml/modsecurity-service.yaml
@@ -2,6 +2,7 @@ apiVersion: v1
kind: Service
metadata:
name: modsecurity-crs
+ namespace: clover-gateway
spec:
type: NodePort
ports:
diff --git a/samples/services/modsecurity/yaml/render_yaml.py b/samples/services/modsecurity/yaml/render_yaml.py
index 54f8069..67622d6 100644
--- a/samples/services/modsecurity/yaml/render_yaml.py
+++ b/samples/services/modsecurity/yaml/render_yaml.py
@@ -22,6 +22,7 @@ def render_yaml(args):
image_name=args['image_name'],
image_tag=args['image_tag'],
deploy_name=args['deploy_name'],
+ deploy_namespace=args['deploy_namespace'],
http_port=args['http_port'],
paranoia_level=args['paranoia_level']
)
@@ -49,6 +50,9 @@ if __name__ == '__main__':
'--deploy_name', default='modsecurity-crs',
help='The k8s deploy name to use')
parser.add_argument(
+ '--deploy_namespace', default='clover-gateway',
+ help='The k8s namespace to deploy pod and service')
+ parser.add_argument(
'--http_port', default='80',
help='Analyze http traffic on this port')
parser.add_argument(