diff options
Diffstat (limited to 'doc/security')
| -rw-r--r-- | doc/security/rack_attack.md | 196 | ||||
| -rw-r--r-- | doc/security/rate_limits.md | 96 | ||||
| -rw-r--r-- | doc/security/token_overview.md | 5 |
3 files changed, 95 insertions, 202 deletions
diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index b0bebc5a956..a8b55007d2e 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -1,195 +1,9 @@ --- -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 --> diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 4585748ffc2..9d49297c9de 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -14,18 +14,22 @@ 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. Most [brute-force attacks](https://en.wikipedia.org/wiki/Brute-force_attack) are similarly mitigated by a rate limit. -## Admin Area settings +## Configurable limits -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,40 @@ 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) +You can set these rate limits using the Rails console: + +- [Webhook rate limit](../administration/instance_limits.md#webhook-rate-limit) + +## 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 +87,52 @@ 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* + ``` + + By default, the [`keys` command is disabled](https://docs.gitlab.com/omnibus/settings/redis.html#renamed-commands). -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. diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 2a971b21840..333548fa1c9 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -117,4 +117,9 @@ Instead, API calls can be passed an access token using headers, like [the `Priva 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. |