Skip to content

G
gitlab-ce
Commit 276f5149 authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

Merge branch 'sam-update-protect-docs' into 'master' 

Revise Protect documentation

See merge request gitlab-org/gitlab!49253
parents a523866d 68b0c68c
Hide whitespace changes
Inline Side-by-side
Showing with 767 additions and 503 deletions
doc/topics/web_application_firewall/index.md
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
redirect_to: '../../user/project/clusters/protect/web_application_firewall/index.md'
---
This document was moved to [another location](../../user/project/clusters/protect/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 the GitLab [Ingress](../../user/clusters/applications.md#ingress)
deployment, the [ModSecurity](https://modsecurity.org/)
module is loaded into Ingress-NGINX by default and monitors the traffic 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 detects and logs a wide range of common attacks.
By default, the WAF is deployed in Detection-only mode and only logs 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-managed 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:
This guide shows how the WAF can be deployed using Auto DevOps. The WAF
is available 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://github.com/coreruleset/coreruleset/) by
default. The OWASP CRS logs attempts to the following attacks:
- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection)
- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS))
- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion)
- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion)
- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection)
- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation)
- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools)
- [Metadata/Error Leakages](https://wiki.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://github.com/coreruleset/coreruleset/)
## Roadmap
You can find more information on the product direction of the WAF in
[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/).
<!-- This redirect file can be deleted after <2021-04-01>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/topics/web_application_firewall/quick_start_guide.md
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
redirect_to: '../../user/project/clusters/protect/web_application_firewall/quick_start_guide.md'
---
# Getting started with the Web Application Firewall
This document was moved to [another location](../../user/project/clusters/protect/web_application_firewall/quick_start_guide.md).
This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after
deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../autodevops/index.md).
The GitLab native Kubernetes integration is used, so you do not need
to create a Kubernetes cluster manually using the Google Cloud Platform console.
A simple application is created and deployed based on a GitLab template.
These instructions also work for a self-managed GitLab instance. However, you
need to ensure your own [runners are configured](../../ci/runners/README.md) and
[Google OAuth is enabled](../../integration/google.md).
The GitLab Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress),
so it is available to your applications no matter how you deploy them to Kubernetes.
## Configuring your Google account
Before creating and connecting your Kubernetes cluster to your GitLab project,
you need a Google Cloud Platform account. If you do not already have one,
sign up at <https://console.cloud.google.com>. You need to either sign in with an existing
Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one.
1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account).
NOTE:
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab
Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit.
## Creating a new project from a template
We use a GitLab project templates to get started. As the name suggests,
those projects provide a barebones application built on some well-known frameworks.
1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select
**New project**.
1. Go to the **Create from template** tab where you can choose for example a Ruby on
Rails, Spring, or NodeJS Express project.
Use the Ruby on Rails template.
![Select project template](../autodevops/img/guide_project_template_v12_3.png)
1. Give your project a name, optionally a description, and make it public so that
you can take advantage of the features available in the
[GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com).
![Create project](../autodevops/img/guide_create_project_v12_3.png)
1. Click **Create project**.
Now that the project is created, the next step is to create the Kubernetes cluster
to deploy this application under.
## Creating a Kubernetes cluster from within GitLab
1. On the project's landing page, click **Add Kubernetes cluster**
(note that this option is also available when you navigate to **Operations > Kubernetes**).
![Project landing page](../autodevops/img/guide_project_landing_page_v12_10.png)
1. On the **Create new cluster on GKE** tab, click **Sign in with Google**.
![Google sign in](../autodevops/img/guide_google_signin_v12_3.png)
1. Connect with your Google account and click **Allow** when asked (this
appears only the first time you connect GitLab with your Google account).
![Google auth](../autodevops/img/guide_google_auth_v12_3.png)
1. The last step is to provide the cluster details.
1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster.
(Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.)
1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in.
1. Enter the number of nodes you want it to have.
1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types).
![GitLab GKE cluster details](../autodevops/img/guide_gitlab_gke_details_v12_3.png)
1. Click **Create Kubernetes cluster**.
After a couple of minutes, the cluster is created. You can also see its
status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
The next step is to install some applications on your cluster that are needed
to take full advantage of Auto DevOps.
## Install Ingress
The GitLab Kubernetes integration comes with some
[pre-defined applications](../../user/project/clusters/index.md#installing-applications)
for you to install.
![Cluster applications](../autodevops/img/guide_cluster_apps_v12_3.png)
For this guide, we need to install Ingress. Ingress provides load balancing,
SSL termination, and name-based virtual hosting, using NGINX behind
the scenes. Make sure to switch the toggle to the enabled position before installing.
Both logging and blocking modes are available for WAF. While logging mode is useful for
auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress.
![Cluster applications](img/guide_waf_ingress_installation_v12_10.png)
After Ingress is installed, wait a few seconds and copy the IP address that
is displayed in order to add in your base **Domain** at the top of the page. For
the purpose of this guide, we use the one suggested by GitLab. Once you have
filled in the domain, click **Save changes**.
![Cluster Base Domain](../autodevops/img/guide_base_domain_v12_3.png)
Prometheus should also be installed. It is an open-source monitoring and
alerting system that is used to supervise the deployed application.
Installing GitLab Runner is not required as we use the shared runners that
GitLab.com provides.
## Enabling Auto DevOps (optional)
Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable
Auto DevOps at both the instance-level (for self-managed instances) and the group-level.
Follow these steps if Auto DevOps has been manually disabled:
1. Navigate to **Settings > CI/CD > Auto DevOps**.
1. Select **Default to Auto DevOps pipeline**.
1. Select the [continuous deployment strategy](../autodevops/index.md#deployment-strategy)
which automatically deploys the application to production once the pipeline
successfully runs on the `master` branch.
1. Click **Save changes**.
![Auto DevOps settings](../autodevops/img/guide_enable_autodevops_v12_3.png)
Once you complete all the above and save your changes, a new pipeline is
automatically created. To view the pipeline, go to **CI/CD > Pipelines**.
![First pipeline](../autodevops/img/guide_first_pipeline_v12_3.png)
The next section explains what each pipeline job does.
## Deploying the application
By now you should see the pipeline running, but what is it running exactly?
To navigate inside the pipeline, click its status badge (its status should be "Running").
The pipeline is split into a few stages, each running a couple of jobs.
![Pipeline stages](../autodevops/img/guide_pipeline_stages_v13_0.png)
In the **build** stage, the application is built into a Docker image and then
uploaded to your project's [Container Registry](../../user/packages/container_registry/index.md) ([Auto Build](../autodevops/stages.md#auto-build)).
In the **test** stage, GitLab runs various checks on the application.
The **production** stage is run after the tests and checks finish, and it automatically
deploys the application in Kubernetes ([Auto Deploy](../autodevops/stages.md#auto-deploy)).
The **production** stage creates Kubernetes objects
like a Deployment, Service, and Ingress resource. The
application is monitored by the WAF automatically.
## Validating Ingress is running ModSecurity
Now we can make sure that Ingress is running properly with ModSecurity and send
a request to ensure our application is responding correctly. You must connect to
your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install).
1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled.
This is done by running the following commands:
```shell
$ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller'
ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running
$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;'
modsecurity on;
```
1. Verify the Rails application has been installed properly.
```shell
$ kubectl get ns
auto-devv-2-16730183-production Active
$ kubectl get pods -n auto-devv-2-16730183-production
NAME READY STATUS RESTARTS
production-5778cfcfcd-nqjcm 1/1 Running 0
production-postgres-6449f8cc98-r7xgg 1/1 Running 0
```
1. To make sure the Rails application is responding, send a request to it by running:
```shell
$ kubectl get ing -n auto-devv-2-16730183-production
NAME HOSTS PORTS
production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443
$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2
<body>
<p>You're on Rails!</p>
</body>
```
Now that we have confirmed our system is properly setup, we can go ahead and test
the WAF with OWASP CRS!
## Testing out the OWASP Core Rule Set
Now let's send a potentially malicious request, as if we were a scanner,
checking for vulnerabilities within our application and examine the ModSecurity logs:
```shell
$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2
<body>
<p>You're on Rails!</p>
</body>
$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe'
{
"message": "Found User-Agent associated with security scanner",
"details": {
"match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )",
"reference": "o0,8v84,8t:lowercase",
"ruleId": "913100",
"file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf",
"lineNumber": "33",
"data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe",
"severity": "2",
"ver": "OWASP_CRS/3.2.0",
"rev": "",
"tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"],
"maturity": "0",
"accuracy": "0"
}
}
```
You can see that ModSecurity logs the suspicious behavior. By sending a request
with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe), a tool for testing for SQL injections uses, we can detect that someone was
searching for vulnerabilities on our system. Detecting scanners is useful, because we
can learn if someone is trying to exploit our system.
## Conclusion
You can now see the benefits of a using a Web Application Firewall.
ModSecurity and the OWASP Core Rule Set, offer many more benefits.
You can explore them in more detail:
- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/)
- [ModSecurity](https://www.modsecurity.org/)
- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/)
- [AutoDevOps](../autodevops/index.md)
<!-- This redirect file can be deleted after <2021-04-01>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/user/clusters/applications.md
View file @ 276f5149
......@@ -1296,7 +1296,7 @@ To enable WAF, switch its respective toggle to the enabled position when install
or updating [Ingress application](#ingress).
If this is your first time using the GitLab WAF, we recommend you follow the
[quick start guide](../../topics/web_application_firewall/quick_start_guide.md).
[quick start guide](../project/clusters/protect/web_application_firewall/quick_start_guide.md).
There is a small performance overhead by enabling ModSecurity. If this is
considered significant for your application, you can disable ModSecurity's
......@@ -1308,7 +1308,7 @@ rule engine for your deployed application in any of the following ways:
1. Switch its respective toggle to the disabled position, and then apply changes
by selecting **Save changes** to reinstall Ingress with the recent changes.
![Disabling WAF](../../topics/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png)
![Disabling WAF](../project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png)
##### Logging and blocking modes
......@@ -1321,7 +1321,7 @@ To help you tune your WAF rules, you can globally set your WAF to either
To change your WAF's mode:
1. If you haven't already done so,
[install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md).
[install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md).
1. Navigate to **Operations > Kubernetes**.
1. In **Applications**, scroll to **Ingress**.
1. Under **Global default**, select your desired mode.
......@@ -1337,12 +1337,12 @@ The **ModSecurity** user interface controls are disabled if the version deployed
differs from the one available in GitLab. However, actions at the [Ingress](#ingress)
level, such as uninstalling, can still be performed:
![WAF settings disabled](../../topics/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png)
![WAF settings disabled](../project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png)
Update [Ingress](#ingress) to the most recent version to take advantage of bug
fixes, security fixes, and performance improvements. To update the
[Ingress application](#ingress), you must first uninstall it, and then re-install
it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md).
it as described in [Install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md).
##### Viewing Web Application Firewall traffic
......
doc/user/project/clusters/protect/container_host_security/index.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Container Host Security
Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can
monitor and (optionally) block activity inside the containers themselves. This is done by leveraging
an integration with Falco to provide the monitoring capabilities and an integration with Pod
Security Policies and AppArmor to provide blocking capabilities.
## Overview
Container Host Security can be used to monitor and block activity inside a container as well as to
enforce security policies across the entire Kubernetes cluster. Falco profiles allow for users to
define the activity they want to monitor for and detect. Among other things, this can include system
log entries, process starts, file activity, and network ports opened. AppArmor is used to block any
undesired activity via AppArmor profiles. These profiles are loaded into the cluster when
referenced by Pod Security Policies.
By default, Container Host Security is deployed into the cluster in monitor mode only, with no
default profiles or rules running out-of-the-box. Activity monitoring and blocking begins only when
users define profiles for these technologies.
## Installation
See the [installation guide](quick_start_guide.md) for the recommended steps to install the
Container Host Security capabilities. This guide shows the recommended way of installing Container
Host Security through GMAv2. However, it's also possible to do a manual installation through our
Helm chart.
## Features
- Prevent containers from starting as root.
- Limit the privileges and system calls available to containers.
- Monitor system logs, process starts, files read/written/deleted, and network ports opened.
- Optionally block processes from starting or files from being read/written/deleted.
## Supported container orchestrators
Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container
orchestrators aren't supported.
## Supported Kubernetes providers
The following cloud providers are supported:
- Amazon EKS
- Google GKE
Although Container Host Security may function on Azure or self-managed Kubernetes instances, it isn't
officially tested and supported on those providers.
## Roadmap
See the [Category Direction page](https://about.gitlab.com/direction/protect/container_host_security/)
for more information on the product direction of Container Host Security.
doc/user/project/clusters/protect/container_host_security/quick_start_guide.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Getting started with Container Host Security
The following steps are recommended for installing Container Host Security. Although you can install
some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install
applications through GMAv2 exclusively when using Container Network Security.
## Installation steps
The following steps are recommended to install and use Container Host Security through GitLab:
1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/).
1. [Create a group](../../../../group/#create-a-new-group).
1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md).
1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md).
1. Install and configure an Ingress node:
- [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd).
- [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually).
- Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain)
into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes
cluster.
1. [Install and configure Falco](../../../../clusters/applications.md#install-falco-using-gitlab-cicd)
for activity monitoring.
1. [Install and configure AppArmor](../../../../clusters/applications.md#install-apparmor-using-gitlab-cicd)
for activity blocking.
1. [Configure Pod Security Policies](../../../../clusters/applications.md#using-podsecuritypolicy-in-your-deployments)
(required to be able to load AppArmor profiles).
It's possible to install and manage Falco and AppArmor in other ways, such as installing them
manually in a Kubernetes cluster and then connecting it back to GitLab. These methods aren't
supported or documented.
## Viewing the logs
Falco logs can be viewed by running the following command in your Kubernetes cluster:
```shell
kubectl -n gitlab-managed-apps logs -l app=falco
```
## Troubleshooting
### Trouble connecting to the cluster
Your CI/CD pipeline may occasionally fail or have trouble connecting to the cluster. Here are some
initial troubleshooting steps that resolve the most common problems:
1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache)
1. If things still aren't working, a more assertive set of actions may help get things back to a
good state:
- Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui)
in GitLab.
- Delete the relevant namespace in Kubernetes by running
`kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster.
- Rerun the application project pipeline to redeploy the application.
### Using GMAv1 with GMAv2
When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with
applications being uninstalled or removed from the cluster. This is because GMAv2 actively
uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2.
It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the
GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1
applications must be reinstalled after each run of that pipeline. This approach isn't recommended as
it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled.
When using Container Network Security, the preferred and recommended path is to install all
necessary components with GMAv2 and the cluster management project.
**Related documentation links:**
- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click)
- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md)
doc/user/project/clusters/protect/container_network_security/index.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Container Network Security
Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium
NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods
inside the cluster. Container Network Security can be used to enforce L3, L4, and L7 policies and
can prevent an attacker with control over one pod from spreading laterally to access other pods in
the same cluster. Both Ingress and Egress rules are supported.
By default, Cilium is deployed in Detection-only mode and only logs attack attempts. GitLab provides
a set of out-of-the-box policies as examples and to help users get started. These policies are
disabled by default, as they must usually be customized to match application-specific needs.
## Installation
See the [installation guide](quick_start_guide.md) for the recommended steps to install GitLab
Container Network Security. This guide shows the recommended way of installing Container Network
Security through GMAv2. However, it's also possible to install Cilium manually through our Helm
chart.
## Features
- GitLab managed installation of Cilium.
- Support for L3, L4, and L7 policies.
- Ability to export logs to a SIEM.
- Statistics page showing volume of packets processed and dropped over time (Gold/Ultimate users
only).
- Management of NetworkPolicies through code in a project (Available for auto DevOps users only).
- Management of CiliumNetworkPolicies through a UI policy manager (Gold/Ultimate users only).
## Supported container orchestrators
Kubernetes v1.14+ is the only supported container orchestrator. OpenShift and other container
orchestrators aren't supported.
## Supported Kubernetes providers
The following cloud providers are supported:
- Amazon EKS
- Google GKE
Although Container Network Security may function on Azure or self-managed Kubernetes instances, it
isn't officially tested and supported on those providers.
## Supported NetworkPolicies
GitLab only supports the use of CiliumNetworkPolicies. Although generic Kubernetes NetworkPolicies
or other kinds of NetworkPolicies may work, GitLab doesn't test or support them.
## Managing NetworkPolicies through GitLab vs your cloud provider
Some cloud providers offer integrations with Cilium or offer other ways to manage NetworkPolicies in
Kubernetes. GitLab Container Network Security doesn't support deployments that have NetworkPolicies
managed by an external provider. By choosing to manage NetworkPolicies through GitLab, you can take
advantage of the following benefits:
- Support for handling NetworkPolicy infrastructure as code.
- Full revision history and audit log of all changes made.
- Ability to revert back to a previous version at any time.
## Roadmap
See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/)
for more information on the product direction of Container Network Security.
doc/user/project/clusters/protect/container_network_security/quick_start_guide.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Getting started with Container Network Security
The following steps are recommended for installing Container Network Security. Although you can
install some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install
applications through GMAv2 exclusively when using Container Network Security.
## Installation steps
The following steps are recommended to install and use Container Network Security through GitLab:
1. [Install at least one runner and connect it to GitLab](https://docs.gitlab.com/runner/).
1. [Create a group](../../../../group/#create-a-new-group).
1. [Connect a Kubernetes cluster to the group](../../add_remove_clusters.md).
1. [Create a cluster management project and associate it with the Kubernetes cluster](../../../../clusters/management_project.md).
1. Install and configure an Ingress node:
- [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd).
- [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually).
- Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain)
into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes
cluster.
1. [Install and configure Cilium](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd).
1. Be sure to restart all pods that were running before Cilium was installed by running this command
in your cluster:
`kubectl get pods --all-namespaces -o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HOSTNETWORK:.spec.hostNetwork --no-headers=true | grep '<none>' | awk '{print "-n "$1" "$2}' | xargs -L 1 -r kubectl delete pod`
It's possible to install and manage Cilium in other ways. For example, you could use the GitLab Helm
chart to install Cilium manually in a Kubernetes cluster, and then connect it back to GitLab.
However, such methods aren't documented or officially supported by GitLab.
## Managing Network Policies
Managing NetworkPolicies through GitLab is advantageous over managing the policies in Kubernetes
directly. Kubernetes doesn't provide a GUI editor, a change control process, or a revision history.
Network Policies can be managed through GitLab in one of two ways:
- Management through a YAML file in each application's project (for projects using Auto DevOps). For
more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy).
- Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more
information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate/Gold only).
Each method has benefits and drawbacks:
| | YAML method | UI method (Ultimate/Gold only) |
|--|:------------|:-------------------------------|
| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. |
| **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. |
Users are encouraged to choose one of the two methods to manage their policies. If users attempt to
use both methods simultaneously, when the application project pipeline runs the contents of the
NetworkPolicy in the `auto-deploy-values.yaml` file may override policies configured in the UI
editor.
## Monitoring throughput `**(ULTIMATE)**`
To view statistics for Container Network Security, you must follow the installation steps above and
configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you
must enable Hubble with flow metrics for each namespace by adding the following lines to
your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd):
your [Cilium values](../../../../clusters/applications.md#install-cilium-using-gitlab-cicd):
```yaml
global:
hubble:
enabled: true
metrics:
enabled:
- 'flow:sourceContext=namespace;destinationContext=namespace'
```
Additional information about the statistics page is available in the
[documentation that describes the Threat Management UI](../../../../application_security/threat_monitoring/index.md#container-network-policy).
## Forwarding logs to a SIEM
Cilium logs can be forwarded to a SIEM or an external logging system through syslog protocol by
installing and configuring Fluentd. Fluentd can be installed through GitLab in two ways:
- The [GMAv1 method](../../../../clusters/applications.md#fluentd)
- The [GMAv2 method](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd)
GitLab strongly encourages using only the GMAv2 method to install Fluentd.
## Viewing the logs
Cilium logs can be viewed by running the following command in your Kubernetes cluster:
```shell
kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor
```
## Troubleshooting
### Traffic is not being blocked as expected
By default, Cilium is installed in Audit mode only, meaning that NetworkPolicies log policy
violations but don't block any traffic. To set Cilium to Blocking mode, you must add the following
lines to the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project:
```yaml
config:
policyAuditMode: false
agent:
monitor:
eventTypes: ["drop"]
```
### Traffic is not being allowed as expected
Keep in mind that when Cilium is set to blocking mode (rather than Audit mode), NetworkPolicies
operate on an allow-list basis. If one or more NetworkPolicies apply to a node, then all traffic
that doesn't match at least one Policy is blocked. To resolve, add NetworkPolicies defining the
traffic that you want to allow in the node.
### Trouble connecting to the cluster
Occasionally, your CI/CD pipeline may fail or have trouble connecting to the cluster. Here are some
initial troubleshooting steps that resolve the most common problems:
1. [Clear the cluster cache](../../index.md#clearing-the-cluster-cache).
1. If things still aren't working, a more assertive set of actions may help get things back into a
good state:
- Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab.
- Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster.
- Rerun the application project pipeline to redeploy the application.
### Using GMAv1 with GMAv2
When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with
applications being uninstalled or removed from the cluster. This is because GMAv2 actively
uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2.
It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the
GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1
applications must be reinstalled after each run of that pipeline. This approach isn't recommended as
it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled.
When using Container Network Security, the preferred and recommended path is to install all
necessary components with GMAv2 and the cluster management project.
**Related documentation links:**
- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click)
- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md)
doc/user/project/clusters/protect/index.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Protecting your deployed applications
GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md).
These protections are available in the Kubernetes network layer and in the container itself. At
the network layer, the Container Network Security capabilities in GitLab provide basic firewall
functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster
and traffic between pods inside the cluster. Inside the container, Container Host Security provides
Intrusion Detection and Prevention capabilities that can monitor and block activity inside the
containers themselves.
## Capabilities
The following capabilities are available to protect deployed applications in Kubernetes:
- Web Application Firewall
- [Overview](web_application_firewall/index.md)
- [Installation guide](web_application_firewall/quick_start_guide.md)
- Container Network Security
- [Overview](container_network_security/index.md)
- [Installation guide](container_network_security/quick_start_guide.md)
- Container Host Security
- [Overview](container_host_security/index.md)
- [Installation guide](container_host_security/quick_start_guide.md)
doc/user/project/clusters/protect/web_application_firewall/index.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Web Application Firewall
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 the GitLab [Ingress](../../../../clusters/applications.md#ingress)
deployment, the [ModSecurity](https://modsecurity.org/)
module is loaded into Ingress-NGINX by default and monitors the traffic 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 detects and logs a wide range of common attacks.
By default, the WAF is deployed in Detection-only mode and only logs 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](../../../../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-managed instance of GitLab, you must 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:
This guide shows how the WAF can be deployed using Auto DevOps. The WAF
is available 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://github.com/coreruleset/coreruleset/) by
default. The OWASP CRS logs attempts to the following attacks:
- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection)
- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS))
- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion)
- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion)
- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection)
- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation)
- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools)
- [Metadata/Error Leakages](https://wiki.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://github.com/coreruleset/coreruleset/)
## Roadmap
You can find more information on the product direction of the WAF in
[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/).
doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md 0 → 100644
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Getting started with the Web Application Firewall
This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after
deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../../../../../topics/autodevops/index.md).
The GitLab native Kubernetes integration is used, so you do not need
to create a Kubernetes cluster manually using the Google Cloud Platform console.
A simple application is created and deployed based on a GitLab template.
These instructions also work for a self-managed GitLab instance. However, you
need to ensure your own [runners are configured](../../../../../ci/runners/README.md) and
[Google OAuth is enabled](../../../../../integration/google.md).
The GitLab Web Application Firewall is deployed with [Ingress](../../../../clusters/applications.md#ingress),
so it is available to your applications no matter how you deploy them to Kubernetes.
## Configuring your Google account
Before creating and connecting your Kubernetes cluster to your GitLab project,
you need a Google Cloud Platform account. If you do not already have one,
sign up at <https://console.cloud.google.com>. You need to either sign in with an existing
Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one.
1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account).
NOTE:
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab
Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit.
## Creating a new project from a template
We use a GitLab project templates to get started. As the name suggests,
those projects provide a barebones application built on some well-known frameworks.
1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select
**New project**.
1. Go to the **Create from template** tab where you can choose for example a Ruby on
Rails, Spring, or NodeJS Express project.
Use the Ruby on Rails template.
![Select project template](../../../../../topics/autodevops/img/guide_project_template_v12_3.png)
1. Give your project a name, optionally a description, and make it public so that
you can take advantage of the features available in the
[GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com).
![Create project](../../../../../topics/autodevops/img/guide_create_project_v12_3.png)
1. Click **Create project**.
Now that the project is created, the next step is to create the Kubernetes cluster
to deploy this application under.
## Creating a Kubernetes cluster from within GitLab
1. On the project's landing page, click **Add Kubernetes cluster**
(note that this option is also available when you navigate to **Operations > Kubernetes**).
![Project landing page](../../../../../topics/autodevops/img/guide_project_landing_page_v12_10.png)
1. On the **Create new cluster on GKE** tab, click **Sign in with Google**.
![Google sign in](../../../../../topics/autodevops/img/guide_google_signin_v12_3.png)
1. Connect with your Google account and click **Allow** when asked (this
appears only the first time you connect GitLab with your Google account).
![Google auth](../../../../../topics/autodevops/img/guide_google_auth_v12_3.png)
1. The last step is to provide the cluster details.
1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster.
(Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.)
1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in.
1. Enter the number of nodes you want it to have.
1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types).
![GitLab GKE cluster details](../../../../../topics/autodevops/img/guide_gitlab_gke_details_v12_3.png)
1. Click **Create Kubernetes cluster**.
After a couple of minutes, the cluster is created. You can also see its
status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
The next step is to install some applications on your cluster that are needed
to take full advantage of Auto DevOps.
## Install Ingress
The GitLab Kubernetes integration comes with some
[pre-defined applications](../../index.md#installing-applications)
for you to install.
![Cluster applications](../../../../../topics/autodevops/img/guide_cluster_apps_v12_3.png)
For this guide, we need to install Ingress. Ingress provides load balancing,
SSL termination, and name-based virtual hosting, using NGINX behind
the scenes. Make sure to switch the toggle to the enabled position before installing.
Both logging and blocking modes are available for WAF. While logging mode is useful for
auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress.
![Cluster applications](img/guide_waf_ingress_installation_v12_10.png)
After Ingress is installed, wait a few seconds and copy the IP address that
is displayed in order to add in your base **Domain** at the top of the page. For
the purpose of this guide, we use the one suggested by GitLab. Once you have
filled in the domain, click **Save changes**.
![Cluster Base Domain](../../../../../topics/autodevops/img/guide_base_domain_v12_3.png)
Prometheus should also be installed. It is an open-source monitoring and
alerting system that is used to supervise the deployed application.
Installing GitLab Runner is not required as we use the shared runners that
GitLab.com provides.
## Enabling Auto DevOps (optional)
Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable
Auto DevOps at both the instance-level (for self-managed instances) and the group-level.
Follow these steps if Auto DevOps has been manually disabled:
1. Navigate to **Settings > CI/CD > Auto DevOps**.
1. Select **Default to Auto DevOps pipeline**.
1. Select the [continuous deployment strategy](../../../../../topics/autodevops/index.md#deployment-strategy)
which automatically deploys the application to production once the pipeline
successfully runs on the `master` branch.
1. Click **Save changes**.
![Auto DevOps settings](../../../../../topics/autodevops/img/guide_enable_autodevops_v12_3.png)
Once you complete all the above and save your changes, a new pipeline is
automatically created. To view the pipeline, go to **CI/CD > Pipelines**.
![First pipeline](../../../../../topics/autodevops/img/guide_first_pipeline_v12_3.png)
The next section explains what each pipeline job does.
## Deploying the application
By now you should see the pipeline running, but what is it running exactly?
To navigate inside the pipeline, click its status badge (its status should be "Running").
The pipeline is split into a few stages, each running a couple of jobs.
![Pipeline stages](../../../../../topics/autodevops/img/guide_pipeline_stages_v13_0.png)
In the **build** stage, the application is built into a Docker image and then
uploaded to your project's [Container Registry](../../../../packages/container_registry/index.md)
([Auto Build](../../../../../topics/autodevops/stages.md#auto-build)).
In the **test** stage, GitLab runs various checks on the application.
The **production** stage is run after the tests and checks finish, and it automatically
deploys the application in Kubernetes ([Auto Deploy](../../../../../topics/autodevops/stages.md#auto-deploy)).
The **production** stage creates Kubernetes objects
like a Deployment, Service, and Ingress resource. The
application is monitored by the WAF automatically.
## Validating Ingress is running ModSecurity
Now we can make sure that Ingress is running properly with ModSecurity and send
a request to ensure our application is responding correctly. You must connect to
your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install).
1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled.
This is done by running the following commands:
```shell
$ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller'
ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running
$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;'
modsecurity on;
```
1. Verify the Rails application has been installed properly.
```shell
$ kubectl get ns
auto-devv-2-16730183-production Active
$ kubectl get pods -n auto-devv-2-16730183-production
NAME READY STATUS RESTARTS
production-5778cfcfcd-nqjcm 1/1 Running 0
production-postgres-6449f8cc98-r7xgg 1/1 Running 0
```
1. To make sure the Rails application is responding, send a request to it by running:
```shell
$ kubectl get ing -n auto-devv-2-16730183-production
NAME HOSTS PORTS
production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443
$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2
<body>
<p>You're on Rails!</p>
</body>
```
Now that we have confirmed our system is properly setup, we can go ahead and test
the WAF with OWASP CRS!
## Testing out the OWASP Core Rule Set
Now let's send a potentially malicious request, as if we were a scanner,
checking for vulnerabilities within our application and examine the ModSecurity logs:
```shell
$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2
<body>
<p>You're on Rails!</p>
</body>
$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe'
{
"message": "Found User-Agent associated with security scanner",
"details": {
"match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )",
"reference": "o0,8v84,8t:lowercase",
"ruleId": "913100",
"file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf",
"lineNumber": "33",
"data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe",
"severity": "2",
"ver": "OWASP_CRS/3.2.0",
"rev": "",
"tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"],
"maturity": "0",
"accuracy": "0"
}
}
```
You can see that ModSecurity logs the suspicious behavior. By sending a request
with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe),
a tool for testing for SQL injections uses, we can detect that someone was
searching for vulnerabilities on our system. Detecting scanners is useful, because we
can learn if someone is trying to exploit our system.
## Conclusion
You can now see the benefits of a using a Web Application Firewall.
ModSecurity and the OWASP Core Rule Set, offer many more benefits.
You can explore them in more detail:
- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/)
- [ModSecurity](https://www.modsecurity.org/)
- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/)
- [AutoDevOps](../../../../../topics/autodevops/index.md)
doc/user/project/clusters/securing.md
View file @ 276f5149
---
stage: Protect
group: Container Security
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
redirect_to: 'protect/index.md'
---
# Securing your deployed applications
This document was moved to [another location](protect/index.md).
GitLab makes it easy to secure applications deployed in [connected Kubernetes clusters](index.md).
You can benefit from the protection of a [Web Application Firewall](../../../topics/web_application_firewall/quick_start_guide.md),
[Network Policies](../../../topics/autodevops/stages.md#network-policy),
and [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd).
This page contains full end-to-end steps and instructions to connect your cluster to GitLab and
install these features, whether or not your applications are deployed through GitLab CI/CD. If you
use [Auto DevOps](../../../topics/autodevops/index.md)
to build and deploy your application with GitLab, see the documentation for the respective
[GitLab Managed Applications](../../clusters/applications.md)
above.
## Overview
At a high level, the required steps include the following:
- Connect the cluster to GitLab.
- Set up one or more runners.
- Set up a cluster management project.
- Install a Web Application Firewall, and/or Network Policies, and/or Container Host
Security.
- Install Prometheus to get statistics and metrics in the
[threat monitoring](../../application_security/threat_monitoring/)
dashboard.
### Requirements
Minimum requirements (depending on the GitLab Manage Application you want to install):
- Your cluster is connected to GitLab (ModSecurity, Cilium, and Falco).
- At least one runner is installed (Cilium and Falco only).
### Understanding how GitLab Managed Apps are installed
NOTE:
These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm
command runner pod in the cluster.
You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab
uses Sidekiq (a background processing service) to facilitate this.
```mermaid
sequenceDiagram
autonumber
GitLab->>+Sidekiq: Install a GitLab Managed App
Sidekiq->>+Kubernetes: Helm install
Kubernetes-->>-Sidekiq: Installation complete
Sidekiq-->>-GitLab: Refresh UI
```
Although this installation method is easier because it's a point-and-click action in the user
interface, it's inflexible and harder to debug. If something goes wrong, you can't see the
deployment logs. The Web Application Firewall feature uses this installation method.
However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103))
don't use Sidekiq to deploy. All the applications are deployed using a GitLab CI/CD pipeline and
therefore, by runners.
```mermaid
sequenceDiagram
autonumber
GitLab->>+GitLab: Trigger pipeline
GitLab->>+Runner: Run deployment job
Runner->>+Kubernetes: Helm install
Kubernetes-->>-Runner: Installation is complete
Runner-->>-GitLab: Report job status and update pipeline
```
Debugging is easier because you have access to the raw logs of these jobs (the Helm Tiller output is
available as an artifact in case of failure), and the flexibility is much better. Since these
deployments are only triggered when a pipeline is running (most likely when there's a new commit in
the cluster management repository), every action has a paper trail and follows the classic merge
request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App, and Container
Host Security (Falco) are deployed with this model.
## Connect the cluster to GitLab
To deploy GitLab Managed Apps to your cluster, you must first
[add your cluster](add_remove_clusters.md)
to GitLab. Then [install](../../clusters/applications.md#install-with-one-click)
the Web Application Firewall from the project or group Kubernetes page.
Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a
cluster independent of the applications that use the cluster.
## Set up a runner
To install CI/CD-based GitLab Managed Apps, a pipeline using a runner must be running in
GitLab. You can [install a runner](../../clusters/applications.md#gitlab-runner)
in the Kubernetes cluster added in the previous step, or use one of the shared runners provided by
GitLab if you're using GitLab.com.
With your cluster connected to GitLab and a runner in place, you can proceed to the next
steps and start installing the Cilium and Falco GitLab Managed Apps to secure your applications
hosted on this cluster.
## Create a Cluster Management Project
A [Cluster Management Project](../../clusters/management_project.md)
is a GitLab project that contains a `.gitlab-ci.yml` file to deploy GitLab Managed Apps to your
cluster. This project runs the required charts with the Kubernetes
[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
privileges.
The creation of this project starts like any other GitLab project. Use an empty
project and add a `gitlab-ci.yml` file at the root, containing this template:
```yaml
include:
- template: Managed-Cluster-Applications.gitlab-ci.yml
```
To make this project a Cluster Management Project, follow these
[instructions](../../clusters/management_project.md#selecting-a-cluster-management-project).
This project can be designated as such even if your application isn't hosted on GitLab. In this
case, create a new empty project where you can select your newly created Cluster Management Project.
## Install GitLab Container Network Policy
GitLab Container Network Policy is based on [Cilium](https://cilium.io/). To
install the Cilium GitLab Managed App, add a
`.gitlab/managed-apps/config.yaml` file to your Cluster Management project:
```yaml
# possible values are gke, eks or you can leave it blank
clusterType: gke
cilium:
installed: true
```
Your application doesn't have to be managed or deployed by GitLab to leverage this feature.
[Read more](../../clusters/applications.md#install-cilium-using-gitlab-cicd)
about configuring Container Network Policy.
## Install GitLab Container Host Security
Similarly, you can install Container Host Security, based on
[Falco](https://falco.org/), in your `.gitlab/managed-apps/config.yaml`:
```yaml
falco:
installed: true
```
[Read more](../../clusters/applications.md#install-falco-using-gitlab-cicd)
about configuring Container Host Security.
<!-- This redirect file can be deleted after <2021-04-01>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7