Investigation tools for security incidents

The core GitHub tools you can use to investigate security incidents, what each tool is best used for, and common considerations that affect what data is available.

Dans cet article

Use this reference to decide which GitHub tools to use during a security investigation, what questions each tool can answer, and what factors may affect the data you can see.

Remarque

The availability of each tool (and the data it provides) varies by GitHub plan, your role and permissions, feature enablement, and pre-incident configuration (for example, audit log streaming and IP address disclosure require prior set up).

Activity view

Use

  • Get an overview of activity in a specific repository, including merges, pushes, force pushes, branch creations and deletions, attributed to specific actors over a defined period.
  • Correlate suspicious code appearances with related pushes or merges.
  • Answer questions about when a change was made, who made it, in which branch, and explore the diff or commit history.

Permissions

Read access to the repository.

Key resources

Notes and limitations

  • Activity view is best used as an initial navigation and correlation surface; it doesn't have the same completeness or query power as raw audit log exports.
  • Some incidents require correlation across repositories or organizations, which may be easier in the audit log.

Audit logs

Use

  • Answer questions about what's changed, when, and by whom across an enterprise or organization.
  • Investigate events that may have enabled compromise, or indicate it, such as changes to membership, roles, permissions, or the generation or use of access tokens, etc.
  • Attribute security-relevant actions to an actor (user or integration) and build an investigation timeline.
  • Filter by actor, action, IP address (if enabled), or token, to identify suspicious activity or trace token usage.
  • Correlate activity across multiple repositories or organizations.

Permissions

  • To view the organization audit log, you need to be an organization owner.
  • To view the enterprise audit log, you need to be an enterprise administrator.
  • To view the security log (personal account), you need to be the account owner.
  • To view audit log data exported to an external Security Information and Event Management (SIEM) system, log management system or other tools and services, you need access to that system.

Key resources

Notes and limitations

  • GitHub provides three audit logs: enterprise, organization, and user security logs.
  • The GitHub audit log UI has limited filtering and search capabilities. For this reason, we recommend that enterprises stream the enterprise audit log to an external SIEM or log management system for more advanced querying.
    • Audit log streaming to an external SIEM or log management system requires prior configuration. See Streaming de journaux d’audit pour votre entreprise.
    • Without audit log streaming, you won't be able to run more complex queries, such as correlating events across organizations or repositories, or pivoting from a specific token to all related events.
    • Git events data are included in the stream.
  • We recommend streaming API request events; this requires prior configuration. See Streaming de journaux d’audit pour votre entreprise.
  • For enterprises on GitHub Enterprise Cloud, we recommend displaying IP addresses in the audit logs; this requires prior configuration. See Affichage des adresses IP dans le journal d’audit de votre entreprise.
  • Different GitHub plans have different data availability and data retention offerings:
    • GitHub Free and GitHub Team plans can't view API activity or Git events at all.
    • Standalone organizations (organizations that are not part of an enterprise) can't stream the audit logs, can't view API request events, and are limited to 7 days for Git event data.
    • For enterprises on GitHub Enterprise Cloud:
      • If your enterprise uses Enterprise Managed Users, then the audit log also includes user security logs (events related to user accounts, such as login activity and token usage).
      • If your enterprise doesn't use Enterprise Managed Users, then the GitHub audit log only includes events related to the enterprise account and the organizations within it.
  • The audit logs don't include page view or repository browsing telemetry.

Dependency graph

Use

  • Check whether a repository depends on a vulnerable or compromised package (or version).
  • Review for new or suspicious dependencies that may have been introduced during an incident.
  • Filter and explore dependencies by ecosystem or relationship (direct or transitive).
  • Export a software bill of materials (SBOM) for auditing purposes, or to preserve evidence.

Permissions

  • Write or maintain access to the repository.

Key resources

Notes and limitations

  • The dependency graph is generated from supported manifest/lock files (and optional build-time submissions), so it can be incomplete or differ from what was actually built and deployed. To get the most accurate view, especially for dependencies resolved during CI/build, you should be supplementing the dependency graph with build-time dependency submission (or other build provenance such as SBOMs).

Use

  • Search for Indicators of Compromise (IoCs) across repositories, such as known malicious workflows or package names.
  • Quickly scope the potential blast radius by checking if suspicious code patterns, such as a leaked secret or malicious code snippet, appear in other repositories across the organization or enterprise.
  • Scope the search by various different qualifiers that may be useful during an incident, for example:
    • Search within a specific repository, organization, or enterprise (using the repo:, org:, enterprise: qualifiers).
    • Search within specific file paths (path:.github/workflows repo:ORG-NAME/REPO-NAME).

Permissions required

  • To search across public repositories, you must be signed into your GitHub account.
  • To search across private repositories, you must have read access to those repositories.

Key resources

Notes and limitations

  • Supports regex search.
  • Searches across the default branch of a repository only. If the suspicious code was introduced in a non-default branch and hasn't been merged, it won't be found by code search.
  • You can use code search to determine if a pattern or IoC is present, but it doesn't provide context such as when the code was added or by whom. You should use code search in conjunction with other tools, such as audit logs, activity view, or checking the blame view, commit history and pull request history of a repository.

Security overview and security alerts

Use

  • See a high-level view of all security alerts (secret scanning, code scanning, and Dependabot alerts) across repositories in an organization or enterprise.
  • Triage what GitHub has already detected and identify which repositories are affected.
  • Track new alerts created during an incident (which can indicate active exploitation or spread).

Permissions required

  • To see data for organizations at the enterprise-level, an enterprise administrator must have the organization owner or security manager role in the relevant organizations.
  • To see data for repositories at the organization-level, the organization owner or security manager role is required.

Key resources

Notes and limitations

  • Alerts for leaked secrets, vulnerable code, vulnerable dependencies and malware are only visible if the relevant features were enabled and configured prior to the incident.

Workflow runs and logs

Use

  • Confirm what executed in CI/CD at a given time (such as the commands executed, or the dependency installed).
  • Investigate suspicious workflow runs, such as those triggered by an unfamiliar user or at an unusual time, to see what actions were performed, which secrets were accessed, and what code was executed.
  • Determine whether a workflow had access to any secrets.

Permissions required

  • Read access to the repository.

Key resources

Notes and limitations

  • GitHub automatically redacts secrets from workflow logs.
  • By default, workflow logs are retained by GitHub for 90 days, but you can configure this retention period to be longer (up to 400 days for private repositories).