How the attack works
When a GitHub organization or enterprise uses single sign-on, access to its resources depends on the identity provider (IdP). Recovery codes are the way in for the day the IdP is unavailable: an organization owner or enterprise owner enters one at the single sign-on prompt and passes without the IdP. Each code works once, the codes have to be used in consecutive order, and a code grants access for 24 hours. GitHub tells owners not to share or distribute the codes and to keep them in a password manager. Owners can open the codes at any time from the single sign-on settings, where they can download, print or copy them, and they can generate a new set.
An attacker in an owner's session collects the codes for later. They do not replace the owner's GitHub credentials, but they take the IdP out of the path, and with it the IdP's own multi-factor rules, its conditional access and the offboarding that disables a user there. Generating a new set has a second effect: the codes shown in the settings are replaced, so the copies the other owners stored may no longer be the ones GitHub displays.
GitHub records each of these actions for the organization as org.recovery_codes_viewed, org.recovery_codes_downloaded, org.recovery_codes_printed and org.recovery_codes_generated, and for the enterprise under the same names with the prefix business. This page is the step before a code is used. The use itself is covered on the page about single sign-on being disabled or changed.
What an attacker needs
- Control of a signed-in session of an organization owner, or of an enterprise owner for the enterprise's codes.
- To use a code later, the GitHub credentials of an owner account. With Enterprise Managed Users a recovery code can be used only by the setup user.
Impact
A set of single-use codes, each of which lets an owner pass single sign-on without the identity provider for 24 hours. Containment that relies on the IdP, such as disabling the user there or tightening its sign-in policy, no longer stops an attacker who holds a code and an owner's GitHub credentials. A regenerated set can also leave the legitimate owners without working copies when the IdP really is unavailable.
Detection rules
GitHub Single Sign-On Recovery Codes Generated
Detects an organization owner or enterprise owner generating a new set of single sign-on recovery codes. GitHub replaces the codes shown in the settings with the new set, so whoever generated them holds current codes and the copies other owners stored earlier may be outdated. Expected after a suspected exposure or an owner change, and rare otherwise.
title: GitHub Single Sign-On Recovery Codes Generated
id: 513830b3-afa9-4b40-9bcf-9d6bddf4e854
status: experimental
description: >-
Detects an organization owner or enterprise owner generating a new set of
single sign-on recovery codes. GitHub replaces the codes shown in the
settings with the new set, so whoever generated them holds current codes
and the copies other owners stored earlier may be outdated. Expected after
a suspected exposure or an owner change, and rare otherwise.
references:
- https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization
- https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise
- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes
- https://attack.mitre.org/techniques/T1555/
author: Forestall
date: 2026-11-16
tags:
- attack.credential-access
- attack.t1555
logsource:
product: github
service: audit
detection:
selection:
action:
- org.recovery_codes_generated
- business.recovery_codes_generated
condition: selection
falsepositives:
- Owners who rotate the codes on purpose, for example after an owner left or after a code was used. Confirm the reason with the owner and make sure the other owners received the new set.
level: medium
False positives
- Owners who rotate the codes on purpose, for example after an owner left or after a code was used. Confirm the reason with the owner and make sure the other owners received the new set.
GitHub Single Sign-On Recovery Codes Viewed, Downloaded or Printed
Detects an organization owner or enterprise owner viewing, downloading or printing the single sign-on recovery codes. Each code lets an owner pass single sign-on without the identity provider for 24 hours, so the codes are worth collecting for later use. The events are expected when single sign-on is set up and rare afterwards.
title: GitHub Single Sign-On Recovery Codes Viewed, Downloaded or Printed
id: 3b5564eb-ad52-49aa-a08d-20949d18c460
status: experimental
description: >-
Detects an organization owner or enterprise owner viewing, downloading or
printing the single sign-on recovery codes. Each code lets an owner pass
single sign-on without the identity provider for 24 hours, so the codes are
worth collecting for later use. The events are expected when single sign-on
is set up and rare afterwards.
references:
- https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization
- https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise
- https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes
- https://attack.mitre.org/techniques/T1555/
author: Forestall
date: 2026-11-16
tags:
- attack.credential-access
- attack.t1555
logsource:
product: github
service: audit
detection:
selection:
action:
- org.recovery_codes_viewed
- org.recovery_codes_downloaded
- org.recovery_codes_printed
- business.recovery_codes_viewed
- business.recovery_codes_downloaded
- business.recovery_codes_printed
condition: selection
falsepositives:
- Owners saving the codes when single sign-on is configured or changed, after a new set was generated, or during an identity provider outage. Confirm the reason with the owner, and check that no recovery code was used afterwards.
level: medium
False positives
- Owners saving the codes when single sign-on is configured or changed, after a new set was generated, or during an identity provider outage. Confirm the reason with the owner, and check that no recovery code was used afterwards.
Triage
- Identify the owner (actor) and the organization or enterprise, and confirm the action with the owner through a separate channel.
- Check whether single sign-on was set up or changed at that time, or whether the identity provider had an outage. Saving the codes is expected then.
- Review the owner's recent activity in the audit log and the account's security log for sign-ins from new devices or locations.
- Search for
org.recovery_code_used,org.recovery_code_failedand theirbusinessequivalents afterwards, and for changes to the single sign-on settings or to the list of owners. - If the access is not explained, treat the codes as stolen.
Response
Once the attack is confirmed:
- Generate a new set of recovery codes from a session you trust, so that the set the attacker saw is replaced, and store the new set where only the owners who need it can reach it.
- Secure the owner account that opened or generated the codes. Reset its password and second factor, end its sessions and revoke its personal access tokens and SSH keys.
- Search the audit log for recovery codes used or tried since the access. Treat a use nobody can explain as a bypass of single sign-on and review everything that account did in the following 24 hours.
- Review what the owner account changed while the attacker had it, such as new owners, changed single sign-on settings, installed apps and approved tokens, and undo it.
- Tell the other owners that their stored copies are outdated, so that nobody finds out during an identity provider outage.
Mitigation
- Keep the number of organization and enterprise owners small, and require phishing-resistant two-factor authentication for their GitHub accounts.
- Store the recovery codes in a password manager or vault that few people can open, and never in shared documents, chat or tickets.
- Stream the audit log to your SIEM and alert on recovery codes being viewed, downloaded, printed or generated. After the initial setup these events should be rare.
- Generate a new set after any suspected exposure and whenever an owner who had access to the codes leaves.
Frequently asked questions
Is it normal for an owner to view or download the recovery codes?
At certain moments, yes. GitHub tells owners to download and store the codes when single sign-on is configured, and owners save a new copy after generating a new set. Outside those moments the events should be rare, because the codes are meant to sit unused in a password manager. An access that matches no setup, change or identity provider outage deserves a question to the owner.
What can someone do with a recovery code?
An organization owner or enterprise owner can enter it at the single sign-on prompt and pass without the identity provider. Each code works once, the codes have to be used in consecutive order, and a code grants access for 24 hours. The code does not replace the account's own GitHub sign-in. With Enterprise Managed Users, only the setup user can use a recovery code.
Do these rules tell me that a recovery code was used?
No. They cover the codes being viewed, downloaded, printed or generated. A code being used is a different event, `org.recovery_code_used` or `business.recovery_code_used`, and a failed attempt is `org.recovery_code_failed` or `business.recovery_code_failed`. Search for those after any alert from this page.
Does generating new codes end the exposure?
GitHub states that when new recovery codes are generated, the codes displayed on the recovery codes page are updated automatically. Generate a new set from a trusted session after a suspected exposure, store it safely and tell the other owners. Secure the owner account as well, because an attacker who still controls it can simply open the new set.
References
- MITRE ATT&CK T1555: Credentials from Password Stores
- Audit log events for your organization
- Audit log events for your enterprise
- Downloading your organization's SAML single sign-on recovery codes
- Accessing your organization if your identity provider is unavailable
- Downloading your enterprise account's single sign-on recovery codes
- Accessing your enterprise account if your identity provider is unavailable