diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-01 18:12:07 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-01 18:12:07 +0300 |
commit | 7b197a72aac71c97cf234401a585aba58841ed64 (patch) | |
tree | 29212c9616269c257430a8cb5c247e45cbf17c7c /doc | |
parent | a53033814ddff597cd05244f378915bacdcb5aea (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/.vale/gitlab/InternalLinkExtension.yml | 4 | ||||
-rw-r--r-- | doc/api/group_protected_environments.md | 2 | ||||
-rw-r--r-- | doc/api/protected_environments.md | 2 | ||||
-rw-r--r-- | doc/ci/cloud_services/index.md | 2 | ||||
-rw-r--r-- | doc/ci/environments/deployment_safety.md | 4 | ||||
-rw-r--r-- | doc/ci/testing/unit_test_reports.md | 2 | ||||
-rw-r--r-- | doc/ci/yaml/artifacts_reports.md | 2 | ||||
-rw-r--r-- | doc/integration/jenkins.md | 2 | ||||
-rw-r--r-- | doc/security/img/allowlist_v13_0.png | bin | 16076 -> 0 bytes | |||
-rw-r--r-- | doc/security/webhooks.md | 109 | ||||
-rw-r--r-- | doc/user/project/import/github.md | 2 |
11 files changed, 65 insertions, 66 deletions
diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 5783c4347a9..52142b50dfc 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -5,9 +5,9 @@ # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence -message: 'Link "%s" must use the .md file extension.' +message: 'Link "%s" must link directly to a file and use the .md file extension.' link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation level: error scope: raw raw: - - '\[.+\]\([\w\/\.-]+\.html[^)]*\)' + - '\[[^\]]+\]\([^:\)]+(\/(#[^\)]+)?\)|\.html(#.+)?\))' diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 8a7a3ecd3bc..3f1d932e0c8 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -15,7 +15,7 @@ Read more about [group-level protected environments](../ci/environments/protecte ## Valid access levels -The access levels are defined in the `ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. +The access levels are defined in the `ProtectedEnvironments::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. Currently, these levels are recognized: ```plaintext diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 4c6f509a752..5b52d11feda 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -11,7 +11,7 @@ type: concepts, howto ## Valid access levels -The access levels are defined in the `ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. +The access levels are defined in the `ProtectedEnvironments::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. Currently, these levels are recognized: ```plaintext diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index b460af2d96e..0fac5ae112d 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -16,7 +16,7 @@ GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) t - Account on GitLab. - Access to a cloud provider that supports OIDC to configure authorization and create roles. -The original implementation of `CI_JOB_JWT` supports [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/). The updated implementation of `CI_JOB_JWT_V2` supports additional cloud providers with OIDC including AWS, Azure, GCP, and Vault. +The original implementation of `CI_JOB_JWT` supports [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/index.md). The updated implementation of `CI_JOB_JWT_V2` supports additional cloud providers with OIDC including AWS, Azure, GCP, and Vault. NOTE: Configuring OIDC enables JWT token access to the target environments for all pipelines. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 788061b2955..90efc7ba9ef 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deployment safety **(FREE)** -[Deployment jobs](../jobs/#deployment-jobs) are a specific kind of CI/CD +[Deployment jobs](../jobs/index.md#deployment-jobs) are a specific kind of CI/CD job. They can be more sensitive than other jobs in a pipeline, and might need to be treated with extra care. GitLab has several features that help maintain deployment security and stability. @@ -66,7 +66,7 @@ For more information, see [Resource Group documentation](../resource_groups/inde ## Skip outdated deployment jobs The effective execution order of pipeline jobs can vary from run to run, which -could cause undesired behavior. For example, a [deployment job](../jobs/#deployment-jobs) +could cause undesired behavior. For example, a [deployment job](../jobs/index.md#deployment-jobs) in a newer pipeline could finish before a deployment job in an older pipeline. This creates a race condition where the older deployment finishes later, overwriting the "newer" deployment. diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index 6294996c703..28356a62c99 100644 --- a/doc/ci/testing/unit_test_reports.md +++ b/doc/ci/testing/unit_test_reports.md @@ -156,7 +156,7 @@ If parsing JUnit report XML results in an error, an indicator is shown next to t ![Test Reports With Errors](img/pipelines_junit_test_report_with_errors_v13_10.png) -For test case parsing limits, see [Max test cases per unit test report](../../user/gitlab_com/#gitlab-cicd). +For test case parsing limits, see [Max test cases per unit test report](../../user/gitlab_com/index.md#gitlab-cicd). GitLab does not parse very [large nodes](https://nokogiri.org/tutorials/parsing_an_html_xml_document.html#parse-options) of JUnit reports. There is [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268035) open to make this optional. diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index 43482134d2f..d68432e567e 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -169,7 +169,7 @@ GitLab can display the results of one or more reports in: - The pipeline [**Security** tab](../../user/application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline). - The [security dashboard](../../user/application_security/security_dashboard/index.md). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The [dependency list](../../user/application_security/dependency_list/). +- The [dependency list](../../user/application_security/dependency_list/index.md). ## `artifacts:reports:dotenv` diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 5b779f22bd3..e174e02546a 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -177,7 +177,7 @@ If you get this error message while configuring GitLab, the following are possib - GitLab is unable to reach your Jenkins instance at the address. If your GitLab instance is self-managed, try pinging the Jenkins instance at the domain provided on the GitLab instance. - The Jenkins instance is at a local address and is not included in the - [GitLab installation's allowlist](../security/webhooks.md#allowlist-for-local-requests). + [GitLab installation's allowlist](../security/webhooks.md#create-an-allowlist-for-local-requests). - The credentials for the Jenkins instance do not have sufficient access or are invalid. - The **Enable authentication for `/project` end-point** checkbox is not selected in your [Jenkin's plugin configuration](#configure-the-jenkins-server). 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/webhooks.md b/doc/security/webhooks.md index dcd4c76ab65..b2973155950 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -7,78 +7,80 @@ type: concepts, reference, howto # Webhooks and insecure internal web services **(FREE SELF)** -Users with at least the Maintainer role can set up [Webhooks](../user/project/integrations/webhooks.md) that are +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. +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. +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 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. +Webhook requests are made by the GitLab server itself and use a single optional secret token per hook for authorization +instead of: -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`. +- A user token. +- A repository-specific token. -## Allow requests to local network +As a result, these requests can have broader access than intended, including access to everything running on the server +that hosts the webhook including: -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. +- 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. -This behavior can be overridden: +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 **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 **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 - ![Outbound local requests allowlist](img/allowlist_v13_0.png) +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 **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 @@ -89,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 diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 3dcf9bed6c7..b75b8493d7a 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) +- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). |