path: root/docs/release/configguide/modsecurity_config_guide.rst

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