diff options
Diffstat (limited to 'docs/release/configguide/modsecurity_config_guide.rst')
| -rw-r--r-- | docs/release/configguide/modsecurity_config_guide.rst | 294 |
1 files changed, 294 insertions, 0 deletions
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. |