diff options
Diffstat (limited to 'doc/security/rack_attack.md')
| -rw-r--r-- | doc/security/rack_attack.md | 156 |
1 files changed, 106 insertions, 50 deletions
diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 8695b5d2194..b99bfb16829 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -1,7 +1,10 @@ --- type: reference, howto --- -# Rack Attack + +# Rack Attack initializer + +## Overview [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 @@ -13,19 +16,72 @@ If you find throttling is not enough to protect you against abusive clients, Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering, and tracking. -**Note:** Starting with 11.2, Rack Attack is disabled by default. To continue -using Rack Attack, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). +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: **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: **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 +will be enabled: + +- Protected paths will be throttled. +- Failed authentications for Git and container registry requests will 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: + +```ruby +default['gitlab']['gitlab-rails']['rack_attack_protected_paths'] = [ + '/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' +] +``` + +This header is included in responses to blocked requests: + +``` +Retry-After: 60 +``` + +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. -By default, user sign-in, user sign-up (if enabled), and user password reset is -limited to 6 requests per minute. After trying for 6 times, the client will -have to wait for the next minute to be able to try again. +This applies only to Git requests and container registry (`/jwt/auth`) requests +(combined). -If you installed or upgraded GitLab by following the [official guides](../install/README.md), -Rack Attack should be disabled by default. If your instance is not exposed to any incoming -connections, it is recommended that you leave Rack Attack disabled. +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. -For more information on how to use these options check out -[rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md). +No response headers are provided. ## Settings @@ -34,34 +90,34 @@ For more information on how to use these options check out 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 - } - ``` + ```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: - ``` - sudo gitlab-ctl reconfigure - ``` + ``` + 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 v12.1 and up. - For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"]`. + CIDR notation is supported in GitLab v12.1 and up. + 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. + specified time. - `findtime`: The maximum amount of time that failed requests can count against an IP - before it's blacklisted (in seconds). + before it's blacklisted (in seconds). - `bantime`: The total amount of time that a blacklisted IP will be blocked (in - seconds). + seconds). **Installations from source** @@ -71,25 +127,25 @@ 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 - ``` + ```ruby + config.middleware.use Rack::Attack + ``` 1. Copy `config/initializers/rack_attack.rb.example` to `config/initializers/rack_attack.rb` 1. Open `config/initializers/rack_attack.rb`, review the `paths_to_be_protected`, and add any other path you need protecting 1. Restart GitLab: - ```sh - sudo service gitlab restart - ``` + ```sh + 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, more relaxed throttle rules will be if you set `limit: 3` and `period: 1.seconds` (this will allow 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 do not forget to restart your +variable. If you change any of these settings you must restart your GitLab instance. ## Remove blocked IPs from Rack Attack via Redis @@ -98,28 +154,28 @@ In case you want to remove a blocked IP, follow these steps: 1. Find the IPs that have been blocked in the production log: - ```sh - grep "Rack_Attack" /var/log/gitlab/gitlab-rails/auth.log - ``` + ```sh + 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`: - ```sh - /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket - ``` + ```sh + /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: - ``` - del cache:gitlab:rack::attack:allow2ban:ban:<ip> - ``` + ``` + del cache:gitlab:rack::attack:allow2ban:ban:<ip> + ``` 1. Confirm that the key with the IP no longer shows up: - ``` - keys *rack::attack* - ``` + ``` + keys *rack::attack* + ``` 1. Optionally, add the IP to the whitelist to prevent it from being blacklisted again (see [settings](#settings)). @@ -136,8 +192,8 @@ the load balancer. In that case, you will need to: 1. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings). 1. Reconfigure GitLab: - ``` - sudo gitlab-ctl reconfigure - ``` + ``` + sudo gitlab-ctl reconfigure + ``` 1. [Remove the block via Redis.](#remove-blocked-ips-from-rack-attack-via-redis) |