diff options
Diffstat (limited to 'doc/security')
| -rw-r--r-- | doc/security/img/allowlist_v13_0.png | bin | 16076 -> 0 bytes | |||
| -rw-r--r-- | doc/security/img/outbound_requests_section_v12_2.png | bin | 6303 -> 0 bytes | |||
| -rw-r--r-- | doc/security/information_exclusivity.md | 2 | ||||
| -rw-r--r-- | doc/security/password_length_limits.md | 2 | ||||
| -rw-r--r-- | doc/security/ssh_keys_restrictions.md | 2 | ||||
| -rw-r--r-- | doc/security/token_overview.md | 27 | ||||
| -rw-r--r-- | doc/security/two_factor_authentication.md | 4 | ||||
| -rw-r--r-- | doc/security/unlock_user.md | 2 | ||||
| -rw-r--r-- | doc/security/user_email_confirmation.md | 2 | ||||
| -rw-r--r-- | doc/security/user_file_uploads.md | 2 | ||||
| -rw-r--r-- | doc/security/webhooks.md | 134 |
11 files changed, 84 insertions, 93 deletions
diff --git a/doc/security/img/allowlist_v13_0.png b/doc/security/img/allowlist_v13_0.png Binary files differdeleted file mode 100644 index 973b53a57a4..00000000000 --- a/doc/security/img/allowlist_v13_0.png +++ /dev/null diff --git a/doc/security/img/outbound_requests_section_v12_2.png b/doc/security/img/outbound_requests_section_v12_2.png Binary files differdeleted file mode 100644 index 3dc99868a35..00000000000 --- a/doc/security/img/outbound_requests_section_v12_2.png +++ /dev/null diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 754d5fff843..2eeb436316f 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -24,7 +24,7 @@ limitation. You can take steps to prevent unintentional sharing and information destruction. This limitation is the reason why only certain people are allowed to [add users to a project](../user/project/members/index.md) -and why only a GitLab administrator can +and why only a GitLab administrator can [force push a protected branch](../user/project/protected_branches.md). <!-- ## Troubleshooting diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 04c3a5c99e1..57466d1ed5d 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -30,7 +30,7 @@ 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 **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General** and expand **Sign-up restrictions**.  diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index eca52c41e4f..138ebb9858a 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -20,7 +20,7 @@ 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 **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General** (`/admin/application_settings/general`). 1. Expand the **Visibility and access controls** section: diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index a2119c86268..e585f2caeca 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -124,17 +124,16 @@ This table shows available scopes per token. Scopes can be limited further on to ## Security considerations -Access tokens should be treated like passwords and kept secure. - -Adding them to URLs is a security risk. This is especially true when cloning or adding a remote, as Git then writes the URL to its `.git/config` file in plain text. URLs are also generally logged by proxies and application servers, which makes those credentials visible to system administrators. - -Instead, API calls can be passed an access token using headers, like [the `Private-Token` header](../api/index.md#personalprojectgroup-access-tokens). - -Tokens can also be stored using a [Git credential storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). - -Tokens should not be committed to your source code. Instead, consider an approach such as [using external secrets in CI](../ci/secrets/index.md). - -When creating a scoped token, consider using the most limited scope possible to reduce the impact of accidentally leaking the token. - -When creating a token, consider setting a token that expires when your task is complete. For example, if performing a one-off import, set the -token to expire after a few hours or a day. This reduces the impact of a token that is accidentally leaked because it is useless when it expires. +- Access tokens should be treated like passwords and kept secure. +- Adding access tokens to URLs is a security risk, especially when cloning or adding a remote because Git then writes the URL to its `.git/config` file in plain text. URLs are + also generally logged by proxies and application servers, which makes those credentials visible to system administrators. Instead, pass API calls an access token using + headers like [the `Private-Token` header](../api/index.md#personalprojectgroup-access-tokens). +- Tokens can also be stored using a [Git credential storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). +- Tokens should not be committed to your source code. Instead, consider an approach such as [using external secrets in CI](../ci/secrets/index.md). +- When creating a scoped token, consider using the most limited scope possible to reduce the impact of accidentally leaking the token. +- When creating a token, consider setting a token that expires when your task is complete. For example, if performing a one-off import, set the + token to expire after a few hours or a day. This reduces the impact of a token that is accidentally leaked because it is useless when it expires. +- Be careful not to include tokens when pasting code, console commands, or log outputs into an issue or MR description or comment. +- Don’t log credentials in the console logs. Consider [protecting](../ci/variables/index.md#protected-cicd-variables) and + [masking](../ci/variables/index.md#mask-a-cicd-variable) your credentials. +- Review all currently active access tokens of all types on a regular basis and revoke any that are no longer needed. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 93d77a69f0e..c808cf4e321 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -26,7 +26,7 @@ cannot leave the 2FA configuration area at `/-/profile/two_factor_auth`. To enable 2FA for all users: -1. On the top bar, select **Menu > Admin**. +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-in restrictions** section, where you can configure both. @@ -52,7 +52,7 @@ Prerequisites: To enforce 2FA only for certain groups: -1. On the top bar, select **Menu > Groups** and find your group. +1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. 1. Select **All users in this group must set up two-factor authentication**. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index efe9c5784ad..041527f18af 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -14,7 +14,7 @@ Users are locked after ten failed sign-in attempts. These users remain locked: ## Unlock a user from the Admin Area -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Use the search bar to find the locked user. 1. From the **User administration** dropdown select **Unlock**. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 54920b15362..172e26db618 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -11,7 +11,7 @@ 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 **Menu > Admin**. +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 **Send confirmation email on sign-up** option. diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 7c11d01396d..ddb8392d2be 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -39,7 +39,7 @@ Prerequisite: To configure authentication settings for all media files: -1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, 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 f2066ee4a42..e1daa705355 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -7,85 +7,80 @@ type: concepts, reference, howto # Webhooks and insecure internal web services **(FREE SELF)** -NOTE: -On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. - -If you have non-GitLab web services running on your GitLab server or within its -local network, these may be vulnerable to exploitation via Webhooks. - -With [Webhooks](../user/project/integrations/webhooks.md), you and your project -maintainers and owners can set up URLs to be triggered when specific changes -occur in your projects. Normally, these requests are sent to external web -services specifically set up for this purpose, that process the request and its -attached data in some appropriate way. - -Things get hairy, however, when a Webhook is set up with a URL that doesn't -point to an external, but to an internal service, that may do something -completely unintended when the webhook is triggered and the POST request is -sent. - -Webhook requests are made by the GitLab server itself and use a single -(optional) secret token per hook for authorization (instead of a user or -repository-specific token). As a result, these requests may have broader access than -intended, including access to everything running on the server hosting the webhook. This -may include the GitLab server or API itself (for example, `http://localhost:123`). -Depending on the called webhook, this may also result in network access -to other servers within that webhook server's local network (for example, -`http://192.168.1.12:345`), even if these services are otherwise protected -and inaccessible from the outside world. - -If a web service does not require authentication, Webhooks can be used to -trigger destructive commands by getting the GitLab server to make POST requests -to endpoints like `http://localhost:123/some-resource/delete`. - -To prevent this type of exploitation from happening, starting with GitLab 10.6, -all Webhook requests to the current GitLab instance server address and/or in a -private network are forbidden by default. That means that all requests made -to `127.0.0.1`, `::1` and `0.0.0.0`, as well as IPv4 `10.0.0.0/8`, `172.16.0.0/12`, -`192.168.0.0/16` and IPv6 site-local (`ffc0::/10`) addresses aren't allowed. - -This behavior can be overridden: - -1. On the top bar, select **Menu > Admin**. +Users with at least the Maintainer role can set up [webhooks](../user/project/integrations/webhooks.md) that are +triggered when specific changes occur in a project. When triggered, a `POST` HTTP request is sent to a URL. A webhook is +usually configured to send data to a specific external web service, which processes the data in an appropriate way. + +However, a webhook can be configured with a URL for an internal web service instead of an external web service. +When the webhook is triggered, non-GitLab web services running on your GitLab server or in its local network could be +exploited. + +Webhook requests are made by the GitLab server itself and use a single optional secret token per hook for authorization +instead of: + +- A user token. +- A repository-specific token. + +As a result, these requests can have broader access than intended, including access to everything running on the server +that hosts the webhook including: + +- The GitLab server. +- The API itself. +- For some webhooks, network access to other servers in that webhook server's local network, even if these services + are otherwise protected and inaccessible from the outside world. + +Webhooks can be used to trigger destructive commands using web services that don't require authentication. These webhooks +can get the GitLab server to make `POST` HTTP requests to endpoints that delete resources. + +## Allow webhook and service requests to local network + +To prevent exploitation of insecure internal web services, all webhook requests to the following local network addresses are not allowed: + +- The current GitLab instance server address. +- Private network addresses, including `127.0.0.1`, `::1`, `0.0.0.0`, `10.0.0.0/8`, `172.16.0.0/12`, + `192.168.0.0/16`, and IPv6 site-local (`ffc0::/10`) addresses. + +To allow access to these addresses: + +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. -1. Expand the **Outbound requests** section: -  -1. Select **Allow requests to the local network from web hooks and services**. +1. Expand **Outbound requests**. +1. Select the **Allow requests to the local network from web hooks and services** checkbox. -NOTE: -*System hooks* are enabled to make requests to local network by default since they are -set up by administrators. However, you can turn this off by disabling the -**Allow requests to the local network from system hooks** option. +## Prevent system hook requests to local network -## Allowlist for local requests +[System hooks](../administration/system_hooks.md) are permitted to make requests to local network by default because +they are set up by administrators. To prevent system hook requests to the local network: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44496) in GitLab 12.2 +1. On the top bar, select **Main menu > Admin**. +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. -You can allow certain domains and IP addresses to be accessible to both *system hooks* -and *webhooks* even when local requests are not allowed by adding them to the -allowlist: +## Create an allowlist for local requests -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > Network** (`/admin/application_settings/network`) - and expand **Outbound requests**: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44496) in GitLab 12.2 -  +You can allow certain domains and IP addresses to be accessible to both system hooks and webhooks, even when local +requests are forbidden. To add these domains to the allowlist: -The allowed entries can be separated by semicolons, commas or whitespaces -(including newlines) and be in different formats like hostnames, IP addresses and/or -IP ranges. IPv6 is supported. Hostnames that contain Unicode characters should -use [Internationalized Domain Names in Applications](https://www.icann.org/en/icann-acronyms-and-terms/internationalized-domain-names-in-applications-en) -(IDNA) encoding. +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Outbound requests** and add entries. -The allowlist can hold a maximum of 1000 entries. Each entry can be a maximum of -255 characters. +The entries can: -You can allow a particular port by specifying it in the allowlist entry. -For example `127.0.0.1:8080` only allows connections to port 8080 on `127.0.0.1`. -If no port is mentioned, all ports on that IP/domain are allowed. An IP range -allows all ports on all IPs in that range. +- Be separated by semicolons, commas, or whitespaces (including newlines). +- Be in different formats like hostnames, IP addresses, IP address ranges. IPv6 is supported. Hostnames that contain + Unicode characters should use [Internationalized Domain Names in Applications](https://www.icann.org/en/icann-acronyms-and-terms/internationalized-domain-names-in-applications-en) + (IDNA) encoding. +- Include ports. For example, `127.0.0.1:8080` only allows connections to port 8080 on `127.0.0.1`. If no port is specified, + all ports on that IP address or domain are allowed. An IP address range allows all ports on all IP addresses in that + range. +- Number no more than 1000 entries of no more than 255 characters for each entry. +- Not contain wildcards (for example, `*.example.com`). -Example: +For example: ```plaintext example.com;gitlab.example.com @@ -96,9 +91,6 @@ example.com;gitlab.example.com example.com:8080 ``` -NOTE: -Wildcards (`*.example.com`) are not currently supported. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues |
