Reconcile changes in doc/security/token_overview.md to fix docs-lint

Some changes in doc/update/versions/gitlab_17_changes.md referred
to fragments that did not exist in `doc/security/token_overview.md`
for some reason.

doc/security/token_overview.md

@@ -92,7 +92,7 @@ Deploy tokens can be managed by project maintainers and owners.
 This is useful, for example, for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don't have to set up a fake user account.
-Project maintainers and owners can add or enable a deploy key for a project repository
+Project maintainers and owners can add or enable a deploy key for a project repository.
 ## Runner authentication tokens
@@ -205,7 +205,7 @@ Prerequisites:
 - You must be an administrator.
-1. On the left sidebar, at the bottom, select **Admin Area**.
+1. On the left sidebar, at the bottom, select **Admin area**.
 1. Select **Settings > General**.
 1. Expand **Visibility and access controls**.
 1. Under **Feed token**, select the **Disable feed token** checkbox, then select **Save changes**.
@@ -366,7 +366,7 @@ To replace the token:
 ## Troubleshooting
-### Identify personal, project and group access tokens expiring on a certain date using the Rails console
+### Identify personal, project, and group access tokens expiring on a certain date
 Access tokens that have no expiration date are valid indefinitely, which is a
 security risk if the access token is divulged.
@@ -384,7 +384,8 @@ If you are not aware of when your tokens expire because the dates have changed,
 you might have unexpected authentication failures when trying to sign into GitLab
 on that date.
-To manage this issue, there exists a [tool that assists with analyzing, extending, or remove token expiration dates](../administration/raketasks/tokens/index.md).
+To manage this issue, you should upgrade to GitLab 17.2 or later, because these versions
+contain a [tool that assists with analyzing, extending, or remove token expiration dates](../administration/raketasks/tokens/index.md).
 If you cannot run the tool, you can also run scripts in self-managed instances to identify
 tokens that either:
@@ -397,14 +398,29 @@ You run these scripts from your terminal window in either:
 - A [Rails console session](../administration/operations/rails_console.md#starting-a-rails-console-session).
 - Using the [Rails Runner](../administration/operations/rails_console.md#using-the-rails-runner).
-Both scripts return results in this format:
+The specific scripts you run differ depending on if you have upgraded to GitLab 16.0
+and later, or not:
+
+- If you have not yet upgraded to GitLab 16.0 or later, [identify tokens that do not have an expiration date](#find-tokens-with-no-expiration-date).
+- If you have upgraded to GitLab 16.0 or later, use scripts to identify any of
+  the following:
+  - [Tokens expiring on a specific date](#find-all-tokens-expiring-on-a-specific-date).
+  - [Tokens expiring in a specific month](#find-tokens-expiring-in-a-given-month).
+  - [Dates when many tokens expire](#identify-dates-when-many-tokens-expire).
+
+After you have identified tokens affected by this issue, you can run a final script
+to [extend the lifetime of specific tokens](#extend-token-lifetime) if needed.
+
+These scripts return results in the following format:
 ```plaintext
 Expired Group Access Token in Group ID 25, Token ID: 8, Name: Example Token, Scopes: ["read_api", "create_runner"], Last used:
 Expired Project Access Token in Project ID 2, Token ID: 9, Name: Test Token, Scopes: ["api", "read_registry", "write_registry"], Last used: 2022-02-11 13:22:14 UTC
 ```
-#### expired_tokens.rb
+For more information on this, see [incident 18003](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/18003).
+
+#### Find all tokens expiring on a specific date
 This script finds tokens that expire on a specific date.
@@ -420,13 +436,17 @@ To use it:
 1. In your terminal window, connect to your instance.
 1. Start a Rails console session with `sudo gitlab-rails console`.
-1. Paste in the entire script. Change the `expires_at_date` to the date one year after your instance was upgraded to GitLab 16.0.
+1. Depending on your needs, copy either the entire [`expired_tokens.rb`](#expired_tokensrb)
+   or [`expired_tokens_date_range.rb`](#expired_tokens_date_rangerb) script below, and paste it into the console.
+   Change the `expires_at_date` to the date one year after your instance was upgraded to GitLab 16.0.
 1. Press <kbd>Enter</kbd>.
 :::TabTitle Rails Runner
 1. In your terminal window, connect to your instance.
-1. Copy this entire script, and save it as a file on your instance:
+1. Depending on your needs, copy either the entire [`expired_tokens.rb`](#expired_tokensrb)
+   or [`expired_tokens_date_range.rb`](#expired_tokens_date_rangerb) script below, and save it
+   as a file on your instance:
    - Name it `expired_tokens.rb`.
    - Change the `expires_at_date` to the date one year after your instance was upgraded to GitLab 16.0.
    - The file must be accessible to `git:git`.
@@ -440,10 +460,13 @@ For more information, see the [Rails Runner troubleshooting section](../administ
 ::EndTabs
+##### `expired_tokens.rb`
+
+This script requires you to know the exact date your GitLab instance
+was upgraded to GitLab 16.0.
+
 ```ruby
-# This script requires you to know the exact date your GitLab instance
-# was upgraded to GitLab 16.0. Change this value to the date one year after
-# your GitLab instance was upgraded.
+# Change this value to the date one year after your GitLab instance was upgraded.
 expires_at_date = "2024-05-22"
@@ -462,7 +485,7 @@ PersonalAccessToken.project_access_token.where(expires_at: expires_at_date).find
 end
 ```
-#### expired_tokens_date_range.rb
+#### Find tokens expiring in a given month
 This script finds tokens that expire in a particular month. You don't need to know
 the exact date your instance was upgraded to GitLab 16.0. To use it:
@@ -472,13 +495,14 @@ the exact date your instance was upgraded to GitLab 16.0. To use it:
 :::TabTitle Rails console session
 1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
-1. Paste in the entire script. If desired, change the `date_range` to a different range.
+1. Paste in the entire [`tokens_with_no_expiry.rb`](#tokens_with_no_expiryrb) script below.
+   If desired, change the `date_range` to a different range.
 1. Press <kbd>Enter</kbd>.
 :::TabTitle Rails Runner
 1. In your terminal window, connect to your instance.
-1. Copy this entire script, and save it as a file on your instance:
+1. Copy this entire [`tokens_with_no_expiry.rb`](#tokens_with_no_expiryrb) script below, and save it as a file on your instance:
    - Name it `expired_tokens_date_range.rb`.
    - If desired, change the `date_range` to a different range.
    - The file must be accessible to `git:git`.
@@ -493,6 +517,8 @@ For more information, see the [Rails Runner troubleshooting section](../administ
 ::EndTabs
+##### `expired_tokens_date_range.rb`
+
 ```ruby
 # This script enables you to search for tokens that expire within a
 # certain date range (like 1.month) from the current date. Use it if
@@ -515,6 +541,116 @@ PersonalAccessToken.project_access_token.where(expires_at: Date.today .. Date.to
 end
 ```
+#### Identify dates when many tokens expire
+
+This script identifies dates when most of tokens expire. You can use it in combination with other scripts on this page to identify and extend large batches of tokens that may be approaching their expiration date, in case your team has not yet set up token rotation.
+
+The script returns results in this format:
+
+```plaintext
+42 Personal Access Tokens will expire at 2024-06-27
+17 Personal Access Tokens will expire at 2024-09-23
+3 Personal Access Tokens will expire at 2024-08-13
+```
+
+To use it:
+
+::Tabs
+
+:::TabTitle Rails console session
+
+1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
+1. Paste in the entire [`dates_when_most_of_tokens_expire.rb`](#dates_when_most_of_tokens_expirerb) script.
+1. Press <kbd>Enter</kbd>.
+
+:::TabTitle Rails Runner
+
+1. In your terminal window, connect to your instance.
+1. Copy this entire [`dates_when_most_of_tokens_expire.rb`](#dates_when_most_of_tokens_expirerb)
+   script, and save it as a file on your instance:
+   - Name it `dates_when_most_of_tokens_expire.rb`.
+   - The file must be accessible to `git:git`.
+1. Run this command, changing `/path/to/dates_when_most_of_tokens_expire.rb`
+   to the _full_ path to your `dates_when_most_of_tokens_expire.rb` file:
+
+   ```shell
+   sudo gitlab-rails runner /path/to/dates_when_most_of_tokens_expire.rb
+   ```
+
+For more information, see the [Rails Runner troubleshooting section](../administration/operations/rails_console.md#troubleshooting).
+
+::EndTabs
+
+##### `dates_when_most_of_tokens_expire.rb`
+
+```ruby
+PersonalAccessToken
+  .select(:expires_at, Arel.sql('count(*)'))
+  .where('expires_at >= NOW()')
+  .group(:expires_at)
+  .order(Arel.sql('count(*) DESC'))
+  .limit(10)
+  .each do |token|
+    puts "#{token.count} Personal Access Tokens will expire at #{token.expires_at}"
+  end
+```
+
+#### Find tokens with no expiration date
+
+This script finds tokens that lack an expiration date: `expires_at` is `NULL`. For users
+who have not yet upgraded to GitLab version 16.0 or later, the token `expires_at`
+value is `NULL`, and can be used to identify tokens to add an expiration date to.
+
+You can use this script in either the [Rails console](../administration/operations/rails_console.md)
+or the [Rails Runner](../administration/operations/rails_console.md#using-the-rails-runner):
+
+::Tabs
+
+:::TabTitle Rails console session
+
+1. In your terminal window, connect to your instance.
+1. Start a Rails console session with `sudo gitlab-rails console`.
+1. Paste in the entire [`tokens_with_no_expiry.rb`](#tokens_with_no_expiryrb) script below.
+1. Press <kbd>Enter</kbd>.
+
+:::TabTitle Rails Runner
+
+1. In your terminal window, connect to your instance.
+1. Copy this entire [`tokens_with_no_expiry.rb`](#tokens_with_no_expiryrb) script below, and save it as a file on your instance:
+   - Name it `tokens_with_no_expiry.rb`.
+   - The file must be accessible to `git:git`.
+1. Run this command, changing the path to the _full_ path to your `tokens_with_no_expiry.rb` file:
+
+   ```shell
+   sudo gitlab-rails runner /path/to/tokens_with_no_expiry.rb
+   ```
+
+For more information, see the [Rails Runner troubleshooting section](../administration/operations/rails_console.md#troubleshooting).
+
+::EndTabs
+
+##### `tokens_with_no_expiry.rb`
+
+This script finds tokens without a value set for `expires_at`.
+
+   ```ruby
+   # This script finds tokens which do not have an expires_at value set.
+
+   # Check for expiring personal access tokens
+   PersonalAccessToken.owner_is_human.where(expires_at: nil).find_each do |token|
+     puts "Expires_at is nil for Personal Access Token ID: #{token.id}, User Email: #{token.user.email}, Name: #{token.name}, Scopes: #{token.scopes}, Last used: #{token.last_used_at}"
+   end
+
+   # Check for expiring project and group access tokens
+   PersonalAccessToken.project_access_token.where(expires_at: nil).find_each do |token|
+     token.user.members.each do |member|
+       type = member.is_a?(GroupMember) ? 'Group' : 'Project'
+
+       puts "Expires_at is nil for #{type} access token in #{type} ID #{member.source_id}, Token ID: #{token.id}, Name: #{token.name}, Scopes: #{token.scopes}, Last used: #{token.last_used_at}"
+     end
+   end
+   ```
+
 ### Extend token lifetime
 Delay the expiration of certain tokens with this script.
@@ -526,7 +662,7 @@ If this date is approaching and there are tokens that have not yet
 been rotated, you can use this script to delay expiration and give
 users more time to rotate their tokens.
-#### extend_expiring_tokens.rb
+#### Extend lifetime for specific tokens
 This script extends the lifetime of all tokens which expire on a specified date, including:
@@ -544,13 +680,14 @@ To use the script:
 :::TabTitle Rails console session
 1. In your terminal window, start a Rails console session with `sudo gitlab-rails console`.
-1. Paste in the entire script. If desired, change the `expiring_date` to a different date.
+1. Paste in the entire [`extend_expiring_tokens.rb`](#extend_expiring_tokensrb) script below.
+   If desired, change the `expiring_date` to a different date.
 1. Press <kbd>Enter</kbd>.
 :::TabTitle Rails Runner
 1. In your terminal window, connect to your instance.
-1. Copy this entire script, and save it as a file on your instance:
+1. Copy this entire [`extend_expiring_tokens.rb`](#extend_expiring_tokensrb) script below, and save it as a file on your instance:
    - Name it `extend_expiring_tokens.rb`.
    - If desired, change the `expiring_date` to a different date.
    - The file must be accessible to `git:git`.
@@ -565,6 +702,8 @@ For more information, see the [Rails Runner troubleshooting section](../administ
 ::EndTabs
+##### `extend_expiring_tokens.rb`
+
 ```ruby
 expiring_date = Date.new(2024, 5, 30)
 new_expires_at = 6.months.from_now

doc/update/versions/gitlab_17_changes.md

@@ -135,7 +135,7 @@ a certificate signed with an RSA key can use RSA-2048 but not RSA-1024. GitLab
 will fail to connect to a service that uses a certificate signed with insufficient
 bits with a `certificate key too weak` error message.
-Check the [GitLab documentation on securing your installation](../../security/index.md).
+Check the [GitLab documentation on securing your installation](../../security/index.md)
 for more details.
 ## 17.1.0