Merge branch 'fern-defend-tutorial' into 'master'

Create Guide on installation/usage of Defend WAF

See merge request gitlab-org/gitlab!18676

doc/topics/web_application_firewall/index.md

+# Web Application Firewall - ModSecurity
+
+A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to
+and from a web application. By inspecting HTTP traffic, it can prevent attacks
+stemming from web application security flaws. It can be used to detect SQL injection,
+Cross-Site Scripting (XSS), Remote File Inclusion, Security Misconfigurations, and
+much more.
+
+## Overview
+
+GitLab provides a WAF out of the box after Ingress is deployed.
+All you need to do is deploy your application along with a service
+and Ingress resource.
+
+In GitLab's [Ingress](../../user/clusters/applications.md#ingress) deployment, the [ModSecurity](https://modsecurity.org/) module is loaded
+into Ingress-NGINX by default and monitors the traffic going to the
+applications which have an Ingress.
+
+The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) by default. The OWASP CRS will detect and log a wide range of common attacks.
+
+NOTE: **Note**
+The WAF is deployed in "Detection-only mode" by default and will only log attack
+attempts.
+
+## Requirements
+
+The Web Application Firewall requires:
+
+- **Kubernetes**
+
+  To enable the WAF, you need:
+
+  - Kubernetes 1.12+.
+  - A load balancer. You can use NGINX-Ingress by deploying it to your
+    Kubernetes cluster by either:
+    - Using the [`nginx-ingress` Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress).
+    - Installing the [Ingress GitLab Managed App](../../user/clusters/applications.md#ingress) with WAF enabled.
+
+- **Configured Kubernetes objects**
+
+  To use the WAF on an application, you need to deploy the following Kubernetes resources:
+
+  - [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
+  - [Service](https://kubernetes.io/docs/concepts/services-networking/service/)
+  - [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+
+## Quick start
+
+If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) for
+how to use the WAF with GitLab.com and a Kubernetes cluster on Google Kubernetes Engine (GKE).
+
+If you are using a self-hosted instance of GitLab, you need to configure the
+[Google OAuth2 OmniAuth Provider](../../integration/google.md) before
+you can configure a cluster on GKE. Once this is set up, you can follow the steps on the [quick start guide](quick_start_guide.md) to get started.
+
+NOTE: **Note**
+This guide shows how the WAF can be deployed using Auto DevOps. The WAF
+is avaliable by default to all applications no matter how they are deployed,
+as long as they are using Ingress.
+
+## Network firewall vs. Web Application Firewall
+
+A network firewall or packet filter looks at traffic at the Network (L3) and Transport (L4) layers
+of the [OSI Model](https://en.wikipedia.org/wiki/OSI_model), and denies packets from entry based on
+a set of rules regarding the network in general.
+
+A Web Application Firewall operates at the Application (L7) layer of the OSI Model and can
+examine all the packets traveling to and from a specific application. A WAF can set
+more advanced rules around threat detection.
+
+## Features
+
+ModSecurity is enabled with the [OWASP Core Rule Set (CRS)](https://modsecurity.org/crs/) by
+default. The OWASP CRS logs attempts to the following attacks:
+
+- [SQL Injection](https://www.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection)
+- [Cross-Site Scripting](https://www.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS))
+- [Local File Inclusion](https://www.owasp.org/index.php/Testing_for_Local_File_Inclusion)
+- [Remote File Inclusion](https://www.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion)
+- [Code Injection](https://www.owasp.org/index.php/Code_Injection)
+- [Session Fixation](https://www.owasp.org/index.php/Session_fixation)
+- [Scanner Detection](https://www.owasp.org/index.php/Category:Vulnerability_Scanning_Tools)
+- [Metadata/Error Leakages](https://www.owasp.org/index.php/Improper_Error_Handling)
+
+It is good to have a basic knowledge of the following:
+
+- [Kubernetes](https://kubernetes.io/docs/home/)
+- [Ingress](https://kubernetes.github.io/ingress-nginx/)
+- [ModSecurity](https://www.modsecurity.org/)
+- [OWASP Core Rule Set](https://modsecurity.org/crs/)
+
+## Roadmap
+
+More information on the direction of the WAF can be
+found in [Product Vision - Defend](https://about.gitlab.com/direction/defend/#waf)

doc/user/clusters/applications.md

@@ -139,10 +139,12 @@ file. Customizing installation by modifying this file is not supported.
 > - Introduced in GitLab 10.2 for project-level clusters.
 > - Introduced in GitLab 11.6 for group-level clusters.
 
-[Ingress](https://kubernetes.github.io/ingress-nginx/) can provide load
-balancing, SSL termination, and name-based virtual hosting. It acts as a
-web proxy for your applications and is useful if you want to use [Auto
-DevOps](../../topics/autodevops/index.md) or deploy your own web apps.
+[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) provides load balancing, SSL termination, and name-based virtual hosting
+out of the box. It acts as a web proxy for your applications and is useful
+if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps.
+
+The Ingress Controller installed is [Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/),
+which is supported by the Kubernetes community.
 
 NOTE: **Note:**
 With the following procedure, a load balancer must be installed in your cluster
@@ -255,12 +257,20 @@ use an A record. If your external endpoint is a hostname, use a CNAME record.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7.
 
-Out of the box, GitLab provides you real-time security monitoring with
-[ModSecurity](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity).
+A Web Application Firewall (WAF) is able to examine traffic being sent/received
+and can block malicious traffic before it reaches your application. The benefits
+of a WAF are:
+
+- Real-time security monitoring for your application
+- Logging of all your HTTP traffic to the application
+- Access control for your application
+- Highly configurable logging and blocking rules
+
+Out of the box, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/)
 
-Modsecurity is a toolkit for real-time web application monitoring, logging,
-and access control. With GitLab's offering, the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), which provides generic attack detection capabilities,
-is automatically applied.
+ModSecurity is a toolkit for real-time web application monitoring, logging,
+and access control. With GitLab's offering, the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/),
+which provides generic attack detection capabilities, is automatically applied.
 
 This feature:
 
@@ -275,6 +285,12 @@ This feature:
 To enable ModSecurity, check the **Enable Web Application Firewall** checkbox
 when installing your [Ingress application](#ingress).
 
+If this is your first time using GitLab's WAF, we recommend you follow the
+[quick start guide](../../topics/web_application_firewall/quick_start_guide.md).
+
+There is a small performance overhead by enabling ModSecurity. However,
+if this is considered significant for your application, you can disable it.
+
 There is a small performance overhead by enabling ModSecurity. If this is
 considered significant for your application, you can disable ModSecurity's
 rule engine for your deployed application by setting