From fc925583dab4dcdaf750bd4aa5d79642fc5c9871 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 7 Jun 2019 13:55:22 +0000 Subject: Add type to frontmatter --- doc/security/README.md | 1 + doc/security/crime_vulnerability.md | 10 +++++++--- doc/security/information_exclusivity.md | 6 +++++- doc/security/password_length_limits.md | 4 ++++ 4 files changed, 17 insertions(+), 4 deletions(-) diff --git a/doc/security/README.md b/doc/security/README.md index a90127e0356..c48d5bc2065 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -1,5 +1,6 @@ --- comments: false +type: index --- # Security diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index d61a205d954..33878830c7b 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # How we manage the TLS protocol CRIME vulnerability > CRIME ("Compression Ratio Info-leak Made Easy") is a security exploit against @@ -7,7 +11,7 @@ authentication cookies, it allows an attacker to perform session hijacking on an authenticated web session, allowing the launching of further attacks. ([CRIME](https://en.wikipedia.org/w/index.php?title=CRIME&oldid=692423806)) -### Description +## Description The TLS Protocol CRIME Vulnerability affects compression over HTTPS, therefore it warns against using SSL Compression (for example gzip) or SPDY which @@ -24,7 +28,7 @@ Although SPDY is enabled in Omnibus installations, CRIME relies on compression (the 'C') and the default compression level in NGINX's SPDY module is 0 (no compression). -### Nessus +## Nessus The Nessus scanner, [reports a possible CRIME vulnerability][nessus] in GitLab similar to the following format: @@ -50,7 +54,7 @@ attack nor does it check if compression is enabled. With just this approach, it cannot tell that SPDY's compression is disabled and not subject to the CRIME vulnerability. -### References +## References - Nginx ["Module ngx_http_spdy_module"][ngx-spdy] - Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"][nessus] diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 22756232025..846bcdfe26e 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,3 +1,7 @@ +--- +type: concepts +--- + # Information exclusivity Git is a distributed version control system (DVCS). @@ -6,4 +10,4 @@ In GitLab every project member that is not a guest (so reporters, developers and After obtaining this local copy the user can upload the full repository anywhere, including another project under their control or another server. The consequence is that you can't build access controls that prevent the intentional sharing of source code by users that have access to the source code. This is an inherent feature of a DVCS and all git management systems have this limitation. -Obviously you can take steps to prevent unintentional sharing and information destruction, this is why only some people are allowed to invite others and nobody can force push a protected branch. +Obviously you can take steps to prevent unintentional sharing and information destruction, this is why only some people are allowed to invite others and nobody can force push a protected branch. \ No newline at end of file diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index d21b26a43e8..3ad78a5c835 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Custom password length limits If you want to enforce longer user passwords you can create an extra Devise initializer with the steps below. -- cgit v1.2.1 From bf926010933fa2ce9d655c0a3df3f57951832975 Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Fri, 7 Jun 2019 14:33:31 +0000 Subject: Various edits to security documentation Edits to conform with CE epic 1280 SSOT standards, other improvements --- doc/security/crime_vulnerability.md | 26 +++++++++++----- doc/security/information_exclusivity.md | 37 +++++++++++++++++----- doc/security/password_length_limits.md | 19 +++++++++-- doc/security/rack_attack.md | 24 ++++++++------ doc/security/reset_root_password.md | 19 +++++++++-- doc/security/ssh_keys_restrictions.md | 15 +++++++++ doc/security/two_factor_authentication.md | 15 +++++++++ doc/security/unlock_user.md | 20 ++++++++++-- doc/security/user_email_confirmation.md | 22 +++++++++++-- doc/security/user_file_uploads.md | 35 ++++++++++++++++----- doc/security/webhooks.md | 52 ++++++++++++++++++++++++++----- 11 files changed, 233 insertions(+), 51 deletions(-) diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 33878830c7b..9665cc0337f 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -13,13 +13,13 @@ authenticated web session, allowing the launching of further attacks. ## Description -The TLS Protocol CRIME Vulnerability affects compression over HTTPS, therefore -it warns against using SSL Compression (for example gzip) or SPDY which -optionally uses compression as well. +The TLS Protocol CRIME Vulnerability affects systems that use data compression +over HTTPS. Your system might be vulnerable to the CRIME vulnerability if you use +SSL Compression (for example, gzip) or SPDY (which optionally uses compression). GitLab supports both gzip and [SPDY][ngx-spdy] and mitigates the CRIME -vulnerability by deactivating gzip when HTTPS is enabled. You can see the -sources of the files in question: +vulnerability by deactivating gzip when HTTPS is enabled. The sources of the +files are here: - [Source installation NGINX file][source-nginx] - [Omnibus installation NGINX file][omnibus-nginx] @@ -49,8 +49,8 @@ SPDY support earlier than version 4 is advertised. ``` From the report above it is important to note that Nessus is only checking if -TLS advertises the SPDY protocol earlier than version 4, it does not perform an -attack nor does it check if compression is enabled. With just this approach, it +TLS advertises the SPDY protocol earlier than version 4. It does not perform an +attack nor does it check if compression is enabled. The Nessus scanner alone cannot tell that SPDY's compression is disabled and not subject to the CRIME vulnerability. @@ -65,3 +65,15 @@ vulnerability. [ngx-spdy]: http://nginx.org/en/docs/http/ngx_http_spdy_module.html [nessus]: https://www.tenable.com/plugins/index.php?view=single&id=62565 [wiki-crime]: https://en.wikipedia.org/wiki/CRIME + + diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 846bcdfe26e..dc654c56d1c 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,13 +1,34 @@ --- type: concepts --- - # Information exclusivity -Git is a distributed version control system (DVCS). -This means that everyone that works with the source code has a local copy of the complete repository. -In GitLab every project member that is not a guest (so reporters, developers and maintainers) can clone the repository to get a local copy. -After obtaining this local copy the user can upload the full repository anywhere, including another project under their control or another server. -The consequence is that you can't build access controls that prevent the intentional sharing of source code by users that have access to the source code. -This is an inherent feature of a DVCS and all git management systems have this limitation. -Obviously you can take steps to prevent unintentional sharing and information destruction, this is why only some people are allowed to invite others and nobody can force push a protected branch. \ No newline at end of file +Git is a distributed version control system (DVCS). This means that everyone +who works with the source code has a local copy of the complete repository. + +In GitLab every project member that is not a guest (reporters, developers, and +maintainers) can clone the repository to create a local copy. After obtaining +a local copy, the user can upload the full repository anywhere, including to +another project that is under their control, or onto another server. + +Therefore, it is impossible to build access controls that prevent the +intentional sharing of source code by users that have access to the source code. + +This is an inherent feature of a DVCS. All git management systems have this +limitation. + +You can take steps to prevent unintentional sharing and information +destruction. This is the reason why only certain people are allowed to invite +others and why no user can force push a protected branch. + + diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 3ad78a5c835..d78293c75c6 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,15 +1,28 @@ --- type: reference, howto --- - # Custom password length limits -If you want to enforce longer user passwords you can create an extra Devise initializer with the steps below. +If you want to enforce longer user passwords you can create an extra Devise +initializer with the steps below. -If you do not use the `devise_password_length.rb` initializer the password length is set to a minimum of 8 characters in `config/initializers/devise.rb`. +If you do not use the `devise_password_length.rb` initializer the password +length is set to a minimum of 8 characters in `config/initializers/devise.rb`. ```bash cd /home/git/gitlab sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb sudo -u git -H editor config/initializers/devise_password_length.rb # inspect and edit the new password length limits ``` + + diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 66081d7e376..4cbddc4ec3a 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -1,24 +1,28 @@ +--- +type: reference, howto +--- # Rack Attack Rack Attack, also known as Rack::Attack, is [a rubygem](https://github.com/kickstarter/rack-attack) that is meant to protect GitLab with the ability to customize throttling and -blocking user IPs. +to block user IP addresses. + You can prevent brute-force passwords attacks, scrapers, or any other offenders -by throttling requests from IP addresses making large volumes of requests. -In case you find throttling is not enough to protect you against abusive clients, -Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering and +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. **Note:** Starting with 11.2, Rack Attack is disabled by default. To continue -using this feature, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). +using Rack Attack, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). 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. -If you installed or upgraded GitLab by following the [official guides](../install/README.md) -this should be disabled by default. If your instance is not exposed to any incoming -connections, it is recommended to leave Rack Attack disabled. +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. For more information on how to use these options check out [rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md). @@ -27,7 +31,7 @@ For more information on how to use these options check out **Omnibus GitLab** -1. Open `/etc/gitlab/gitlab.rb` with you editor +1. Open `/etc/gitlab/gitlab.rb` with your editor 1. Add the following: ```ruby @@ -53,7 +57,7 @@ The following settings can be configured: For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3"]`. - `maxretry`: The maximum amount of times a request can be made in the specified time. -- `findtime`: The maximum amount of time failed requests can count against an IP +- `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 will be blocked (in seconds). diff --git a/doc/security/reset_root_password.md b/doc/security/reset_root_password.md index 6a882ed6fe5..a58d70f0ff2 100644 --- a/doc/security/reset_root_password.md +++ b/doc/security/reset_root_password.md @@ -1,8 +1,11 @@ +--- +type: howto +--- # How to reset your root password -Log into your server with root privileges. Then start a Ruby on Rails console. +To reset your root password, first log into your server with root privileges. -Start the console with this command: +Start a Ruby on Rails console with this command: ```bash gitlab-rails console production @@ -38,3 +41,15 @@ user.save! ``` Exit the console and try to login with your new password. + + diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 6b6a8a06cc9..ae4cc44519e 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -1,3 +1,6 @@ +--- +type: reference, howto +--- # Restrict allowed SSH key technologies and minimum length `ssh-keygen` allows users to create RSA keys with as few as 768 bits, which @@ -25,3 +28,15 @@ An icon will be visible to the user of a restricted key in the SSH keys section ![Restricted SSH key icon](img/ssh_keys_restricted_key_icon.png) Hovering over this icon will tell you why the key is restricted. + + diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 2ece4ed3fc9..ad5daef805a 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -1,3 +1,6 @@ +--- +type: howto +--- # Enforce Two-factor Authentication (2FA) Two-factor Authentication (2FA) provides an additional level of security to your @@ -55,3 +58,15 @@ sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_EN CAUTION: **Caution:** This is a permanent and irreversible action. Users will have to reactivate 2FA from scratch if they want to use it again. + + diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index d5ecef7f605..75cf754e197 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,8 +1,12 @@ +--- +type: howto +--- # How to unlock a locked user -Log into your server with root privileges. Then start a Ruby on Rails console. +To unlock a locked user, first log into your server with root privileges. + +Start a Ruby on Rails console with this command: -Start the console with this command: ```bash gitlab-rails console production @@ -29,3 +33,15 @@ user.unlock_access! ``` Exit the console, the user should now be able to log in again. + + diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 8c07e11dcb1..f0af0a7ac6a 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,7 +1,23 @@ +--- +type: howto +--- # User email confirmation at sign-up -GitLab admin can enable email confirmation on sign-up, if you want to confirm all -user emails before they are able to sign-in. +GitLab can be configured to require confirmation of a user's email address when +the user signs up. When this setting is enabled, the user is unable to sign in until +they confirm their email address. In the Admin area under **Settings** (`/admin/application_settings`), go to section -**Sign-up Restrictions** and look for **Send confirmation email on sign-up** option. +**Sign-up Restrictions** and look for the **Send confirmation email on sign-up** option. + + diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 98493d33b00..f34528a6e05 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -1,11 +1,30 @@ +--- +type: reference +--- # User File Uploads -Images attached to issues, merge requests or comments do not require authentication -to be viewed if someone knows the direct URL. This direct URL contains a random -32-character ID that prevents unauthorized people from guessing the URL to an -image containing sensitive information. We don't enable authentication because -these images need to be visible in the body of notification emails, which are -often read from email clients that are not authenticated with GitLab, like -Outlook, Apple Mail, or the Mail app on your mobile device. +Images that are attached to issues, merge requests, or comments +do not require authentication to be viewed if they are accessed directly by URL. +This direct URL contains a random 32-character ID that prevents unauthorized +people from guessing the URL for an image, thus there is some protection if an +image contains sensitive information. -Note that non-image attachments do require authentication to be viewed. +Authentication is not enabled because images must be visible in the body of +notification emails, which are often read from email clients that are not +authenticated with GitLab, such as Outlook, Apple Mail, or the Mail app on your +mobile device. + +>**Note:** +Non-image attachments do require authentication to be viewed. + + diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 8c26bbac6a7..b0a1c801829 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,20 +1,56 @@ +--- +type: concepts, reference, howto +--- # Webhooks and insecure internal web services -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. +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. -With [Webhooks](../user/project/integrations/webhooks.md), you and your project maintainers and owners can set up URLs to be triggered when specific things happen to 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. +With [Webhooks](../user/project/integrations/webhooks.md), you and your project +maintainers and owners can set up URLs to be triggered when specific things +happen to 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. -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. +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. -Because Webhook requests are made by the GitLab server itself, these have complete access to everything running on the server (`http://localhost:123`) or within the server's local network (`http://192.168.1.12:345`), even if these services are otherwise protected and inaccessible from the outside world. +Because Webhook requests are made by the GitLab server itself, these have +complete access to everything running on the server (`http://localhost:123`) or +within the server's local network (`http://192.168.1.12:345`), even if these +services are otherwise protected and inaccessible from the outside world. -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`. +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`. -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 will be 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 won't be allowed. +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 will be 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 won't be allowed. -This behavior can be overridden by enabling the option *"Allow requests to the local network from hooks and services"* in the *"Outbound requests"* section inside the Admin area under **Settings** (`/admin/application_settings/network`): +This behavior can be overridden by enabling the option *"Allow requests to the +local network from hooks and services"* in the *"Outbound requests"* section +inside the Admin area under **Settings** +(`/admin/application_settings/network`): ![Outbound requests admin settings](img/outbound_requests_section.png) >**Note:** -*System hooks* are exempt from this protection because they are set up by admins. +*System hooks* are exempt from this protection because they are set up by +admins. + + -- cgit v1.2.1 From 7d4cf82ee3d1eb1ca29ef186eefc689fbe1b837c Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Fri, 7 Jun 2019 15:32:46 +0000 Subject: Updated security docs Changes include: - Added front matter - Added Troubleshooting header - Shorted long lines - Corrected typos and improved clarity throughout --- doc/security/user_file_uploads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index f34528a6e05..00a2607b607 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -12,7 +12,7 @@ image contains sensitive information. Authentication is not enabled because images must be visible in the body of notification emails, which are often read from email clients that are not authenticated with GitLab, such as Outlook, Apple Mail, or the Mail app on your -mobile device. +mobile device. >**Note:** Non-image attachments do require authentication to be viewed. -- cgit v1.2.1 From 6fb7ced5796e37720f1be0fb2e125ee824fbe071 Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Fri, 7 Jun 2019 19:27:27 +0000 Subject: Apply suggestion to doc/security/rack_attack.md --- doc/security/rack_attack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 4cbddc4ec3a..fa4b0d1fb09 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -3,7 +3,7 @@ type: reference, howto --- # Rack Attack -Rack Attack, also known as Rack::Attack, is [a rubygem](https://github.com/kickstarter/rack-attack) +[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. -- cgit v1.2.1 From be1d1c704311019ee415991a9eb785a056ff8931 Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Fri, 7 Jun 2019 19:27:48 +0000 Subject: Apply suggestion to doc/security/webhooks.md --- doc/security/webhooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index b0a1c801829..d4fa088cb15 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -7,8 +7,8 @@ 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. With [Webhooks](../user/project/integrations/webhooks.md), you and your project -maintainers and owners can set up URLs to be triggered when specific things -happen to projects. Normally, these requests are sent to external web services +maintainers and owners can set up URLs to be triggered when specific changes +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. -- cgit v1.2.1 From fc87880c96df615957aebe850f586bad9fba0044 Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Fri, 7 Jun 2019 20:17:01 +0000 Subject: Added links to pertinent GitLab docs Clarified who can push to a protected branch --- doc/security/information_exclusivity.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index dc654c56d1c..2a0fb96cb8c 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -18,8 +18,9 @@ This is an inherent feature of a DVCS. All git management systems have this limitation. You can take steps to prevent unintentional sharing and information -destruction. This is the reason why only certain people are allowed to invite -others and why no user can force push a protected branch. +destruction. This limitation is the reason why only certain people are allowed +to [add users to a project](../user/project/members/) and why only a GitLab +admin can [force push a protected branch](../project/protected_branches.html).