[v10.0.x] ServiceAccounts: Add secret scan service docs (#67807)

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> (cherry picked from commit 3644ea6556) Co-authored-by: Jo <joao.guerreiro@grafana.com>
2023-05-04 17:29:27 +02:00
parent c67e84358c
commit 9e83b6081d
3 changed files with 117 additions and 2 deletions
@@ -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.