Responding to a security incident

Respond strategically to a security incident affecting organizations or repositories in your GitHub enterprise.

The guidance in this article is aimed at enterprise owners, organization owners, security managers and security teams. However, you will need to have the enterprise owner role to perform several of the actions outlined in this article. Some steps may require coordination with organization owners or repository administrators.

Introduction

This guide walks you through how to respond to a security incident, outlining the GitHub surfaces you can use to validate and investigate a threat, and the tools you can use to contain and remediate it.

Prerequisites

Investigating and responding to an incident is self-service. Before an incident occurs, enterprise owners should enable enterprise audit log streaming, API request event streaming, and source IP address disclosure. Without all three features enabled at the enterprise level, responders will have critical visibility gaps when investigating incidents affecting the enterprise or its organizations. Enterprise owners should also set an appropriate retention period for the streamed logs and ensure incident responders can access them. See Preparing for a security incident.

Throughout your response

As you progress through your response, make sure that you:

• Capture available evidence: Take screenshots of suspicious activity, export logs or query results while they are available, and save copies of affected files or code before cleanup. Opening a support ticket does not preserve logs or extend their retention period.
• Keep a record: Document your findings (for example, times, dates, Indicators of Compromise (IoCs), repositories affected) and record each decision you take.
• Communicate: Notify relevant stakeholders (such as security leads and engineering managers, as well as legal and privacy teams if sensitive data is at risk) and keep them updated.

Step 1: Assess the signal and validate quickly

The goal is to quickly determine whether the signal you're seeing is likely to be a real and active threat.

1. Identify

Try to identify the nature of the signal you're seeing. For example, does the signal show indications of:

• Credential compromise (alert for a leaked secret, reports of credentials found on an external site)
• Unauthorized access or account compromise (reports of suspicious logins, unfamiliar commits or changes)
• Data exfiltration (reports of suspicious file changes or additions, unexpected workflow runs, unusual API activity, unknown repository creations, or unexpected repository visibility changes)
• Malicious code injection (reports of suspicious code changes, unexpected workflow runs, new files added)
• Supply chain attack (reports of suspicious package versions, alerts for vulnerable dependencies)

For help identifying these threat signals across your organization or enterprise, consult Common security incident investigation areas.

We suggest you don't spend too much time on deep inspection in the earlier stages of your investigation, since the initial goal is to identify the threat signal in order to validate it and strategize your response.

2. Validate

Check for evidence to validate that the potential threat is real, and whether or not it's currently active.

The following GitHub tools and surfaces can help.

For details on each tool, see Investigation tools for security incidents.

The validation phase can be quick:

• Aim to gather enough evidence to determine whether the signal is likely to be a real and active threat.
• If you can't quickly rule out the signal as a false positive, assume it's real.
• Deep investigation can be performed later.

3. Decide

Based on the evidence gathered, determine three things:

1. Is this a real threat? If you cannot quickly and confidently rule the signal out as a false positive, treat it as real and proceed to containment.
2. Is the threat still active? If the attacker appears to still have access or activity is ongoing, prioritize immediate containment actions first. If the compromise appears historical, you still need to investigate and remediate, but you may have more time to plan your response.
3. What is the potential scope? Consider how far the compromise could reach—a single credential, a repository, an organization, or the entire enterprise. This will help you scale your response appropriately.

If in doubt, treat the threat as real, and scale back your response as evidence allows.

Step 2: Contain the threat

The next step assumes you are dealing with a real and active threat. The goal now is to immediately reduce ongoing risk using what you know so far.

There are several containment actions you can choose to perform to limit the attacker's access and capabilities.

Revoke compromised credentials

For exposed or exploited credentials, the most immediate action you can take is to revoke the affected credentials to prevent further misuse.

• Revoke via the API

  If the token is one of the following types, and the literal value of the token is known, you (or anybody) can revoke it by submitting a request via the REST API. See Revocation.

  • Personal access token (classic)
  • Fine-grained personal access token
  • OAuth app access token
  • GitHub App user access token
  • GitHub App refresh token

• Revocation and containment options

  There are additional options for blocking credential access. For a full list by credential type, see GitHub credential types reference.

• Revoke or delete credentials for a specific user

  If you've identified a specific compromised account, enterprise or organization owners on GitHub Enterprise Cloud can revoke SSO authorizations for that individual user. For enterprises with Enterprise Managed Users, you can also delete credentials entirely. This is less disruptive than bulk actions while still containing the threat. See Revoking authorizations or deleting credentials in your enterprise.

• Revoke or delete credentials of a specific type

  If the incident is limited to one credential type, such as personal access tokens (classic), enterprise or organization owners can revoke SSO authorizations or delete credentials of that type only, across all members, using the GitHub UI. This targets the affected credential type without disrupting other credentials. See Revoking authorizations or deleting credentials in your enterprise.

• Emergency actions (major incident)

  Enterprise and organization owners on GitHub Enterprise Cloud can take bulk emergency actions to lock down access across their enterprise or organization. For enterprises with Enterprise Managed Users, this includes deleting all user tokens and keys. These are high-impact actions that will break automations and should be reserved for major incidents. See Responding to security incidents in your enterprise.

All of these de-authorization and revocation actions, whether initiated by an admin or by the affected user, are recorded in the audit log, and the affected user receives an email notification.

Restrict access

To restrict access to the enterprise, organization or repository, there are several immediate actions you can take.

• Configure IP allowlists

  Block unknown or suspicious IP addresses from accessing the organization or enterprise. See Restricting network traffic to your enterprise with an IP allow list (enterprise admins) and Managing allowed IP addresses for your organization (organization owners).

• Remove compromised or suspicious users

  Remove the user or suspend the account. See Removing a member from your organization (organization owners).

• Change repository visibility to private

  Change the affected repository's visibility to private, and restrict the ability of others to make further changes. For example, if sensitive code was exposed in a public repository belonging to the organization, or if a malicious actor changed the repository's visibility setting from private to public, you can change the visibility of the repository. See Setting repository visibility (repository administrators and organization owners) and Restricting repository visibility changes in your organization (organization owners).

• Emergency actions (major incident)

  Enterprise owners on GitHub Enterprise Cloud can take bulk emergency actions to lock down access across their enterprise. These include locking down SSO to block all non-owner access and revoking all user SSO authorizations across organizations. These are high-impact actions that will break automations and should be reserved for major incidents. See Responding to security incidents in your enterprise.

Disable malicious artifacts and activity

• Stop malicious workflow runs

  If you suspect that a GitHub Actions workflow or runner is being used as part of an active attack, you can take the following actions:

  • Cancel in-progress workflow runs for an affected repository. See Canceling a workflow run.
  • Disable GitHub Actions for an affected repository in an organization, or for a specific organization. See Disabling or limiting GitHub Actions for your organization (organization owners) and Enforcing policies for GitHub Actions in your enterprise (enterprise administrators).
  • Remove self-hosted runners. See Removing self-hosted runners.

• Disable webhooks

  If you suspect that a compromised repository or organization webhook is being used as a live data exfiltration channel, you can disable it. See Disabling webhooks.

• Delete malicious branches

  If you've identified branches that contain malicious code or workflows, delete them immediately to prevent execution. See Managing branches within your repository.

Step 3: Investigate fully

After immediate containment, the goal now is to understand the full scope and impact of the incident, identify all IoCs and persistence mechanisms, and gather the evidence you need to contain and fully remediate the threat.

1. Based on the signals you've seen and the evidence gathered so far, develop a working hypothesis of what has happened and decide what additional evidence you will need to prove or disprove that hypothesis.

2. Consider the different investigation areas outlined in Common security incident investigation areas to help guide your investigation.

   Don't limit your investigation to a single line of inquiry. Many attacks use a combination of techniques, such as malicious package installation combined with credential exploitation, workflow file injections, and data exfiltration. Ensure that you are investigating all potential attack vectors.

3. Document all known IoCs so far, searching for traces across all surfaces of GitHub.

4. Inventory all the affected workflows, repositories, and organizations to capture the scope of the incident systematically.

   • Include the repository name, what was affected (code, secrets, workflows), and the timeline of compromise.
   • Create a list of all affected accounts and credentials. Note which tokens, SSH keys, or other credentials may have been exposed or misused.

5. Validate your working theory against the evidence.

   • Review the evidence you've gathered. Does it support your initial hypothesis?
   • Consider alternative explanations. Could there be a different cause for the activity you've observed?
   • If your hypothesis is disproved, form a new hypothesis based on the evidence and repeat the investigation steps as needed.

6. Circle back to containment if you discover new IoCs or evidence of ongoing activity that requires immediate action.

Once you have high confidence in your understanding of what's happened and the root cause, document your findings and proceed to remediation.

Step 4: Remediate

The goal now is to remove all traces of compromise, fix the root cause, and restore systems to a secure state. Remediation actions will depend on the exploitation you have faced, but some good practices are as follows.

Rotate tokens and secrets

Even if you're not certain a credential was compromised, rotate it if there's any possibility of exposure.

• Generate new tokens and secrets to replace any that were revoked or may have been exposed.
• Rotate secrets stored in GitHub at the repository, environment, and organization levels.
• Update any credentials in external systems that may have been accessed using compromised tokens.
• Consider enabling token expiration policies to encourage regular rotation going forward. See Enforcing policies for personal access tokens in your enterprise.

Audit for persistence mechanisms

You will need to check for persistence mechanisms that the attacker may have established to maintain access even after your initial containment actions.

This includes, but isn't limited to, checking for things like:

• Suspicious or unfamiliar workflow files that may have been added or modified.
• New webhooks pointing to unfamiliar domains.
• New self-hosted runners.
• Modifications to self-hosted runners.
• Newly installed GitHub Apps or OAuth app authorizations.
• New deploy keys added to repositories.
• New binary files or executables.

Audit and reinstall dependencies

Compromised dependencies can serve as an attack vector. Make sure you undertake a full audit of your dependencies and reinstall them from trusted sources.

• Review Dependabot alerts for vulnerable dependencies and, where available, Dependabot malware alerts for malicious packages. For the current list of supported ecosystems, see Dependabot malware alerts.
• To investigate additional malware advisories, search for type:malware in the GitHub Advisory Database and audit your dependency graph for matches.
• Pin dependencies to known-good versions or commit SHAs, and reinstall from your package registry.

Verify remediation

Confirm that your remediation efforts have been successful.

• Review code scanning alerts to confirm that code vulnerabilities have been resolved, and no new vulnerabilities have been introduced.
• Review secret scanning alerts to confirm that no secrets remain exposed in any repositories, and that all alerts have been resolved.
• Continue to review and monitor audit logs and other relevant surfaces in the coming days and weeks post-incident.

Step 5. Document

Thorough documentation is essential for the remaining phases and for future reference.

• Record all IoCs discovered during the investigation.
• Document all remediation steps taken, including timestamps and who performed each action.
• Maintain inventories of affected repositories, workflows, and accounts.
• Document decisions made and the reasoning behind them.
• Note any compliance, legal, or privacy implications. Consider whether this incident constitutes a data breach that requires notification.

Step 6: Reflect and harden

The goal now is to learn from the incident and strengthen your security posture to prevent similar incidents.

1. Write an incident summary. This should include a timeline of events from first indication to resolution, as well as the root cause analysis, decisions and actions taken, and lessons learned.
2. Track any outstanding action items from the security incident as issues, such as remaining remediation tasks and any security improvements that need to be implemented based on lessons learned. Copilot can help create these, and you can assign well-scoped issues to Copilot to work on independently. See Starting GitHub Copilot sessions.
3. If you don't already have one, ensure your company or team has an up-to-date Security Incident Response Plan. This should include defined roles and responsibilities, escalation paths, communication protocols, severity classification criteria, and step-by-step response procedures for common threat types. Copilot can help generate and refine this plan based on your specific needs and resources. For additional guidance, see What is incident response.

Next steps

• If you haven't already, consider hardening your security posture to reduce the risk of future incidents. See Protecting against security threats.