Investigation tools for security incidents

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.

Note

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

Using the activity view to see changes to a repository

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 the audit log for your enterprise.
- 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 the audit log for your enterprise.
For enterprises on GitHub Enterprise Cloud, we recommend displaying IP addresses in the audit logs; this requires prior configuration. See Displaying IP addresses in the audit log for your enterprise.
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).

GitHub code search

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

Searching code

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.
Review what credentials a workflow job had access to, including the default GITHUB_TOKEN, any personal access tokens, GitHub App tokens, other credentials stored as secrets, and access tokens obtained during the workflow run.
Retrieve logs programmatically via the REST API for archival, forensic, or automation purposes.

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. The maximum retention is 400 days. Retention can be configured at the enterprise, organization, or repository level. If a workflow run occurred outside of your configured retention window, the logs may no longer be available. For more information, see Managing GitHub Actions settings for a repository, Configuring the retention period for GitHub Actions artifacts and logs in your organization, or Enforcing policies for GitHub Actions in your enterprise.
Workflow runs (including their logs) can also be deleted via the REST API. To check whether a run was deleted, query for workflows.delete_workflow_run events in the audit log.
The default GITHUB_TOKEN issued to each job is scoped to that job and expires when the job finishes or after its effective maximum lifetime (up to 24 hours on self-hosted runners). Even if a step captured the token, it cannot be reused after the job finishes. For more information, see GITHUB_TOKEN.
Other credentials referenced in workflows, such as personal access tokens, GitHub App installation tokens, or third-party API keys stored as secrets, have their own lifecycle and do not expire when the job ends. If a workflow step exposed one of these credentials, the token remains valid until it is revoked or expires according to its own policy. Any credential that may have been exposed should be treated as compromised and rotated or replaced immediately. Review the workflow file and the repository, organization, and environment secrets to determine which credentials were accessible. For more information, see Using secrets in GitHub Actions.
You can download logs for an entire workflow run or for a specific job programmatically using the REST API. Both endpoints return a redirect URL that is valid for one minute. For more information, see REST API endpoints for workflow runs and REST API endpoints for workflow jobs.
Workflow run logs only capture standard output from workflow steps. Activity that does not write to standard output, such as network calls, file system modifications, or background processes, does not appear in the logs.
For GitHub-hosted runners, the runner environment is ephemeral and destroyed after the job completes. GitHub does not retain any data beyond the workflow run logs for these runners. For self-hosted runners, additional host-level or network telemetry may be available from your own infrastructure.
For a more comprehensive investigation, correlate workflow run logs with audit log events. Events such as git.clone, git.fetch, git.push, protected_branch.create, and protected_branch.policy_override can provide additional context. Because Git events in GitHub-hosted audit logs are currently retained for only 7 days for enterprises, setting up streamed enterprise audit logs ahead of time is important for this type of investigation. For more information, see Preparing for a security incident.

In this article