Document authentication metadata for Git events in organization and enterprise audit logs (#43004)

Co-authored-by: Jeff Saracco <jeffsaracco@github.com>
Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>

content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md

@@ -1,60 +1,43 @@
 ---
 title: Identifying audit log events performed by an access token
 shortTitle: Identify events by token
-intro: 'You can identify the actions performed by a specific {% data variables.product.pat_generic %} or OAuth token in your enterprise.'
+intro: 'You can identify the actions performed by a specific token in your enterprise.'
 versions:
   feature: token-audit-log
+topics:
+  - Organizations
+  - Authentication
+  - OAuth apps
+  - GitHub Apps
 ---
 
-## About token data in the audit log
+## About token data in the audit log for an enterprise
 
-In your enterprise's audit log, for any actions that were performed using a {% data variables.product.pat_generic %} or {% data variables.product.prodname_oauth_app %} for authentication, the event data will show the authentication method used and the SHA-256 hash of the token.
+Your enterprise's audit log contains an event for each action that a user or integration performs. If the action occurred outside of {% data variables.product.prodname_dotcom %}'s web UI, the event's data will show details about how the user or integration authenticated.
 
-If you learn that a token was compromised, you can understand the actions taken by the compromised token by searching your enterprise's audit log for all events associated with that token.
+{% data reusables.audit_log.understand-actions-taken-with-token %}
 
-Hashed token values are not included when you export the audit log.
+{% data reusables.audit_log.authentication-methods-with-metadata %}
 
-## Searching for events associated with a token
+## Token data in audit log events
 
-When searching for events associated with a specific token, you can use the UI or REST API. In either case, you will need to know the SHA-256 hash of the token first.
+{% data reusables.audit_log.data-describing-token-use %}
+
+## Identifying events associated with a token
+
+{% data reusables.audit_log.searching-for-associated-events %}
 
 ### Generating a SHA-256 hash value for a token
 
-If you only have a raw token value, you'll need to generate a SHA-256 hash before you can search for the token.
+{% data reusables.audit_log.generating-hash-for-a-token %}
-
-For MacOS and Linux, you can use `echo -n TOKEN | openssl dgst -sha256 -binary | base64`, replacing TOKEN with the token value.
-
-For Powershell, you can use the following script to return a SHA-256 hash for a given string.
-
-```shell copy
-Param (
-    [Parameter(Mandatory=$true)]
-    [string]
-    $ClearString
-)
-
-$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
-$hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ClearString))
-
-$hashString = [System.BitConverter]::ToString($hash)
-$hashString.Replace('-', '')
-```
 
 ### Searching on {% data variables.product.prodname_dotcom %}
 
-While searching the audit log on {% data variables.product.prodname_dotcom %}, include `hashed_token:"VALUE"` in your search query, replacing `VALUE` with the SHA-256 hash of the token.
+{% data reusables.audit_log.searching-for-a-token-on-githubcom %}
-
-{% note %}
-
-**Note:** Make sure to wrap the hashed token value in quotation marks.
-
-{% endnote %}
 
 ### Searching with the REST API
 
-Before you can search for a token using the REST API, after you generate a SHA-256 hash, you also need to URI-escape the hash. Most major programming languages provide a utility for URI escaping. For example, [encodeURIComponent()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) encodes a string for JavaScript.
+{% data reusables.audit_log.searching-for-a-token-with-rest-api %}
-
-Then, include `hashed_token:"VALUE"` in your search phrase, replacing VALUE with the URI-escaped hash.
 
 For example, if the name of the enterprise account is `octo-corp`, the following curl command would search @octo-corp's audit log for all events that are associated with the token whose URI-encoded SHA-256 hash is `EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8`.
 
@@ -62,6 +45,19 @@ For example, if the name of the enterprise account is `octo-corp`, the following
 curl --header "Accept: application/vnd.github+json" --header "Authorization: Bearer YOUR-TOKEN" {% data reusables.rest-api.version-header %} 'https://api.github.com/enterprises/octo-corp/audit-log?phrase=hashed_token:"EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8"'
 ```
 
+{% ifversion token-audit-log-more-metadata %}
+
+### Identifying Git events
+
+{% data reusables.audit_log.you-can-identify-git-events %} For more information, see "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise#exporting-git-events-data)."
+
+{% data reusables.audit_log.authentication-metadata-git-events-release-phase %}
+
+{% endif %}
+
 ## Further reading
 
 - "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise)"
+{%- ifversion ghec %}
+- "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token)"
+{%- endif %}

content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md

@@ -0,0 +1,61 @@
+---
+title: Identifying audit log events performed by an access token
+shortTitle: Identify events by token
+intro: 'You can identify the actions performed by a specific token in your organization.'
+versions:
+  ghec: '*'
+topics:
+  - Organizations
+  - Authentication
+  - OAuth apps
+  - GitHub Apps
+---
+
+## About token data in the audit log for an organization
+
+Your organization's audit log contains an event for each action that a user or integration performs. If the action occurred outside of {% data variables.product.prodname_dotcom %}'s web UI, the event's data will show details about how the user or integration authenticated.
+
+{% data reusables.audit_log.understand-actions-taken-with-token %}
+
+{% data reusables.audit_log.authentication-methods-with-metadata %}
+
+## Token data in audit log events
+
+{% data reusables.audit_log.data-describing-token-use %}
+
+## Identifying events associated with a token
+
+{% data reusables.audit_log.searching-for-associated-events %}
+
+### Generating a SHA-256 hash value for a token
+
+{% data reusables.audit_log.generating-hash-for-a-token %}
+
+### Searching on {% data variables.product.prodname_dotcom %}
+
+{% data reusables.audit_log.searching-for-a-token-on-githubcom %}
+
+### Searching with the REST API
+
+{% data reusables.audit_log.searching-for-a-token-with-rest-api %}
+
+For example, if the name of the organization account is `octo-org`, the following curl command would search @octo-org's audit log for all events that are associated with the token whose URI-encoded SHA-256 hash is `EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8`.
+
+```shell
+curl --header "Accept: application/vnd.github+json" --header "Authorization: Bearer YOUR-TOKEN" {% data reusables.rest-api.version-header %} 'https://api.github.com/orgs/octo-org/audit-log?phrase=hashed_token:"EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8"'
+```
+
+{% ifversion token-audit-log-more-metadata %}
+
+### Identifying Git events
+
+{% data reusables.audit_log.you-can-identify-git-events %} For more information, see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#exporting-the-audit-log)."
+
+{% data reusables.audit_log.authentication-metadata-git-events-release-phase %}
+
+{% endif %}
+
+## Further reading
+
+- "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise)"
+- "[AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token)"

content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md

@@ -15,6 +15,7 @@ children:
   - /managing-allowed-ip-addresses-for-your-organization
   - /restricting-email-notifications-for-your-organization
   - /reviewing-the-audit-log-for-your-organization
+  - /identifying-audit-log-events-performed-by-an-access-token
   - /displaying-ip-addresses-in-the-audit-log-for-your-organization
   - /audit-log-events-for-your-organization
   - /accessing-compliance-reports-for-your-organization

content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md

@@ -130,6 +130,14 @@ Using the qualifier `country`, you can filter events in the audit log based on t
 - `country:Mexico` finds all events that occurred in Mexico.
 - `country:"United States"` all finds events that occurred in the United States.
 
+{% ifversion ghec %}
+
+### Search based on access token
+
+You can identify all events that were performed by a specific access token. For more information, see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token)."
+
+{% endif %}
+
 {% ifversion fpt or ghec %}
 
 ## Exporting the audit log

data/features/token-audit-log-more-metadata.yml

@@ -0,0 +1,4 @@
+# Reference: #11368
+# Additional authentication metadata in enterprise and organization audit logs
+versions:
+  ghec: '*'

data/reusables/audit_log/audit-log-search-list-info-about-action.md

@@ -9,6 +9,12 @@ Each audit log entry shows applicable information about an event, such as:
 - The action that was performed
 - Which country the action took place in
 - The date and time the action occurred
+{%- ifversion ghec %}
+- The SAML SSO identity of the user (actor) who performed the action (public beta)
+{%- endif %}
+{%- ifversion token-audit-log %}
+- For actions outside of the web UI, how the user (actor) authenticated
+{%- endif %}
 {%- ifversion enterprise-audit-log-ip-addresses %}
 - Optionally, the source IP address for the user (actor) who performed the action
 {%- endif %}

data/reusables/audit_log/authentication-metadata-git-events-release-phase.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note**: Display of token data for Git events in the audit log is in public beta and subject to change.
+
+{% endnote %}

data/reusables/audit_log/authentication-methods-with-metadata.md

@@ -0,0 +1,15 @@
+Token data appears in the audit log for the following authentication methods.
+
+- {% data variables.product.pat_generic_caps %}
+- OAuth token
+- {% data variables.product.prodname_github_apps %} (authentication as an app installation or on behalf of a user)
+{%- ifversion token-audit-log-more-metadata %}
+- Deploy key
+- SSH key
+
+{% note %}
+
+**Note**: Display of token data for SSH keys and deploy keys in the audit log is in public beta and subject to change.
+
+{%- endnote %}
+{% endif %}

data/reusables/audit_log/data-describing-token-use.md

@@ -0,0 +1,7 @@
+The following data about token use appears in the audit log to help you understand how the user or integration authenticated.
+
+| Information | Description |
+| :- | :- |
+| `hashed_token` | SHA-256 hash of the token used for authentication. |
+| `programmatic_access_type` | Type of authentication used. |
+| `token_scopes` | If applicable, the scopes for the token. |

data/reusables/audit_log/generating-hash-for-a-token.md

@@ -0,0 +1,19 @@
+If you only have a raw token value, you'll need to generate a SHA-256 hash before you can search for the token.
+
+For MacOS and Linux, you can use `echo -n TOKEN | openssl dgst -sha256 -binary | base64`, replacing TOKEN with the token value.
+
+For Powershell, you can use the following script to return a SHA-256 hash for a given string.
+
+```shell copy
+Param (
+    [Parameter(Mandatory=$true)]
+    [string]
+    $ClearString
+)
+
+$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
+$hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ClearString))
+
+$hashString = [System.BitConverter]::ToString($hash)
+$hashString.Replace('-', '')
+```

data/reusables/audit_log/searching-for-a-token-on-githubcom.md

@@ -0,0 +1,13 @@
+While searching the audit log on {% data variables.product.prodname_dotcom %}, include `hashed_token:"VALUE"` in your search query, replacing `VALUE` with the SHA-256 hash of the token.
+
+{% note %}
+
+**Note:** Make sure to wrap the hashed token value in quotation marks.
+
+{% endnote %}
+
+{% ifversion token-audit-log-more-metadata %}
+
+Searches using {% data variables.product.prodname_dotcom %} do not return Git events.
+
+{% endif %}

data/reusables/audit_log/searching-for-a-token-with-rest-api.md

@@ -0,0 +1,9 @@
+Before you can search for a token using the REST API, after you generate a SHA-256 hash, you also need to URI-escape the hash. Most major programming languages provide a utility for URI escaping. For example, [encodeURIComponent()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) encodes a string for JavaScript.
+
+Then, include `hashed_token:"VALUE"` in your search phrase, replacing VALUE with the URI-escaped hash.
+
+{% ifversion token-audit-log-more-metadata %}
+
+Searches using the REST API do not return Git events.
+
+{% endif %}

data/reusables/audit_log/searching-for-associated-events.md

@@ -0,0 +1,8 @@
+To identify events associated with a specific token, you can use the UI or REST API. {% ifversion token-audit-log-more-metadata %}To identify Git events, you'll need to export the events from the audit log.{% endif %} To identify any events, you will need to know the SHA-256 hash of the token first.
+
+- [Generating a SHA-256 hash value for a token](#generating-a-sha-256-hash-value-for-a-token)
+- [Searching on {% data variables.product.prodname_dotcom %}](#searching-on-github)
+- [Searching with the REST API](#searching-with-the-rest-api)
+{%- ifversion token-audit-log-more-metadata %}
+- [Identifying Git events](#identifying-git-events)
+{%- endif %}

data/reusables/audit_log/understand-actions-taken-with-token.md

@@ -0,0 +1 @@
+If you learn that a token was compromised, you can understand the actions taken by the compromised token by searching the audit log for all events associated with that token.

data/reusables/audit_log/you-can-identify-git-events.md

@@ -0,0 +1 @@
+You can identify Git events authenticated with a specific token. When you export Git event data from the audit log, fields with details about authentication appear in the output.