Secret scanning webhooks & APIs (#16608)

Co-authored-by: shati-patel <shati-patel@github.com>
Co-authored-by: Grey Baker <greysteil@github.com>
Co-authored-by: Prashanth Kannan <prashkan@github.com>
Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com>
Co-authored-by: Melanie Yarbrough <11952755+myarb@users.noreply.github.com>
Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

Author: 6 people

content/developers/apps/creating-a-github-app-using-url-parameters.md

@@ -73,7 +73,9 @@ Permission | Description
 `plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/rest/reference/users#get-a-user)" endpoint. Can be one of: `none` or `read`.
 [`pull_requests`](/rest/reference/permissions-required-for-github-apps/#permission-on-pull-requests) | Grants access to various pull request endpoints. Can be one of: `none`, `read`, or `write`.
 [`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/rest/reference/repos#hooks). Can be one of: `none`, `read`, or `write`.
-[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) |  Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.
+[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) |  Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
+[`secret_scanning_alerts`](/rest/reference/permissions-required-for-github-apps/#permission-on-secret-scanning-alerts) |  Grants access to the [Secret scanning API](/rest/reference/secret-scanning). Can be one of: `none`, `read`, or `write`.{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
+[`security_events`](/rest/reference/permissions-required-for-github-apps/#permission-on-security-events) |  Grants access to the [Code scanning API](/rest/reference/code-scanning/). Can be one of: `none`, `read`, or `write`.{% endif %}
 [`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/rest/reference/repos#contents). Can be one of: `none`, `read`, or `write`.
 [`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/rest/reference/activity#starring). Can be one of: `none`, `read`, or `write`.
 [`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/rest/reference/repos#statuses). Can be one of: `none`, `read`, or `write`.

content/developers/apps/scopes-for-oauth-apps.md

@@ -45,7 +45,8 @@ Name | Description
  `repo:status`| Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code.
  `repo_deployment`| Grants access to [deployment statuses](/rest/reference/repos#deployments) for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code.
  `public_repo`| Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
- `repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest"%}
+ `repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
+&emsp;`security_events` | Grants: <br/> read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning). <br/> read and write access to security events in the [{% data variables.product.prodname_secret_scanning %} API](/rest/reference/secret-scanning).{% endif %}{% if currentVersion ver_gt "enterprise-server@2.21" and currentVersion ver_lt "enterprise-server@3.1" %}
 &emsp;`security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning).{% endif %}
 **`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in public and private repositories. The `repo` and `public_repo` scopes grants full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks.
 &emsp;`write:repo_hook` | Grants read, write, and ping access to hooks in public or private repositories.

content/developers/webhooks-and-events/webhook-events-and-payloads.md

@@ -145,7 +145,7 @@ Also, the `User-Agent` for the requests will have the prefix `GitHub-Hookshot/`.
 
 {{ webhookPayloadsForCurrentVersion.check_suite.completed }}
 
-{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest" %}
+{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
 ### code_scanning_alert
 
 {% data reusables.webhooks.code_scanning_alert_event_short_desc %}
@@ -1099,6 +1099,31 @@ Key | Type | Description
 
 {% endif %}
 
+{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
+
+### secret_scanning_alert
+
+{% data reusables.webhooks.secret_scanning_alert_event_short_desc %}
+
+#### Availability
+
+- Repository webhooks
+- Organization webhooks
+- {% data variables.product.prodname_github_app %}s with the `secret_scanning_alerts:read` permission
+
+#### Webhook payload object
+
+{% data reusables.webhooks.secret_scanning_alert_event_properties %}
+{% data reusables.webhooks.repo_desc %}
+{% data reusables.webhooks.org_desc %}
+{% data reusables.webhooks.app_desc %}
+`sender` | `object` | If the `action` is `resolved` or `reopened`, the `sender` object will be the user that triggered the event. The `sender` object is empty for all other actions.
+
+#### Webhook payload example
+
+{{ webhookPayloadsForCurrentVersion.secret_scanning_alert.reopened }}
+{% endif %}
+
 ### security_advisory
 
 Activity related to a security advisory. A security advisory provides information about security-related vulnerabilities in software on GitHub. The security advisory dataset also powers the GitHub security alerts, see "[About security alerts for vulnerable dependencies](/articles/about-security-alerts-for-vulnerable-dependencies/)."

content/github/administering-a-repository/about-secret-scanning.md

@@ -80,6 +80,8 @@ When {% data variables.product.prodname_secret_scanning %} detects a secret in a
 
 Repository administrators and organization owners can grant users and team access to {% data variables.product.prodname_secret_scanning %} alerts. For more information, see "[Managing security and analysis settings for your repository](/github/administering-a-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts)."
 
+To monitor results from {% data variables.product.prodname_secret_scanning %} across your private repositories or your organization, you can use the {% data variables.product.prodname_secret_scanning %} API. For more information about API endpoints, see "[{% data variables.product.prodname_secret_scanning_caps %}](/rest/reference/secret-scanning)."
+
 {% data variables.product.product_name %} currently scans private repositories for secrets issued by the following service providers.
 
 - Adafruit

content/rest/reference/index.md

@@ -15,8 +15,6 @@ versions:
 {% link_in_list /apps %}
 {% link_in_list /billing %}
 {% link_in_list /checks %}
-<!-- uncomment code-scanning when it's been added to openAPI -->
-<!-- {% link_in_list /code-scanning %} -->
 {% link_in_list /codes-of-conduct %}
 {% link_in_list /code-scanning %}
 {% link_in_list /emojis %}
@@ -39,6 +37,7 @@ versions:
 {% link_in_list /repos %}
 {% link_in_list /scim %}
 {% link_in_list /search %}
+{% link_in_list /secret-scanning %}
 {% link_in_list /teams %}
 {% link_in_list /users %}
 {% link_in_list /permissions-required-for-github-apps %}

content/rest/reference/permissions-required-for-github-apps.md

@@ -819,10 +819,19 @@ _Teams_
 * [`PUT /orgs/:org/actions/secrets/:secret_name/repositories/:repository_id`](/rest/reference/actions#add-selected-repository-to-an-organization-secret) (:write)
 * [`DELETE /orgs/:org/actions/secrets/:secret_name/repositories/:repository_id`](/rest/reference/actions#remove-selected-repository-from-an-organization-secret) (:write)
 * [`DELETE /orgs/:org/actions/secrets/:secret_name`](/rest/reference/actions#delete-an-organization-secret) (:write)
+{% endif %}
+
+{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
+### Permission on "secret scanning alerts"
+
+- [`GET /repos/:owner/:repo/secret-scanning/alerts`](/rest/reference/secret-scanning#list-secret-scanning-alerts-for-a-repository) (:read)
 
+- [`GET /repos/:owner/:repo/secret-scanning/alerts/:alert_number`](/rest/reference/secret-scanning#get-a-secret-scanning-alert) (:read)
+
+- [`PATCH /repos/:owner/:repo/secret-scanning/alerts/:alert_number`](/rest/reference/secret-scanning#update-a-secret-scanning-alert) (:write)
 {% endif %}
 
-{% if currentVersion == "free-pro-team@latest" %}
+{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
 ### Permission on "security events"
 
 - [`GET /repos/:owner/:repo/code-scanning/alerts`](/rest/reference/code-scanning#list-code-scanning-alerts-for-a-repository) (:read)

content/rest/reference/secret-scanning.md

@@ -0,0 +1,12 @@
+---
+title: Secret scanning
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=3.1'
+---
+
+{% data reusables.secret-scanning.api-beta %}
+
+The {% data variables.product.prodname_secret_scanning %} API lets you retrieve and update secret scanning alerts from a private repository. For more information on secret scanning for private repositories, see "[Securing your repository](/github/administering-a-repository/securing-your-repository)."
+
+{% include rest_operations_at_current_path %}

data/reusables/secret-scanning/api-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** The {% data variables.product.prodname_secret_scanning %} API is currently in beta and subject to change.
+
+{% endnote %}

data/reusables/webhooks/secret_scanning_alert_event_properties.md

@@ -0,0 +1,4 @@
+Key | Type | Description
+----|------|-------------
+`action` |`string` | The action that was performed. This can be either `created`, `resolved`, or `reopened`.
+`alert` |`object` | The secret scanning alert involved in the event.

data/reusables/webhooks/secret_scanning_alert_event_short_desc.md

@@ -0,0 +1 @@
+Activity related to secret scanning alerts in a repository. The type of activity is specified in the action property of the payload object. For more information, see “[About secret scanning](/github/administering-a-repository/about-secret-scanning).”