From 3644ea65562fcddc4e8edf37e4a28051f1bf0e0f Mon Sep 17 00:00:00 2001 From: Jo Date: Thu, 4 May 2023 10:36:51 +0200 Subject: [PATCH] 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 --------- Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Co-authored-by: Victor Cinaglia --- conf/defaults.ini | 20 ++++- conf/sample.ini | 16 ++++ .../configure-security/secret-scan.md | 83 +++++++++++++++++++ 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 docs/sources/setup-grafana/configure-security/secret-scan.md diff --git a/conf/defaults.ini b/conf/defaults.ini index 0176519d9e1..1066299459e 100644 --- a/conf/defaults.ini +++ b/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 = diff --git a/conf/sample.ini b/conf/sample.ini index 29bf51e332b..91d4e908be5 100644 --- a/conf/sample.ini +++ b/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. diff --git a/docs/sources/setup-grafana/configure-security/secret-scan.md b/docs/sources/setup-grafana/configure-security/secret-scan.md new file mode 100644 index 00000000000..0338da5de69 --- /dev/null +++ b/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": , + "message": "Token of type grafana_service_account_token with name +sa-the-toucans has been publicly exposed in . +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.