Various edits to security documentation

Edits to conform with CE epic 1280 SSOT standards, other improvements

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
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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
 ```
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->
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.
+
+<!-- ## 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. -->