diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-06-20 13:43:29 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-06-20 13:43:29 +0300 |
commit | 3b1af5cc7ed2666ff18b718ce5d30fa5a2756674 (patch) | |
tree | 3bc4a40e0ee51ec27eabf917c537033c0c5b14d4 /doc/security | |
parent | 9bba14be3f2c211bf79e15769cd9b77bc73a13bc (diff) |
Add latest changes from gitlab-org/gitlab@16-1-stable-eev16.1.0-rc42
Diffstat (limited to 'doc/security')
-rw-r--r-- | doc/security/hardening.md | 67 | ||||
-rw-r--r-- | doc/security/hardening_application_recommendations.md | 243 | ||||
-rw-r--r-- | doc/security/hardening_cicd_recommendations.md | 69 | ||||
-rw-r--r-- | doc/security/hardening_configuration_recommendations.md | 161 | ||||
-rw-r--r-- | doc/security/hardening_general_concepts.md | 88 | ||||
-rw-r--r-- | doc/security/hardening_operating_system_recommendations.md | 167 | ||||
-rw-r--r-- | doc/security/identity_verification.md | 43 | ||||
-rw-r--r-- | doc/security/index.md | 2 | ||||
-rw-r--r-- | doc/security/password_length_limits.md | 6 | ||||
-rw-r--r-- | doc/security/reset_user_password.md | 5 | ||||
-rw-r--r-- | doc/security/ssh_keys_restrictions.md | 5 | ||||
-rw-r--r-- | doc/security/token_overview.md | 12 | ||||
-rw-r--r-- | doc/security/two_factor_authentication.md | 9 | ||||
-rw-r--r-- | doc/security/unlock_user.md | 14 | ||||
-rw-r--r-- | doc/security/user_email_confirmation.md | 7 | ||||
-rw-r--r-- | doc/security/user_file_uploads.md | 4 | ||||
-rw-r--r-- | doc/security/webhooks.md | 12 |
17 files changed, 893 insertions, 21 deletions
diff --git a/doc/security/hardening.md b/doc/security/hardening.md new file mode 100644 index 00000000000..21b8594fc6e --- /dev/null +++ b/doc/security/hardening.md @@ -0,0 +1,67 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab Hardening Recommendations **(FREE SELF)** + +This documentation is for GitLab instances where the overall system can be "hardened" +against common and even not-so-common attacks. It is not designed to completely +eradicate attacks, but to provide strong mitigation thereby reducing overall risk. Some +of the techniques apply to any GitLab deployment, such as SaaS or self-managed, while other +techniques apply to the underlying OS. + +These techniques are a work in progress, and have not been tested at scale +(such as a large environments with many users). They have been tested on a self-managed +single instance running a Linux package installation, and while many of the techniques can +translated to other deployment types, they may not all work or apply. + +Most of the listed recommendations provide specific recommendations or +reference choices one can make based upon the general documentation. +Through hardening, there may be impact to certain features your users may specifically +want or depend on, so you should communicate with users and do a phased rollout of hardening +changes. + +The hardening instructions are in five categories for easier +understanding. They are listed in the following section. + +## GitLab hardening general concepts + +This details information on hardening as an approach to security and some of the larger +philosophies. For more information, see [hardening general concepts](hardening_general_concepts.md). + +## GitLab application settings + +Application settings made using the GitLab GUI to the application itself. For more information, see +[application recommendations](hardening_application_recommendations.md). + +## GitLab CI/CD settings + +CI/CD is a core component of GitLab, and while application of security principles +are based upon needs, there are several things you can do to make your CI/CD more secure. +For more information, see [CI/CD Recommendations](hardening_cicd_recommendations.md). + +## GitLab configuration settings + +Configuration file settings used to control and configure the +application (such as `gitlab.rb`) are documented separately. For more information, see the +[configuration recommendations](hardening_configuration_recommendations.md). + +## Operating System settings + +You can adjust the underlying operating system to increase overall security. For more information, see the +[operating system recommendations](hardening_operating_system_recommendations.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/hardening_application_recommendations.md b/doc/security/hardening_application_recommendations.md new file mode 100644 index 00000000000..9d4d2d562fd --- /dev/null +++ b/doc/security/hardening_application_recommendations.md @@ -0,0 +1,243 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Hardening - Application Recommendations + +For general hardening guidelines, see the [main hardening documentation](hardening.md). + +You control the hardening recommendations for GitLab instances through the +web interface. + +## System hooks + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **System Hooks**. + +In a typical hardened environment, internal information is not transmitted or stored +outside of the system. For an offline environment system, this is +implied. System hooks provide a way for local events in the environment to communicate +information outside of the environment based upon triggers. + +Use cases for this capability are supported, particularly monitoring the +system through a remote system. +However, you must apply extreme caution when deploying system hooks. For hardened +systems, if they are intended to be an offline environment, a perimeter of trusted +systems allowed to communicate with each other must be enforced, so any hooks +(system, web, or file) must only communicate with those trusted systems. TLS is strongly +encouraged for communications through system hooks. + +## Push rules + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Push Rules**. + +Ensure that the following items are selected: + +- **Reject unverified users** +- **Do not allow users to remove Git tags with `git push`** +- **Check whether the commit author is a GitLab user** +- **Prevent pushing secret files** + +The adjustments help limit pushes to established and authorized users. + +## Deploy keys + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Deploy Keys**. + +Public deploy keys at are used to give read or read/write access to +**all** projects on the instance, and are intended for remote automation to access +projects. Public deploy keys should not be used in a hardened environment. If you +must use deploy keys, use project deploy keys instead. For more information, refer to +the documentation on [deploy keys](../user/project/deploy_keys/index.md) and +[project deploy keys](../user/project/deploy_keys/index.md#create-a-project-deploy-key). + +## General + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. + +Hardening adjustments can be made in 4 sections. + +### Visibility and access control + +The default for the following settings is **Private**: + +- **Default project visibility** +- **Default snippet visibility** +- **Default group visibility** + +Only users that are granted specific access to a project, snippet, or group can +access these resources. This can be adjusted later as needed or at the time of +their creation. This helps prevent accidental or malicious disclosure of information. + +Depending on your security policy and posture, you might wish to set your +**Restricted visibility level** to **Public**, as this prevents user profiles +from being viewed by non-authenticated users. + +In **Import sources**, select only the sources you really need. + +A typical deployment has **Enabled Git access protocols** set to **Both SSH and HTTP(S)**, +however if one of the Git protocols is not in use by your users, set it to either +**Only SSH** or **Only HTTP(S)** accordingly. This helps shrink the attack surface. + +For SSH key types, the following are preferred: `ED25519` (and `ED25519-SK`), `RSA`, and +`ECDSA` (and `ECDSA-SK`) in that order. `ED25519` is considered as secure as `RSA` when +`RSA` is set to 2048 bits or higher, however the `ED25519` keys are smaller and the +algorithm is much faster. + +`ED25519-SK` and `ECDSA-SK` both end with `-SK` which stands for +"Security Key". The `-SK` types are compatible with FIDO/U2F standards and pertain to +usage with hardware tokens, for example YubiKeys. + +`DSA` should be set to "Are forbidden". `DSA` has known flaws, and many cryptographers +are suspicious of and do not support using `ECDSA`. + +If GitLab is in FIPS mode, use the following: + +- If running in FIPS mode: + - Use `RSA`, set to **Must be at least 2048 bits**. + - Use `ECDSA` (and `ECDSA-SK`), set to **Must be at least 256 bits**. + - Set all other key types to **Are forbidden**. + `RSA` and `ECDSA` are both approved for FIPS use. +- If not running in FIPS mode, you must use `ED25519` and can also use `RSA`: + - Set `ED25519` (and `ED25519-SK`) to **Must be at least 256 bits**. + - If using `RSA`, set it to **Must be at least 2048 bits**. + - Set all other key types to **Are forbidden**. +- If you are setting up an instance for a new group of users, define your user SSH +key policy with the maximum bits settings for added security. + +In a hardened environment RSS feeds are typically not required, and in **Feed token**, +select the **Disabled feed token** checkbox. + +If all of your users are coming from specific IP addresses, use **Global-allowed IP ranges** +to specifically allow only those addresses. + +For more details on **Visibility and access control**, see [visibility and access controls](../user/admin_area/settings/visibility_and_access_controls.md). +For information on SSH settings, see +[SSH keys restrictions](../security/ssh_keys_restrictions.md). + +### Account and limit + +For hardening purposes, ensure the checkbox next to **Gravatar enabled** is not selected. +All extraneous communications should be curtailed, and in some environments might be +restricted. Account avatars can be manually uploaded by users. + +The settings in this section are intended to help enforce a custom implementation +of your own specific standards on your users. As the various scenarios are too many +and too varied, you should review the +[account and limit settings documentation](../user/admin_area/settings/account_and_limit_settings.md) +and apply changes to enforce your own policies. + +### Sign-up restrictions + +Ensure open sign-up is disabled on your hardened instance. Ensure the **Sign-up enabled** checkbox is not selected. + +In **Email confirmation settings**, ensure that **Hard** is selected. User verification +of their email address is now enforced before access is granted. + +The **Minimum password length (number of characters)** default setting is 12 which +should be fine as long as additional authentication techniques are used. The password +should be complex, so ensure that all four of these checkboxes are selected: + +- **Require numbers** +- **Require uppercase letters** +- **Require lowercase letters** +- **Require symbols** + +If all of your users belong to the same organization that uses a specific domain for +email addresses, then list that domain in **Allowed domains for sign-ups**. This +prevents those with email addresses in other domains from signing up. + +For more detailed information, see +[sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md). + +### Sign-in restrictions + +Two-factor authentication (2FA) should be enabled for all users. Ensure that the +checkbox next to **Two-factor authentication** (2FA) is selected. + +The default setting for **Two-factor grace period** is 48 hours. This should be adjusted +to a much lower value, such as 8 hours. + +Ensure the checkbox next to **Enable admin mode** is selected so that **Admin Mode** is +active. This requires users with Admin access to have to use additional +authentication in order to perform administrative tasks, enforcing additional 2FA by the user. + +In **Email notification for unknown sign-ins**, ensure that **Enable email notification** +is selected. This sends an email to users when a sign-in occurs from an unrecognized location. + +For more detailed information, see +[sign-in restrictions](../user/admin_area/settings/sign_in_restrictions.md). + +## Integrations + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Integrations**. + +In general, as long as administrators control and monitor usage, integrations +are fine in a hardened environment. Be cautious about integrations that allow +for actions from an outside system that trigger actions and processes that typically +require a level of access you would restrict or audit if performed by a local +process or authenticated user. + +## Metrics and profiling + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Metrics and profiling**. + +The main focus for hardening is **Usage statistics**: + +- You should make sure **Enable version check** is selected. This checks to see if you +are running the latest version of GitLab, and as new versions with new features and +security patches come out frequently, this helps you stay up to date. + +- If your environment is isolated or one where your organizational requirements +restrict data gathering and statistics reporting to a software vendor, you may have +to disable the **Enable service ping** feature. For more information on what data is collected to +help you make an informed decision, see +[service ping](../development/service_ping/index.md). + +## Network + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > Network**. + +For any setting that enables rate limiting, make sure it is selected. Default values +should be fine. Additionally there are numerous settings that enable access, and all +of these should be cleared. + +After you've made these adjustments you can fine tune the system to meet performance +and user needs, which may require disabling and adjusting rate limits or enabling +accesses. Here are a few notables to keep in mind: + +- In **Outbound requests**, if you need to open up access to a limited +number of systems, you can limit access to just those systems by specifying +IP address or hostname. Also in this section, make sure you've selected +**Enforce DNS rebinding attack protection** if you're allowing any access at all. + +- Under **Notes rate limit** and **Users API rate limit** you can exclude specific users +from those limits if needed. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/hardening_cicd_recommendations.md b/doc/security/hardening_cicd_recommendations.md new file mode 100644 index 00000000000..16b649cbdd7 --- /dev/null +++ b/doc/security/hardening_cicd_recommendations.md @@ -0,0 +1,69 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Hardening - CI/CD Recommendations + +General hardening guidelines and philosophies are outlined in the [main hardening documentation](hardening.md). + +The hardening recommendations and concepts for CI/CD are listed below. + +## Basic Recommendations + +How you configure the different CI/CD settings depends on your use of CI/CD. For example if you are using it to build +packages, you often need real-time access to external resources such as Docker +images or external code repositories. If you are using it for Infrastructure +as Code (IaC), you often need to store credentials for external systems to +automate deployment. For these and many other scenarios, you need to store +potentially sensitive information to be used during CI/CD operations. As the +individual scenarios themselves are numerous, we have summarized some basic +information to help harden the CI/CD process. + +- **Secrets Management**. Passwords, tokens, keys, and other secrets that require any +level of protection should never be stored in plaintext. Some type of encrypted +container technology should be used, such as GCP Secret Manager, AWS KMS, or +HashiCorp Vault. For self-managed and standalone instances, HashiCorp Vault is +recommended, and many GitLab features can take advantage of Vault and are well +documented in the main [Documentation](../index.md). For detailed CI/CD examples, see [using external secrets in CI](../ci/secrets/index.md). +- **External Communications**. If your CI/CD process requires connectivity to other +hosts, ensure that these communication channels are encrypted. You should use TLS 1.2 or 1.3, and where possible implement mutual TLS. +- **Logging**. Logging can be very important for auditing and troubleshooting, so it +is important that you enable any logging features to ensure you are getting +the information in logs you need. Make sure through periodic testing that +plaintext secrets or other sensitive information is not inadvertently added to log +files. + +## Specific Recommendations + +### Pipelines + +Pipelines are a part of jobs that execute steps in stages to automate tasks on behalf +of the users of a project. They are a core component of CD/CD. + +By default, only the default branch gets a protected pipeline. An owner of a project +can ensure that other branches are protected by +[configuring a protected branch](../user/project/protected_branches.md). +This allows for more restricted security on pipelines. For more information, see +[pipeline security on a protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +Deployment is the part of the CI/CD that deploys the results of the pipeline in +relationship to a given environment. Default settings do not impose many +restrictions, and as different users with different roles and responsibilities can +trigger pipelines that can interact with those environments, you should +restrict these environments. For more information, see +[protected environments](../ci/environments/protected_environments.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/hardening_configuration_recommendations.md b/doc/security/hardening_configuration_recommendations.md new file mode 100644 index 00000000000..475ec06835c --- /dev/null +++ b/doc/security/hardening_configuration_recommendations.md @@ -0,0 +1,161 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Hardening - Configuration Recommendations + +General hardening guidelines are outlined in the [main hardening documentation](hardening.md). + +Some hardening recommendations for GitLab instances involve additional +services or control through configuration files. As a reminder, any time you are +making changes to configuration files, make backup copies of +them before editing. Additionally, if you are making a lot of changes it is +recommended you do not do all of the changes at once, and test them after each +change to ensure everything is working. + +## NGINX + +NGINX is used to serve up the web interface used to access the GitLab instance. As +NGINX is controlled and integrated into GitLab, modification of the +`/etc/gitlab/gitlab.rb` file used for adjustments. Here are a few recommendations for helping to improve +the security of NGINX itself: + +```shell +# +# Only strong ciphers are used +# +nginx['ssl_ciphers'] = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256" +# +# Follow preferred ciphers and the order listed as preference +# +nginx['ssl_prefer_server_ciphers'] = "on" +# +# Only allow TLSv1.2 and TLSv1.3 +# +nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3" + +##! **Recommended in: https://nginx.org/en/docs/http/ngx_http_ssl_module.html** +nginx['ssl_session_cache'] = "builtin:1000 shared:SSL:10m" + +##! **Default according to https://nginx.org/en/docs/http/ngx_http_ssl_module.html** +nginx['ssl_session_timeout'] = "5m" + +# Should prevent logjam attack etc +# For the example below, run the following first: +# openssl dhparam -out /etc/gitlab/ssl/dhparam.pem 4096 +nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem" # changed from nil + +# Turn off session ticket reuse +nginx['ssl_session_tickets'] = "off" +# Pick our own curve instead of what openssl hands us +nginx['ssl_ecdh_curve'] = "secp384r1" +``` + +## Consul + +Consul can be integrated into a GitLab environment, and is intended for larger +deployments. In general for self-managed and standalone deployments with less than +1000 users, Consul may not be needed. If it is needed, first review the +[documentation on Consul](../administration/consul.md), but +more importantly ensure that encryption is used during communications. For more +detailed information on Consul visit the +[HashiCorp website](https://developer.hashicorp.com/consul/docs) to understand how it +works, and review the information on +[encryption security](https://developer.hashicorp.com/consul/docs/security/encryption). + +## Environment Variables + +You can customize multiple +[environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) +on self-managed systems. The main environment variable to +take advantage of from a security perspective is `GITLAB_ROOT_PASSWORD` during the +installation process. If you are installing the self-managed system with a +public-facing IP address exposed to the Internet, make sure the password is set to +something strong. Historically, setting up any type of public-facing service - whether +it is GitLab or some other application - has shown that opportunistic attacks occur +as soon as those systems are discovered, so the hardening process should start during +the installation process. + +As mentioned in the [operating system recommendations](hardening_operating_system_recommendations.md) +ideally there should be firewall rules already in place before the GitLab +installation begins, but you should still set a secure password before the +installation through `GITLAB_ROOT_PASSWORD`. + +## Git Protocols + +To ensure that only authorized users are using SSH for Git access, add the following +to your `/etc/ssh/sshd_config` file: + +```shell +# Ensure only authorized users are using Git +AcceptEnv GIT_PROTOCOL +``` + +This ensures that users cannot pull down projects using SSH unless they have a valid +GitLab account that can perform `git` operations over SSH. More details can be found +under [Configuring Git Protocol](../administration/git_protocol.md). + +## Incoming Email + +You can configure a GitLab self-managed instance to allow for incoming email to be +used for commenting or creating issues and merge requests by registered users on +the GitLab instance. In a hardened environment you should not configure +this feature as it involves outside communications sending in information. + +If the feature is required, follow the instructions in the +[incoming email documentation](../administration/incoming_email.md), with +the following recommendations to ensure maximum security: + +- Dedicate an email address specifically for inbound emails to the instance. +- Use [email sub-addressing](../administration/incoming_email.md). +- Email accounts used by users to send emails should require and have multi-factor authentication (MFA) enabled on those accounts. +- For Postfix specifically, follow the [set up Postfix for incoming email documentation](../administration/reply_by_email_postfix_setup.md). + +## Redis Replication and Failover + +Redis is used on a Linux package installation for replication and failover, and can be +set up when scaling requires that capability. Bear in mind that this opens TCP ports +`6379` for Redis and `26379` for Sentinel. Follow the +[replication and failover documentation](../administration/redis/replication_and_failover.md) +but note the IP addresses of all of the nodes, and set up firewall rules between +nodes that only allow the other node to access those particular ports. + +## Sidekiq Configuration + +In the [instructions for configuring an external Sidekiq](../administration/sidekiq/index.md) +there are numerous references to configuring IP ranges. You must +[configure HTTPS](../administration/sidekiq/index.md#enable-https), +and consider restricting those IP addresses to specific systems that Sidekiq talks to. +You might have to adjust firewall rules at the operating system level as well. + +## S/MIME Signing of Email + +If the GitLab instance is configured for sending out email notifications to users, +configure S/MIME signing to help the recipients ensure that the emails are +legitimate. Follow the instructions on [signing outgoing email](../administration/smime_signing_email.md). + +## Container Registry + +If Lets Encrypt is configured, the Container Registry is enabled by default. This +allows projects to store their own Docker images. Follow the instructions for +configuring the [Container Registry](../administration/packages/container_registry.md), +so you can do things like restrict automatic enablement on new projects and +disabling the Container Registry entirely. You may have to adjust firewall rules to +allow access - if a completely standalone system, you should restrict access to the +Container Registry to localhost only. Specific examples of ports used and their +configuration are also included in the documentation. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/hardening_general_concepts.md b/doc/security/hardening_general_concepts.md new file mode 100644 index 00000000000..a227f0134d0 --- /dev/null +++ b/doc/security/hardening_general_concepts.md @@ -0,0 +1,88 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Hardening - General Concepts + +General hardening guidelines are outlined in the [main hardening documentation](hardening.md). + +The following documentation summarises some of the underlying philosophies for GitLab instance hardening. +While we reference GitLab, in many cases they can actually apply to all computer systems. + +## Layered security + +If there are two ways to implement security, both ways should be implemented instead of +just one. A quick example is account security: + +- Use a long, complex, and unique password for the account. +- Implement a second factor to the authentication process for added security. +- Use a hardware token as a second factor. +- Lock out an account (for at least a fixed amount of time) for failed authentication +attempts. +- An account that is unused for a specific time frame should be disabled, enforce this +with either automation or regular audits. + +Instead of using only one or two items on the list, use as many as possible. This +philosophy can apply to other areas besides account security - it should be applied to +every area possible. + +## Eliminate security through obscurity + +Security through obscurity means that one does not discuss certain +elements of a system, service, or process because of a fear that a potential attacker +might use those details to formulate an attack. Instead, the system should be secured to +the point that details about its configuration could be public and the system would still +be as secure as it could be. In essence, if an attacker learned about the details of the +configuration of a computer system it would not give them an advantage. One of the +downsides of security through obscurity is that it can lead to a potential false sense of +security by the administrator of the system who thinks the system is more secure than it +actually is. + +An example of this is running a service on a non-standard TCP port. For example the +default SSH daemon port on servers is TCP port 22, but it is possible to configure the +SSH daemon to run on another port such as TCP port 2222. The administrator who configured +this might think it increases the security of the system, however it is quite common for +an attacker to port scan a system to discover all open ports, allowing for quick discovery +of the SSH service, and eliminating any perceived security advantage. + +As GitLab is an open-core system and all of the configuration options are well documented +and public information, the idea of security through obscurity goes against a +GitLab core value - transparency. These hardening recommendations are intended to be +public, to help eliminate any security through obscurity. + +## Attack Surface Reduction + +GitLab is a large system with many components. As a general rule for security, it helps +if unused systems are disabled. This eliminates the +available "attack surface" a potential attacker can use to strike. This can also have +the added advantage of increasing available system resources as well. + +As an example, there is a process on a system that fires up and checks queues for input every +five minutes, querying multiple sub-processes while performing its checks. If you are not +using that process, there is no reason to have it configured and it should be disabled. +If an attacker has figured out an attack vector that uses this process, the attacker might exploit it despite your organization not using it. As a general +rule, you should disable any service not being used. + +## External systems + +In larger but still hardened deployments, multiple nodes are often used to +handle the load your GitLab deployment +requires. In those cases, use a combination of external, operating system, and +configuration options for firewall rules. Any option that uses restrictions should only +be opened up enough to allow the subsystem to function. Whenever possible use TLS +encryption for network traffic. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/hardening_operating_system_recommendations.md b/doc/security/hardening_operating_system_recommendations.md new file mode 100644 index 00000000000..8b4b706815c --- /dev/null +++ b/doc/security/hardening_operating_system_recommendations.md @@ -0,0 +1,167 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Hardening - Operating System Recommendations + +General hardening guidelines are outlined in the [main hardening documentation](hardening.md). + +You can configure the underlying operating system to increase overall security. In a +a controlled environment such as a self-managed GitLab instance it requires additional +steps, and in fact is often required for certain deployments. FedRAMP is an example of +such a deployment. + +## SSH Configuration + +### SSH Client Configuration + +For client access (either to the GitLab instance or to the underlying operating +system), here are a couple of recommendations for SSH key generation. The first one +is a typical SSH key: + +```shell +ssh-keygen -a 64 -t ed25519 -f ~/.ssh/id_ed25519 -C "ED25519 Key" +``` + +For a FIPS-compliant SSH key, use the following: + +```shell +ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -C "RSA FIPS-compliant Key" +``` + +### SSH Server Configuration + +At the operating system level, if you are allowing SSH access (typically through +OpenSSH), here is an example of configuration options for the `sshd_config` file +(the exact location may vary depending on the operating system but it is usually +`/etc/ssh/sshd_config`): + +```shell +# +# Example sshd config file. This supports public key authentication and +# turns off several potential security risk areas +# +PubkeyAuthentication yes +PasswordAuthentication yes +UsePAM yes +UseDNS no +AllowTcpForwarding no +X11Forwarding no +PrintMotd no +PermitTunnel no +# Allow client to pass locale environment variables +AcceptEnv LANG LC_* +# override default of no subsystems +Subsystem sftp /usr/lib/openssh/sftp-server +# Protocol adjustments, these would be needed/recommended in a FIPS or +# FedRAMP deployment, and use only strong and proven algorithm choices +Protocol 2 +Ciphers aes128-ctr,aes192-ctr,aes256-ctr +HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521 +KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521 +Macs hmac-sha2-256,hmac-sha2-512 + +``` + +## Firewall Rules + +For firewall rules, only TCP ports `80` and `443` need to be open for basic usage. By +default, `5050` is open for remote access to the container registry, however in a +hardened environment this would most likely exist on a different host, and in some +environments not open at all. Hence, the recommendation is for ports `80` and `443` +only, and port `80` should only be used to redirect to `443`. + +For a truly hardened or isolated environment such as FedRAMP, you should adjust the firewall rules to restrict all ports except to those networks +accessing it. For example, if the IP address is `192.168.1.2` and all of the authorized +clients are also on `192.168.1.0/24`, restrict access to ports `80` and `443` to just +`192.168.1.0/24` only (as a safety restriction), even if access is restricted +elsewhere with another firewall. + +Ideally, if you're installing a self-managed instance, you should implement the firewall rules before the installation begins with access restricted to the admins and installers, and only add additional ranges of IP addresses for +users after the instance is installed and properly hardened. + +Usage of `iptables` or `ufw` is acceptable to implement and enforce port `80` and `443` +access on a per-host basis, otherwise usage of cloud-based firewall rules through GCP +Google Compute or AWS Security Groups should enforce this. All other ports should +be blocked, or at least restricted to specific ranges. For more information on ports, see +[Package Defaults](../administration/package_information/defaults.md). + +### Firewall Additions + +It is possible that various services may be enabled that require external access +(for example Sidekiq) and need network access to be opened up. Restrict these types +of services to specific IP addresses, or a specific Class C. As a layered and added +precaution, where possible restrict these extra services to specific nodes or +sub-networks in GitLab. + +## Kernel Adjustments + +Kernel adjustments can be made by editing `/etc/sysctl.conf`, or one of the files in +`/etc/sysctl.d/`. Kernel adjustments do not completely eliminate the threat of an +attack, but add an extra layer of security. The following notes explain +some of the advantages for these adjustments. + +```shell +## Kernel tweaks for sysctl.conf ## +## +## The following help mitigate out of bounds, null pointer dereference, heap and +## buffer overflow bugs, use-after-free etc from being exploited. It does not 100% +## fix the issues, but seriously hampers exploitation. +## +# Default is 65536, 4096 helps mitigate memory issues used in exploitation +vm.mmap_min_addr=4096 +# Default is 0, randomize virtual address space in memory, makes vuln exploitation +# harder +kernel.randomize_va_space=2 +# Restrict kernel pointer access (e.g. cat /proc/kallsyms) for exploit assistance +kernel.kptr_restrict=2 +# Restrict verbose kernel errors in dmesg +kernel.dmesg_restrict=1 +# Restrict eBPF +kernel.unprivileged_bpf_disabled=1 +net.core.bpf_jit_harden=2 +# Prevent common use-after-free exploits +vm.unprivileged_userfaultfd=0 + +## Networking tweaks ## +## +## Prevent common attacks at the IP stack layer +## +# Prevent SYNFLOOD denial of service attacks +net.ipv4.tcp_syncookies=1 +# Prevent time wait assassination attacks +net.ipv4.tcp_rfc1337=1 +# IP spoofing/source routing protection +net.ipv4.conf.all.rp_filter=1 +net.ipv4.conf.default.rp_filter=1 +net.ipv6.conf.all.accept_ra=0 +net.ipv6.conf.default.accept_ra=0 +net.ipv4.conf.all.accept_source_route=0 +net.ipv4.conf.default.accept_source_route=0 +net.ipv6.conf.all.accept_source_route=0 +net.ipv6.conf.default.accept_source_route=0 +# IP redirection protection +net.ipv4.conf.all.accept_redirects=0 +net.ipv4.conf.default.accept_redirects=0 +net.ipv4.conf.all.secure_redirects=0 +net.ipv4.conf.default.secure_redirects=0 +net.ipv6.conf.all.accept_redirects=0 +net.ipv6.conf.default.accept_redirects=0 +net.ipv4.conf.all.send_redirects=0 +net.ipv4.conf.default.send_redirects=0 +``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, for example `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/identity_verification.md b/doc/security/identity_verification.md new file mode 100644 index 00000000000..761bc114da2 --- /dev/null +++ b/doc/security/identity_verification.md @@ -0,0 +1,43 @@ +--- +stage: Anti-Abuse +group: Anti-Abuse +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Identity verification **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95722) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `identity_verification`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +This feature is not ready for production use. + +Identity verification provides multiple layers of GitLab account security. +Depending on your [risk score](../integration/arkose.md), you might be required to perform up to +three stages of verification to register an account: + +- **All users** - Email verification. +- **Medium-risk users** - Phone number verification. +- **High-risk users** - Credit card verification. + +## Email verification + +To register an account, you must provide a valid email address. +See [Account email verification](email_verification.md). + +## Phone number verification + +In addition to email verification, you might have to provide a valid phone number and verify a one-time code. + +You cannot verify an account with a phone number associated with a banned user. + +## Credit card verification + +In addition to email and phone number verification, you might have to provide a valid credit card number. + +You cannot verify an account with a credit card number associated with a banned user. + +## Related topics + +- [Identity verification development documentation](../development/identity_verification.md) +- [Changing risk assessment support](https://about.gitlab.com/handbook/support/workflows/reinstating-blocked-accounts.html#change-risk-assessment-credit-card-verification) diff --git a/doc/security/index.md b/doc/security/index.md index 7a78461d717..a62d7171112 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -27,6 +27,6 @@ type: index - [Project Import decompressed archive size limits](project_import_decompressed_archive_size_limits.md) - [Responding to security incidents](responding_to_security_incidents.md) -To harden your GitLab instance and minimize the risk of unwanted user account creation, consider access control features like [Sign up restrictions](../user/admin_area/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/index.md) . +To harden your GitLab instance and minimize the risk of unwanted user account creation, consider access control features like [Sign up restrictions](../user/admin_area/settings/sign_up_restrictions.md) and [Authentication options](../topics/authentication/index.md). For more detailed information, refer to [Hardening](hardening.md). Self-managed GitLab customers and administrators are responsible for the security of their underlying hosts, and for keeping GitLab itself up to date. It is important to [regularly patch GitLab](../policy/maintenance.md), patch your operating system and its software, and harden your hosts in accordance with vendor guidance. diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 0211a326e0a..d8e9728f455 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -24,8 +24,10 @@ The user password length is set to a minimum of 8 characters by default. To change the minimum password length using GitLab UI: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** and expand **Sign-up restrictions**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Sign-up restrictions**. 1. Enter a **Minimum password length** value greater than or equal to `8`. 1. Select **Save changes**. diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index f8ba3953379..7adb6256259 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -20,9 +20,10 @@ The user's new password must meet all [password requirements](../user/profile/us To reset a user's password in the UI: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. -1. For the user whose password you want to update, select **Edit** (**{pencil-square}**). +1. For the user whose password you want to update, select **Edit**. 1. In the **Password** area, type a password and password confirmation. 1. Select **Save changes**. diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index f15d71461d4..1e4a4226138 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -20,8 +20,9 @@ limit the allowed SSH key algorithms. GitLab allows you to restrict the allowed SSH key technology as well as specify the minimum key length for each technology: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General** . 1. Expand the **Visibility and access controls** section: ![SSH keys restriction Admin Area settings](img/ssh_keys_restrictions_settings.png) diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 8acd4a125ce..5a772106562 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -20,6 +20,10 @@ You can create [Personal access tokens](../user/profile/personal_access_tokens.m You can limit the scope and expiration date of your personal access tokens. By default, they inherit permissions from the user who created them. +You can use the [personal access tokens API](../api/personal_access_tokens.md) to +programmatically take action, such as +[rotating a personal access token](../api/personal_access_tokens.md#rotate-a-personal-access-token). + ## OAuth2 tokens GitLab can serve as an [OAuth2 provider](../api/oauth2.md) to allow other services to access the GitLab API on a user's behalf. @@ -47,6 +51,10 @@ You can limit the scope and expiration date of project access tokens. When you create a project access token, GitLab creates a [bot user for projects](../user/project/settings/project_access_tokens.md#bot-users-for-projects). Bot users for projects are service accounts and do not count as licensed seats. +You can use the [project access tokens API](../api/project_access_tokens.md) to +programmatically take action, such as +[rotating a project access token](../api/project_access_tokens.md#rotate-a-project-access-token). + ## Group access tokens [Group access tokens](../user/group/settings/group_access_tokens.md#group-access-tokens) @@ -60,6 +68,10 @@ You can limit the scope and expiration date of group access tokens. When you create a group access token, GitLab creates a [bot user for groups](../user/group/settings/group_access_tokens.md#bot-users-for-groups). Bot users for groups are service accounts and do not count as licensed seats. +You can use the [group access tokens API](../api/group_access_tokens.md) to +programmatically take action, such as +[rotating a group access token](../api/group_access_tokens.md#rotate-a-group-access-token). + ## Deploy tokens [Deploy tokens](../user/project/deploy_tokens/index.md) allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. Deploy tokens cannot be used with the GitLab API. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 9ac799610bb..25937993c16 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -29,8 +29,9 @@ cannot leave the 2FA configuration area at `/-/profile/two_factor_auth`. To enable 2FA for all users: -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. 1. Expand the **Sign-in restrictions** section, where you can configure both. If you want 2FA enforcement to take effect during the next sign-in attempt, @@ -55,8 +56,8 @@ Prerequisites: To enforce 2FA only for certain groups: -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select **All users in this group must set up two-factor authentication**. 1. Select **Save changes**. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 279f466e106..e8215616e1b 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -7,14 +7,26 @@ type: howto # Locked users **(FREE SELF)** +## Self-managed users + Users are locked after ten failed sign-in attempts. These users remain locked: - For 10 minutes, after which time they are automatically unlocked. - Until an administrator unlocks them from the [Admin Area](../user/admin_area/index.md) or the command line in under 10 minutes. +## GitLab.com users + +If 2FA is not enabled users are locked after three failed sign-in attempts within 24 hours. These users remain locked until: + +- Their next successful sign-in, at which point they are sent an email with a six-digit unlock code and redirected to a verification page where they can unlock their account by entering the code. +- GitLab Support [manually unlock](https://about.gitlab.com/handbook/support/workflows/reinstating-blocked-accounts.html#manual-unlock) the account after account ownership is verified. + +If 2FA is enabled, users are locked after five failed sign-in attempts within 10 minutes. Accounts are unlocked automatically after 10 minutes. + ## Unlock a user from the Admin Area -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. Use the search bar to find the locked user. 1. From the **User administration** dropdown list, select **Unlock**. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 962f6f0fd61..f2c0052c2b8 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -11,9 +11,10 @@ GitLab can be configured to require confirmation of a user's email address when the user signs up. When this setting is enabled, the user is unable to sign in until they confirm their email address. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). -1. Expand the **Sign-up restrictions** section and look for the **Email confirmation settings** options. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Sign-up restrictions** and look for the **Email confirmation settings** options. ## Confirmation token expiry diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 498245c4efb..5895eda8cdd 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -47,8 +47,8 @@ Prerequisite: To configure authentication settings for all media files: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll to **Project visibility** and select **Require authentication to view media files**. diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 774bfa106f6..13b34d28614 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -50,7 +50,8 @@ To prevent exploitation of insecure internal web services, all webhook and integ To allow access to these addresses: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. 1. Select the **Allow requests to the local network from webhooks and integrations** checkbox. @@ -63,7 +64,8 @@ Prerequisite: [System hooks](../administration/system_hooks.md) can make requests to the local network by default. To prevent system hook requests to the local network: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. 1. Clear the **Allow requests to the local network from system hooks** checkbox. @@ -78,7 +80,8 @@ Prerequisite: To filter requests by blocking many requests: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. 1. Select the **Block all requests, except for IP addresses, IP ranges, and domain names defined in the allowlist** checkbox. @@ -103,7 +106,8 @@ Prerequisite: To allow outbound requests to certain IP addresses and domains: -1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Outbound requests**. 1. In **Local IP addresses and domain names that hooks and integrations can access**, enter your IP addresses and domains. |