Commit 0f8fc0b0 authored by Evan Read's avatar Evan Read

Refactor protected paths UI and documentation

Changelog: other
parent 1d154fa0
......@@ -2,30 +2,26 @@
= form_errors(@application_setting)
%fieldset
- if omnibus_protected_paths_throttle?
.bs-callout.bs-callout-danger
- relative_url_link = 'https://docs.gitlab.com/ee/user/admin_area/settings/protected_paths.html#migrate-settings-from-gitlab-123-and-earlier'
- relative_url_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: relative_url_link }
= _("Omnibus Protected Paths throttle is active, and takes priority over these settings. From 12.4, Omnibus throttle is deprecated and will be removed in a future release. Please read the %{relative_url_link_start}Migrating Protected Paths documentation%{relative_url_link_end}.").html_safe % { relative_url_link_start: relative_url_link_start, relative_url_link_end: '</a>'.html_safe }
.form-group
.form-check
= f.check_box :throttle_protected_paths_enabled, class: 'form-check-input'
= f.label :throttle_protected_paths_enabled, class: 'form-check-label' do
= _('Enable protected paths rate limit')
= _('Enable rate limiting for POST requests to the specified paths')
%span.form-text.text-muted
= _('Helps reduce request volume for protected paths')
= _('Helps reduce request volume for protected paths.')
.form-group
= f.label :throttle_protected_paths_requests_per_period, 'Max requests per period per user', class: 'label-bold'
= f.label :throttle_protected_paths_requests_per_period, 'Maximum requests per period per user', class: 'label-bold'
= f.number_field :throttle_protected_paths_requests_per_period, class: 'form-control gl-form-input'
.form-group
= f.label :throttle_protected_paths_period_in_seconds, 'Rate limit period in seconds', class: 'label-bold'
= f.label :throttle_protected_paths_period_in_seconds, 'Rate limit period (in seconds)', class: 'label-bold'
= f.number_field :throttle_protected_paths_period_in_seconds, class: 'form-control gl-form-input'
.form-group
= f.label :protected_paths, class: 'label-bold' do
= _('Paths to protect with rate limiting')
= f.text_area :protected_paths_raw, placeholder: '/users/sign_in,/users/password', class: 'form-control gl-form-input', rows: 10
%span.form-text.text-muted
- relative_url_link = 'https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab'
- relative_url_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: relative_url_link }
= _('All paths are relative to the GitLab URL. Do not include %{relative_url_link_start}relative URL%{relative_url_link_end}.').html_safe % { relative_url_link_start: relative_url_link_start, relative_url_link_end: '</a>'.html_safe }
= f.text_area :protected_paths_raw, placeholder: '/users/sign_in,/users/password', class: 'form-control gl-form-input', rows: 10
= _('All paths are relative to the GitLab URL. Do not include %{relative_url_link_start}relative URLs%{relative_url_link_end}.').html_safe % { relative_url_link_start: relative_url_link_start, relative_url_link_end: '</a>'.html_safe }
= f.submit _('Save changes'), class: 'gl-button btn btn-confirm'
......@@ -87,14 +87,12 @@
%section.settings.as-protected-paths.no-animate#js-protected-paths-settings{ class: ('expanded' if expanded_by_default?) }
.settings-header
%h4
= _('Protected Paths')
= _('Protected paths')
%button.btn.gl-button.btn-default.js-settings-toggle{ type: 'button' }
= expanded_by_default? ? _('Collapse') : _('Expand')
%p
= _('Configure paths to be protected by Rack Attack.')
.help-block
= _('These paths are protected for POST requests.')
= link_to _('More information'), help_page_path('security/rack_attack', anchor: 'protected-paths-throttle'), target: '_blank'
= _('Rate limit access to specified paths.')
= link_to _('Learn more.'), help_page_path('user/admin_area/settings/protected_paths.md'), target: '_blank', rel: 'noopener noreferrer'
.settings-content
= render 'protected_paths'
......
......@@ -150,6 +150,7 @@ denormalized
denormalizes
denormalizing
denylist
denylisted
denylisting
denylists
deployer
......
......@@ -15,9 +15,7 @@ performance, data, or could even exhaust the allocated resources for the applica
Rate limits can be used to improve the security and durability of GitLab.
For example, one script can make thousands of web requests per second. Whether malicious, apathetic, or just a bug, your application and infrastructure may not be able to cope with the load. Rate limits can help to mitigate these types of attacks.
Read more about [configuring rate limits](../security/rate_limits.md) in the Security documentation.
Read more about [configuring rate limits](../security/rate_limits.md).
### Issue creation
......@@ -128,16 +126,6 @@ This setting limits the import/export actions for groups and projects.
Read more about [import/export rate limits](../user/admin_area/settings/import_export_rate_limits.md).
### Rack attack
This method of rate limiting is cumbersome, but has some advantages. It allows
throttling of specific paths, and is also integrated into Git and container
registry requests.
Read more about the [Rack Attack initializer](../security/rack_attack.md) method of setting rate limits.
- **Default rate limit**: Disabled.
### Member Invitations
Limit the maximum daily member invitations allowed per group hierarchy.
......
......@@ -752,7 +752,6 @@ Depending on your installation method, this file is located at:
This log records:
- Information whenever [Rack Attack](../security/rack_attack.md) registers an abusive request.
- Requests over the [Rate Limit](../user/admin_area/settings/rate_limits_on_raw_endpoints.md) on raw endpoints.
- [Protected paths](../user/admin_area/settings/protected_paths.md) abusive requests.
- In GitLab versions [12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/29239) and later,
......
......@@ -411,11 +411,11 @@ listed in the descriptions of the relevant settings.
| `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. |
| `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. |
| `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
| `throttle_authenticated_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_api_enabled` | Rate limit period in seconds. |
| `throttle_authenticated_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_api_enabled` | Max requests per period per user. |
| `throttle_authenticated_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_api_enabled` | Rate limit period (in seconds). |
| `throttle_authenticated_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_api_enabled` | Maximum requests per period per user. |
| `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
| `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period in seconds. |
| `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Max requests per period per user. |
| `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period (in seconds). |
| `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Maximum requests per period per user. |
| `throttle_unauthenticated_enabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_enabled` or `throttle_unauthenticated_api_enabled` instead.) (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). |
| `throttle_unauthenticated_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_period_in_seconds` or `throttle_unauthenticated_api_period_in_seconds` instead.) Rate limit period in seconds. |
| `throttle_unauthenticated_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_requests_per_period` or `throttle_unauthenticated_api_requests_per_period` instead.) Max requests per period per IP. |
......
---
stage: Manage
group: Access
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
type: reference, howto
redirect_to: '../user/admin_area/settings/protected_paths.md'
remove_date: '2022-01-14'
---
# Rack Attack initializer **(FREE SELF)**
This document was moved to [another location](../user/admin_area/settings/protected_paths.md).
[Rack Attack](https://github.com/kickstarter/rack-attack), also known as Rack::Attack, is a Ruby gem
that is meant to protect GitLab with the ability to customize throttling and
to block user IP addresses.
You can prevent brute-force passwords attacks, scrapers, or any other offenders
by throttling requests from IP addresses that are making large volumes of requests.
If you find throttling is not enough to protect you against abusive clients,
Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering, and
tracking.
For more information on how to use these options see the [Rack Attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md).
NOTE:
See
[User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md)
for simpler limits that are configured in the UI.
NOTE:
Starting with GitLab 11.2, Rack Attack is disabled by default. If your
instance is not exposed to the public internet, it is recommended that you leave
Rack Attack disabled.
## Behavior
If set up as described in the [Settings](#settings) section below, two behaviors
are enabled:
- Protected paths are throttled.
- Failed authentications for Git and container registry requests trigger a temporary IP ban.
### Protected paths throttle
GitLab responds with HTTP status code `429` to POST requests at protected paths
that exceed 10 requests per minute per IP address.
By default, protected paths are:
- `/users/password`
- `/users/sign_in`
- `/api/#{API::API.version}/session.json`
- `/api/#{API::API.version}/session`
- `/users`
- `/users/confirmation`
- `/unsubscribes/`
- `/import/github/personal_access_token`
- `/admin/session`
See [User and IP rate limits](../user/admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests.
For example, the following are limited to a maximum 10 requests per minute:
- User sign-in
- User sign-up (if enabled)
- User password reset
After 10 requests, the client must wait a minute before it can
try again.
### Git and container registry failed authentication ban
GitLab responds with HTTP status code `403` for 1 hour, if 30 failed
authentication requests were received in a 3-minute period from a single IP address.
This applies only to Git requests and container registry (`/jwt/auth`) requests
(combined).
This limit:
- Is reset by requests that authenticate successfully. For example, 29
failed authentication requests followed by 1 successful request, followed by 29
more failed authentication requests would not trigger a ban.
- Does not apply to JWT requests authenticated by `gitlab-ci-token`.
No response headers are provided.
## Settings
**Omnibus GitLab**
1. Open `/etc/gitlab/gitlab.rb` with your editor
1. Add the following:
```ruby
gitlab_rails['rack_attack_git_basic_auth'] = {
'enabled' => true,
'ip_whitelist' => ["127.0.0.1"],
'maxretry' => 10, # Limit the number of Git HTTP authentication attempts per IP
'findtime' => 60, # Reset the auth attempt counter per IP after 60 seconds
'bantime' => 3600 # Ban an IP for one hour (3600s) after too many auth attempts
}
```
1. Reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
The following settings can be configured:
- `enabled`: By default this is set to `false`. Set this to `true` to enable Rack Attack.
- `ip_whitelist`: Whitelist any IPs from being blocked. They must be formatted as strings within a Ruby array.
CIDR notation is supported in GitLab 12.1 and later.
For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"]`.
- `maxretry`: The maximum amount of times a request can be made in the
specified time.
- `findtime`: The maximum amount of time that failed requests can count against an IP
before it's blacklisted (in seconds).
- `bantime`: The total amount of time that a blacklisted IP is blocked (in
seconds).
**Installations from source**
These settings can be found in `config/initializers/rack_attack.rb`. If you are
missing `config/initializers/rack_attack.rb`, the following steps need to be
taken in order to enable protection for your GitLab instance:
1. In `config/application.rb` find and uncomment the following line:
```ruby
config.middleware.use Rack::Attack
```
1. Restart GitLab:
```shell
sudo service gitlab restart
```
If you want more restrictive/relaxed throttle rules, edit
`config/initializers/rack_attack.rb` and change the `limit` or `period` values.
For example, you can set more relaxed throttle rules with
`limit: 3` and `period: 1.seconds`, allowing 3 requests per second.
You can also add other paths to the protected list by adding to `paths_to_be_protected`
variable. If you change any of these settings you must restart your
GitLab instance.
## Remove blocked IPs from Rack Attack via Redis
In case you want to remove a blocked IP, follow these steps:
1. Find the IPs that have been blocked in the production log:
```shell
grep "Rack_Attack" /var/log/gitlab/gitlab-rails/auth.log
```
1. Since the blacklist is stored in Redis, you need to open up `redis-cli`:
```shell
/opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket
```
1. You can remove the block using the following syntax, replacing `<ip>` with
the actual IP that is blacklisted:
```plaintext
del cache:gitlab:rack::attack:allow2ban:ban:<ip>
```
1. Confirm that the key with the IP no longer shows up:
```plaintext
keys *rack::attack*
```
1. Optionally, add the IP to the whitelist to prevent it from being blacklisted
again (see [settings](#settings)).
## Troubleshooting
### Rack attack is blacklisting the load balancer
Rack Attack may block your load balancer if all traffic appears to come from
the load balancer. In that case, you must:
1. [Configure `nginx[real_ip_trusted_addresses]`](https://docs.gitlab.com/omnibus/settings/nginx.html#configuring-gitlab-trusted_proxies-and-the-nginx-real_ip-module).
This keeps users' IPs from being listed as the load balancer IPs.
1. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings).
1. Reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
1. [Remove the block via Redis.](#remove-blocked-ips-from-rack-attack-via-redis)
<!-- This redirect file can be deleted after <2022-01-14>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
......@@ -14,9 +14,13 @@ For GitLab.com, please see
Rate limiting is a common technique used to improve the security and durability
of a web application.
For example, a simple script can make thousands of web requests per second.
Whether malicious, apathetic, or just a bug, your application and infrastructure
may not be able to cope with the load. For more details, see
For example, a simple script can make thousands of web requests per second. The requests could be:
- Malicious.
- Apathetic.
- Just a bug.
Your application and infrastructure may not be able to cope with the load. For more details, see
[Denial-of-service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack).
Most cases can be mitigated by limiting the rate of requests from a single IP address.
......@@ -25,7 +29,7 @@ similarly mitigated by a rate limit.
## Admin Area settings
These are rate limits you can set in the Admin Area of your instance:
You can set these rate limits in the Admin Area of your instance:
- [Import/Export rate limits](../user/admin_area/settings/import_export_rate_limits.md)
- [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creation.md)
......@@ -38,14 +42,36 @@ These are rate limits you can set in the Admin Area of your instance:
- [Files API rate limits](../user/admin_area/settings/files_api_rate_limits.md)
- [Deprecated API rate limits](../user/admin_area/settings/deprecated_api_rate_limits.md)
## Failed authentication ban for Git and container registry
GitLab returns HTTP status code `403` for 1 hour, if 30 failed authentication requests were received
in a 3-minute period from a single IP address. This applies only to combined:
- Git requests.
- Container registry (`/jwt/auth`) requests.
This limit:
- Is reset by requests that authenticate successfully. For example, 29 failed authentication
requests followed by 1 successful request, followed by 29 more failed authentication requests
would not trigger a ban.
- Does not apply to JWT requests authenticated by `gitlab-ci-token`.
- Is disabled by default.
No response headers are provided.
For configuration information, see
[Omnibus GitLab configuration options](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-failed-authentication-ban).
## Non-configurable limits
### Repository archives
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25750) in GitLab 12.9.
There is a rate limit for [downloading repository archives](../api/repositories.md#get-file-archive),
which applies to the project and to the user initiating the download either through the UI or the API.
A rate limit for [downloading repository archives](../api/repositories.md#get-file-archive) is
available. The limit applies to the project and to the user initiating the download either through
the UI or the API.
The **rate limit** is 5 requests per minute per user.
......@@ -57,8 +83,50 @@ There is a rate limit for [testing webhooks](../user/project/integrations/webhoo
The **rate limit** is 5 requests per minute per user.
## Rack Attack initializer
## Troubleshooting
### Rack Attack is denylisting the load balancer
Rack Attack may block your load balancer if all traffic appears to come from
the load balancer. In that case, you must:
1. [Configure `nginx[real_ip_trusted_addresses]`](https://docs.gitlab.com/omnibus/settings/nginx.html#configuring-gitlab-trusted_proxies-and-the-nginx-real_ip-module).
This keeps users' IPs from being listed as the load balancer IPs.
1. Allowlist the load balancer's IP addresses.
1. Reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
### Remove blocked IPs from Rack Attack with Redis
To remove a blocked IP:
1. Find the IPs that have been blocked in the production log:
```shell
grep "Rack_Attack" /var/log/gitlab/gitlab-rails/auth.log
```
1. Since the denylist is stored in Redis, you must open up `redis-cli`:
```shell
/opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket
```
1. You can remove the block using the following syntax, replacing `<ip>` with
the actual IP that is denylisted:
```plaintext
del cache:gitlab:rack::attack:allow2ban:ban:<ip>
```
1. Confirm that the key with the IP no longer shows up:
```plaintext
keys *rack::attack*
```
This method of rate limiting is cumbersome, but has some advantages. It allows
throttling of specific paths, and is also integrated into Git and container
registry requests. See [Rack Attack initializer](rack_attack.md).
1. Optionally, add [the IP to the allowlist](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-rack-attack)
to prevent it being denylisted again.
......@@ -7,28 +7,11 @@ type: reference
# Protected paths **(FREE SELF)**
Rate limiting is a common technique used to improve the security and durability
of a web application. For more details, see
[Rate limits](../../../security/rate_limits.md).
Rate limiting is a technique that improves the security and durability of a web
application. For more details, see [Rate limits](../../../security/rate_limits.md).
GitLab rate limits the following paths with Rack Attack by default:
```plaintext
'/users/password',
'/users/sign_in',
'/api/#{API::API.version}/session.json',
'/api/#{API::API.version}/session',
'/users',
'/users/confirmation',
'/unsubscribes/',
'/import/github/personal_access_token',
'/admin/session'
```
GitLab responds with HTTP status code `429` to POST requests at protected paths
that exceed 10 requests per minute per IP address.
See [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers) for the headers responded to blocked requests.
You can rate limit (protect) specified paths. For these paths, GitLab responds with HTTP status
code `429` to POST requests at protected paths that exceed 10 requests per minute per IP address.
For example, the following are limited to a maximum 10 requests per minute:
......@@ -36,10 +19,15 @@ For example, the following are limited to a maximum 10 requests per minute:
- User sign-up (if enabled)
- User password reset
After 10 requests, the client must wait 60 seconds before it can
try again.
After 10 requests, the client must wait 60 seconds before it can try again.
See also:
- List of paths [protected by default](../../../administration/instance_limits.md#by-protected-path).
- [User and IP rate limits](../../admin_area/settings/user_and_ip_rate_limits.md#response-headers)
for the headers returned to blocked requests.
## Configure using GitLab UI
## Configure protected paths
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31246) in GitLab 12.4.
......
......@@ -3331,7 +3331,7 @@ msgstr ""
msgid "All merge request dependencies have been merged"
msgstr ""
msgid "All paths are relative to the GitLab URL. Do not include %{relative_url_link_start}relative URL%{relative_url_link_end}."
msgid "All paths are relative to the GitLab URL. Do not include %{relative_url_link_start}relative URLs%{relative_url_link_end}."
msgstr ""
msgid "All projects"
......@@ -8647,9 +8647,6 @@ msgstr ""
msgid "Configure existing installation"
msgstr ""
msgid "Configure paths to be protected by Rack Attack."
msgstr ""
msgid "Configure repository mirroring."
msgstr ""
......@@ -12703,7 +12700,7 @@ msgstr ""
msgid "Enable or disable version check and Service Ping."
msgstr ""
msgid "Enable protected paths rate limit"
msgid "Enable rate limiting for POST requests to the specified paths"
msgstr ""
msgid "Enable reCAPTCHA"
......@@ -16841,7 +16838,7 @@ msgstr ""
msgid "Helps reduce request volume (for example, from crawlers or abusive bots)"
msgstr ""
msgid "Helps reduce request volume for protected paths"
msgid "Helps reduce request volume for protected paths."
msgstr ""
msgid "Here you will find recent merge request activity"
......@@ -23619,9 +23616,6 @@ msgstr ""
msgid "OmniAuth"
msgstr ""
msgid "Omnibus Protected Paths throttle is active, and takes priority over these settings. From 12.4, Omnibus throttle is deprecated and will be removed in a future release. Please read the %{relative_url_link_start}Migrating Protected Paths documentation%{relative_url_link_end}."
msgstr ""
msgid "On"
msgstr ""
......@@ -24754,6 +24748,9 @@ msgstr ""
msgid "Paths can contain wildcards, like */welcome"
msgstr ""
msgid "Paths to protect with rate limiting"
msgstr ""
msgid "Pause"
msgstr ""
......@@ -27637,9 +27634,6 @@ msgstr ""
msgid "Protected Environment"
msgstr ""
msgid "Protected Paths"
msgstr ""
msgid "Protected Paths: requests"
msgstr ""
......@@ -27655,6 +27649,9 @@ msgstr ""
msgid "Protected environments"
msgstr ""
msgid "Protected paths"
msgstr ""
msgid "ProtectedBranch|%{wildcards_link_start}Wildcards%{wildcards_link_end} such as %{code_tag_start}*-stable%{code_tag_end} or %{code_tag_start}production/*%{code_tag_end} are supported."
msgstr ""
......@@ -28027,6 +28024,9 @@ msgstr ""
msgid "Rate limit"
msgstr ""
msgid "Rate limit access to specified paths."
msgstr ""
msgid "Rate limits can help reduce request volume (like from crawlers or abusive bots)."
msgstr ""
......@@ -34672,9 +34672,6 @@ msgstr ""
msgid "These existing issues have a similar title. It might be better to comment there instead of creating another similar issue."
msgstr ""
msgid "These paths are protected for POST requests."
msgstr ""
msgid "These runners are shared across projects in this group."
msgstr ""
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment