ServiceAccounts: Add secret scan service docs (#57926)

* add secret scanning docs

* update docs

* fix merge

* add revoke to docs

* add revoke to docs

* typo fix

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* add step by step instructions

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* prettier

* Update docs/sources/setup-grafana/configure-security/secret-scan.md

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* feedback

* Update docs/sources/setup-grafana/configure-security/secret-scan.md

* Update docs/sources/setup-grafana/configure-security/secret-scan.md

* Update docs/sources/setup-grafana/configure-security/secret-scan.md

Co-authored-by: Victor Cinaglia <victor@grafana.com>

---------

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
Co-authored-by: Victor Cinaglia <victor@grafana.com>

conf/defaults.ini

@@ -422,7 +422,7 @@ datasource_limit = 5000
 
 ################################### SQL Data Sources #####################
 [sql_datasources]
-# Default maximum number of open connections maintained in the connection pool 
+# Default maximum number of open connections maintained in the connection pool
 # when connecting to SQL based data sources
 max_open_conns_default = 100
 
@@ -431,7 +431,7 @@ max_open_conns_default = 100
 max_idle_conns_default = 100
 
 # Default maximum connection lifetime used when connecting
-# to SQL based data sources. 
+# to SQL based data sources.
 max_conn_lifetime_default = 14400
 
 #################################### Users ###############################
@@ -484,6 +484,22 @@ user_invite_max_lifetime_duration = 24h
 # Enter a comma-separated list of usernames to hide them in the Grafana UI. These users are shown to Grafana admins and to themselves.
 hidden_users =
 
+[secretscan]
+# Enable secretscan feature
+enabled = false
+
+# Interval to check for token leaks
+interval = 5m
+
+# base URL of the grafana token leak check service
+base_url = https://secret-scanning.grafana.net
+
+# URL to send outgoing webhooks to in case of detection
+oncall_url =
+
+# Whether to revoke the token if a leak is detected or just send a notification
+revoke = true
+
 [service_accounts]
 # When set, Grafana will not allow the creation of tokens with expiry greater than this setting.
 token_expiration_day_limit =

conf/sample.ini

@@ -469,6 +469,22 @@
 # Enter a comma-separated list of users login to hide them in the Grafana UI. These users are shown to Grafana admins and themselves.
 ; hidden_users =
 
+[secretscan]
+# Enable secretscan feature
+;enabled = false
+
+# Interval to check for token leaks
+;interval = 5m
+
+# base URL of the grafana token leak check service
+;base_url = https://secret-scanning.grafana.net
+
+# URL to send outgoing webhooks to in case of detection
+;oncall_url =
+
+# Whether to revoke the token if a leak is detected or just send a notification
+;revoke = true
+
 [service_accounts]
 # Service account maximum expiration date in days.
 # When set, Grafana will not allow the creation of tokens with expiry greater than this setting.

docs/sources/setup-grafana/configure-security/secret-scan.md

@@ -0,0 +1,83 @@
+---
+description: Detect and revoke leaked Grafana service account tokens
+labels:
+  products:
+    - cloud
+    - enterprise
+    - oss
+title: Configure Grafana secret scanning and notifications
+menuTitle: Configure secret scanning
+weight: 1000
+---
+
+# Configure Grafana secret scanning and notifications
+
+With Grafana, you can use the GitHub Secret Scanning service to determine if your [service account tokens]({{< relref "../../administration/service-accounts/" >}}) have been leaked on GitHub.
+
+When GitHub Secret Scanning detects a Grafana secret, its hash is stored in Grafana Labs' secret scanning service.
+
+Grafana instances, whether on-premises or on the cloud, can use this service to verify if a token generated by the instance has been made public. This verification is done by comparing the token's hash with the exposed token's hash.
+
+If the service detects a leaked token, it immediately revokes it, making it useless, and logs the event.
+
+> **Note:** If the `revoke` option is disabled, the service only sends a notification to the configured webhook URL and logs the event. The token is not automatically revoked.
+
+You can also configure the service to send an outgoing webhook notification to a webhook URL.
+
+The notification includes a JSON payload that contains the following data:
+
+```json
+{
+  "alert_uid": "c9ce50a1-d66b-45e4-9b5d-175766cfc026",
+  "link_to_upstream_details": <URL to token leak>,
+  "message": "Token of type grafana_service_account_token with name
+sa-the-toucans has been publicly exposed in <URL to token leak>.
+Grafana has revoked this token",
+  "state": "alerting",
+  "title": "SecretScan Alert: Grafana Token leaked"
+}
+```
+
+> **Note:** Secret scanning is disabled by default. Outgoing connections are made once you enable it.
+
+## Before you begin
+
+- Ensure all your API keys have been migrated to service accounts.
+  For more information about service account migration, refer to [Migrate API keys to Grafana service accounts]({{< relref "../../administration/api-keys/#migrate-api-keys-to-grafana-service-accounts" >}}).
+
+## Configure secret scanning
+
+1. Open the Grafana configuration file.
+
+1. In the `[secretscan]` section, update the following parameters:
+
+```ini
+[secretscan]
+# Enable secretscan feature
+enabled = true
+
+# Whether to revoke the token if a leak is detected or just send a notification
+revoke = true
+```
+
+Save the configuration file and restart Grafana.
+
+## Configure outgoing webhook notifications
+
+1. Create an oncall integration of the type **Webhook** and set up alerts.
+   To learn how to create a Grafana OnCall integration, refer to [Webhook integrations for Grafana OnCall](/docs/oncall/latest/integrations/available-integrations/configure-webhook/).
+
+1. Copy the webhook URL of the new integration.
+
+1. Open the Grafana configuration file.
+
+1. In the `[secretscan]` section, update the following parameters,
+   replacing the URL with the webhook URL you copied in step 2.
+
+```ini
+[secretscan]
+# URL to send a webhook payload in oncall format
+oncall_url = https://example.url/integrations/v1/webhook/3a359nib9eweAd9lAAAETVdOx/
+```
+
+Save the configuration file and restart Grafana.