diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md index a70d2f2eb5..9edae5c978 100644 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md +++ b/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. - -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.generating-hash-for-a-token %} ### 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. - -{% note %} - -**Note:** Make sure to wrap the hashed token value in quotation marks. - -{% endnote %} +{% data reusables.audit_log.searching-for-a-token-on-githubcom %} ### 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. - -Then, include `hashed_token:"VALUE"` in your search phrase, replacing VALUE with the URI-escaped hash. +{% data reusables.audit_log.searching-for-a-token-with-rest-api %} 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 %} diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md new file mode 100644 index 0000000000..6ac39b7d39 --- /dev/null +++ b/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)" diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md index e70881aada..ff0832b8a6 100644 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md +++ b/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 diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md index 5f6e908fea..57fc024f1c 100644 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md +++ b/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 diff --git a/data/features/token-audit-log-more-metadata.yml b/data/features/token-audit-log-more-metadata.yml new file mode 100644 index 0000000000..dbdf858536 --- /dev/null +++ b/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: '*' diff --git a/data/reusables/audit_log/audit-log-search-list-info-about-action.md b/data/reusables/audit_log/audit-log-search-list-info-about-action.md index a6f5176a9d..711ee396a7 100644 --- a/data/reusables/audit_log/audit-log-search-list-info-about-action.md +++ b/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 %} diff --git a/data/reusables/audit_log/authentication-metadata-git-events-release-phase.md b/data/reusables/audit_log/authentication-metadata-git-events-release-phase.md new file mode 100644 index 0000000000..b74de28bbc --- /dev/null +++ b/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 %} diff --git a/data/reusables/audit_log/authentication-methods-with-metadata.md b/data/reusables/audit_log/authentication-methods-with-metadata.md new file mode 100644 index 0000000000..eb1d378160 --- /dev/null +++ b/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 %} diff --git a/data/reusables/audit_log/data-describing-token-use.md b/data/reusables/audit_log/data-describing-token-use.md new file mode 100644 index 0000000000..89ebbb3b67 --- /dev/null +++ b/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. | diff --git a/data/reusables/audit_log/generating-hash-for-a-token.md b/data/reusables/audit_log/generating-hash-for-a-token.md new file mode 100644 index 0000000000..ba2b46aad5 --- /dev/null +++ b/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('-', '') +``` diff --git a/data/reusables/audit_log/searching-for-a-token-on-githubcom.md b/data/reusables/audit_log/searching-for-a-token-on-githubcom.md new file mode 100644 index 0000000000..97d267f864 --- /dev/null +++ b/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 %} diff --git a/data/reusables/audit_log/searching-for-a-token-with-rest-api.md b/data/reusables/audit_log/searching-for-a-token-with-rest-api.md new file mode 100644 index 0000000000..86b7262177 --- /dev/null +++ b/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 %} diff --git a/data/reusables/audit_log/searching-for-associated-events.md b/data/reusables/audit_log/searching-for-associated-events.md new file mode 100644 index 0000000000..52f8e8bcaa --- /dev/null +++ b/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 %} diff --git a/data/reusables/audit_log/understand-actions-taken-with-token.md b/data/reusables/audit_log/understand-actions-taken-with-token.md new file mode 100644 index 0000000000..8b91a14eb9 --- /dev/null +++ b/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. diff --git a/data/reusables/audit_log/you-can-identify-git-events.md b/data/reusables/audit_log/you-can-identify-git-events.md new file mode 100644 index 0000000000..89c4d1b44d --- /dev/null +++ b/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.