webhooks.md 4.86 KB
Newer Older
1
---
Craig Norris's avatar
Craig Norris committed
2 3
stage: none
group: unassigned
4
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
5 6
type: concepts, reference, howto
---
7

Ashley Smith's avatar
Ashley Smith committed
8
# Webhooks and insecure internal web services
9

10
NOTE:
11
On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#webhooks) per project, and per group, is limited.
Russell Dickenson's avatar
Russell Dickenson committed
12

13 14
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.
15

16
With [Webhooks](../user/project/integrations/webhooks.md), you and your project
17
maintainers and owners can set up URLs to be triggered when specific changes
18 19 20
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.
21

22 23 24 25
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.
26

27 28
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
29
repository-specific token). As a result, these may have broader access than
30 31 32 33 34 35
intended to everything running on the server hosting the webhook (which
may include the GitLab server or API itself, e.g., `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 (e.g.,
`http://192.168.1.12:345`), even if these services are otherwise protected
and inaccessible from the outside world.
36

37 38 39
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`.
40

41 42
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
43
private network are forbidden by default. That means that all requests made
44
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`,
45
`192.168.0.0/16` and IPv6 site-local (`ffc0::/10`) addresses aren't allowed.
46

47
This behavior can be overridden by enabling the option *"Allow requests to the
48
local network from web hooks and services"* in the *"Outbound requests"* section
49
inside the **Admin Area > Settings** (`/admin/application_settings/network`):
50

51
![Outbound requests admin settings](img/outbound_requests_section_v12_2.png)
52

53
NOTE:
54 55 56
*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.
57

Amy Qualls's avatar
Amy Qualls committed
58
## Allowlist for local requests
59

60
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44496) in GitLab 12.2
61 62 63

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
Amy Qualls's avatar
Amy Qualls committed
64
allowlist. Navigate to **Admin Area > Settings > Network** (`/admin/application_settings/network`)
65 66
and expand **Outbound requests**:

Amy Qualls's avatar
Amy Qualls committed
67
![Outbound local requests allowlist](img/allowlist_v13_0.png)
68

Amy Qualls's avatar
Amy Qualls committed
69
The allowed entries can be separated by semicolons, commas or whitespaces
70
(including newlines) and be in different formats like hostnames, IP addresses and/or
71
IP ranges. IPv6 is supported. Hostnames that contain Unicode characters should
72 73
use IDNA encoding.

Amy Qualls's avatar
Amy Qualls committed
74
The allowlist can hold a maximum of 1000 entries. Each entry can be a maximum of
75 76
255 characters.

Amy Qualls's avatar
Amy Qualls committed
77
You can allow a particular port by specifying it in the allowlist entry.
78
For example `127.0.0.1:8080` only allows connections to port 8080 on `127.0.0.1`.
Amy Qualls's avatar
Amy Qualls committed
79
If no port is mentioned, all ports on that IP/domain are allowed. An IP range
80
allows all ports on all IPs in that range.
81

82 83
Example:

84
```plaintext
85 86 87
example.com;gitlab.example.com
127.0.0.1,1:0:0:0:0:0:0:1
127.0.0.0/8 1:0:0:0:0:0:0:0/124
88 89 90
[1:0:0:0:0:0:0:1]:8080
127.0.0.1:8080
example.com:8080
91 92
```

93
NOTE:
94
Wildcards (`*.example.com`) are not currently supported.
95

96 97 98 99 100 101 102 103 104 105 106
<!-- ## 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, e.g. `### 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. -->