Most GitHub compromises leave a clear trail in the audit log, but few organisations collect the right events, keep them long enough or alert on them. Stolen personal access tokens, rogue OAuth apps, planted workflows and quietly disabled protections all generate named audit events, many with the hash of the token that did the work. This guide is for detection engineers and SOC teams who already have GitHub Enterprise Cloud or an organisation audit log and need to turn it into detections. It covers which events matter, how token attribution works, how to collect and retain the data, the queries and alert rules worth building, and how to measure coverage. It goes deeper than the GitHub and GitHub Actions Security Guide, which covers hardening rather than detection.
This is an independent guide from NHI Mgmt Group, based on GitHub's public documentation as of November 2026. It is not sponsored or reviewed by GitHub. Product features change, so confirm settings against GitHub's current documentation.
Key takeaways
- The web view is not enough. Git events such as
git.cloneand workflow run events are only available through the REST API, audit log streaming or exports, and the enterprise audit log keeps Git events for just seven days. - Token attribution is the biggest win. Events performed with a personal access token, OAuth token or GitHub App token carry
hashed_token,programmatic_access_typeandtoken_scopes, so you can trace everything a leaked token did. - Stream before you need it. GitHub Enterprise Cloud retains audit events for 180 days and shows only three months by default; streaming to S3, Azure, Google Cloud Storage, Datadog or Splunk is what makes long investigations possible.
- Alert on control changes first. Disabling SAML, removing the 2FA requirement, bypassing push protection, deleting branch protection or pausing the audit stream are low-volume, high-signal events.
- Machine actors need their own baselines. Bots, GitHub Apps and agents act at volume; use
actor_is_bot,actor_is_agentand token fields to separate expected automation from a human using a stolen machine credential.
What the GitHub audit log records
GitHub keeps several related logs. Knowing which one holds an event decides where your detection reads from.
| Log | Scope | Who can read it | Detection use |
|---|---|---|---|
| Enterprise audit log | All organisations in a GitHub Enterprise Cloud account, enterprise settings (business.* events) | Enterprise owners | Primary source: policy changes, SSO, streaming, all org activity |
| Organisation audit log | One organisation: members, teams, repositories, apps, secrets, workflows | Organisation owners | Source for teams without an enterprise account |
| Git events | Clone, fetch and push activity | Enterprise owners via REST API (include=git), streaming or export | Bulk clone and exfiltration detection; not shown in search results |
| User security log | One personal account: sign-ins, 2FA, token creation, SSH keys | The account holder | Investigation of a single user; token creation events such as personal_access_token.create |
| API request events | api.request calls to enterprise resources | Enterprise owners, only when API Request Events is enabled | Reconnaissance and scripted access patterns |
Each event has an action in category.verb form (for example repo.destroy), an actor, a timestamp in UTC epoch milliseconds, and an operation type: create, access, modify, remove, authentication, transfer or restore. Other fields include org, repo, user, user_agent, request_id, actor_is_bot and actor_is_agent. If an agent acted for a user, the user field holds the name of the user the agent acted for.
Token attribution: tracing what a credential did
When an action happens outside the web interface, the event records how the caller authenticated. GitHub documents three fields:
- hashed_token: the SHA-256 hash of the token used. You can search with
hashed_token:"<value>"in the UI or the REST API (URI-encode the value). - programmatic_access_type: the authentication type, for example a personal access token, OAuth token or GitHub App token.
- token_scopes: the scopes held by the token, where applicable.
Token data appears for personal access tokens, OAuth tokens and GitHub Apps acting as an installation or on behalf of a user. Token data for deploy keys and SSH keys is in public preview and may change. If you do not hold the token value, the enterprise credential inventory export provides hashed_token, credential_id and SSH key fingerprints you can match against events. This matters for incident response: when a token turns up in a secret scanning alert or an infostealer log, hash it, query every event with that hash, and you have the blast radius in one search. The GitHub Personal Access Tokens Security Guide covers token types and expiry policies.
High-value events for detection
The full event schema runs to hundreds of actions. The ones below map to attacker behaviour and are low enough in volume to alert on directly.
| Behaviour | Audit actions | Why it matters | ATT&CK |
|---|---|---|---|
| Identity control weakened | business.disable_saml, org.disable_saml, business.disable_two_factor_requirement, org.disable_two_factor_requirement, ip_allow_list.disable, ip_allow_list_entry.create | Removes the controls that stop stolen passwords and tokens being used from anywhere | T1685 |
| Privilege added | business.add_admin, business.invite_admin, org.update_member (member to owner), repo.add_member, team.promote_maintainer | Persistence through a new owner or collaborator | T1098 |
| New machine credential | personal_access_token.request_created, personal_access_token.access_granted, public_key.create (SSH or deploy key), oauth_application.generate_client_secret, org_credential_authorization.grant | A credential that survives a password reset | T1098.001 |
| Third-party access granted | integration_installation.create, integration_installation.repositories_added, integration_installation.version_updated, org.oauth_app_access_approved | Rogue or over-scoped apps hold tokens with org-wide reach | T1528, T1199 |
| Token policy relaxed | personal_access_token.access_restriction_disabled, personal_access_token.expiration_limit_unset, personal_access_token.auto_approve_grant_requests_disabled | Opens the door for long-lived, unreviewed tokens | T1685 |
| Secret protection bypassed | secret_scanning_push_protection.bypass, repository_secret_scanning_push_protection.disable, org_secret_scanning_push_protection_bypass_list.add, business_secret_scanning.disable | A secret reached a repository on purpose, or scanning was switched off | T1552.001, T1685 |
| Branch protection removed | protected_branch.destroy, protected_branch.policy_override, protected_branch.update_allow_force_pushes_enforcement_level, repository_ruleset.destroy | Precedes unreviewed pushes and history rewriting | T1195.002 |
| Workflow and secret tampering | org.create_actions_secret, repo.create_actions_secret, environment.remove_protection_rule, workflows.prepared_workflow_job, org.set_actions_fork_pr_approvals_policy | Planted workflows read every secret a job is given | T1195.002 |
| Code collection and exfiltration | git.clone, repo.download_zip, repo.access (visibility change), repo.transfer_outgoing, org.audit_log_export | Bulk cloning, making private code public, moving repositories out | T1213.003, T1567.001 |
| Destruction | repo.destroy, repo.archived, hook.create, hook.config_changed | Extortion wipes and webhook-based data leakage | T1485 |
| Logging impaired | audit_log_streaming.destroy, audit_log_streaming.update (paused or disabled) | An attacker or careless change blinds the SOC | T1685 |
The workflows.prepared_workflow_job event deserves special attention: GitHub documents that it includes the list of secrets provided to the job. It is only available through the REST API, streaming or exports. Joined with the workflow file path and the actor, it tells you which secrets a planted or modified workflow could read, which is exactly the scoping question you face after a campaign like the GhostAction campaign, where compromised maintainer accounts pushed a workflow that sent 3,325 secrets to an attacker server.
Collection, retention and access
Detection fails most often at collection. GitHub's documented retention, streaming and API settings set the design:
- Retention: on GitHub Enterprise Cloud the audit log covers the last 180 days; Git events are kept for seven days. The web view shows the past three months unless you add a
createdrange. GitHub Enterprise Server keeps audit logs indefinitely unless an owner sets a retention period. - Streaming: enterprise owners can stream audit and Git events for every organisation to Amazon S3 (access keys or OpenID Connect), Azure Blob Storage, Azure Event Hubs, Datadog, Google Cloud Storage or Splunk, and can stream to more than one endpoint. A health check runs every 24 hours and emails owners if a stream is misconfigured; it must be fixed within six days to avoid dropped events. A paused stream buffers seven days of data.
- REST API:
/enterprises/{enterprise}/audit-logand the organisation equivalent, with theread:audit_logscope, cursor pagination,include=gitorinclude=all, and a limit of 1,750 queries per hour per user and IP address. - IP addresses: source IPs are not shown by default. Enterprise owners can enable display for the enterprise, or owners for a single organisation. GitHub does not show IPs for
api.requestevents without repository context, or for actions by bots. Check the legal basis with your privacy team before enabling. - API request events:
api.requestappears only when API Request Events is enabled. It adds volume but shows reconnaissance by tokens that read data without changing anything.
Choosing a collection method
| Method | Best for | Trade-offs |
|---|---|---|
| Audit log streaming | Enterprises with a SIEM or data lake | Enterprise Cloud only; near real time; includes Git events; the stream credential itself must be protected (prefer OIDC to S3 over static keys) |
| REST API polling | Organisations without an enterprise account, or SIEMs with a GitHub connector | Rate limited; the polling token is a powerful credential; gaps if the poller fails |
| Webhooks | Near real-time reaction to repository or organisation events | Not a complete audit record and not a replacement for retention; delivery failures leave gaps |
| Manual export (JSON or CSV) | Small organisations and one-off investigations | No alerting; easy to forget; limited by the 180-day window |
A small organisation with one GitHub organisation can poll the API hourly into a cheap log store and alert on a dozen actions. A large enterprise should stream to two destinations (SIEM for detection, object storage with immutability for retention) and treat a stream change as a security incident until proven otherwise. See the Log Management and Retention Guide for retention decisions.
Detection rules worth building
Start with rules that need no baseline, then add behavioural ones once two to four weeks of data are in place.
- Control tampering (no baseline): any
disable_saml,disable_two_factor_requirement,ip_allow_list.disable,audit_log_streaming.destroyor push protection disable event raises a high-severity alert, routed to the identity team and the SOC. - Push protection bypass: every
secret_scanning_push_protection.bypassopens a ticket for the repository owner to confirm and rotate. Repeated bypasses by one user are a training or insider signal. - New owner or admin:
business.add_adminororg.update_memberto owner outside a change window, or performed with a token rather than the web interface. - Token from a new place: events with a given
hashed_tokenfrom a new country, ASN oruser_agentfamily. Pair with IP display enabled. This is the core detection for a stolen token. - Classic token with broad scopes: events where
token_scopesincludesrepo,admin:orgordelete_repoon a classic token, used to drive migration to fine-grained tokens. - Bulk clone:
git.cloneorrepo.download_zipby one actor or token across more repositories in an hour than its 30-day baseline (for example more than three times the usual maximum). - Workflow file changes with new secrets: a push touching
.github/workflows/followed byworkflows.prepared_workflow_joblisting secrets that workflow never received before. - Visibility and transfer:
repo.accesschanging private or internal to public, and anyrepo.transfer_outgoing. - Mass destruction: more than two
repo.destroyevents by one actor in an hour, a pattern that can follow stolen credentials or a malicious OAuth app grant. - App reach expanded:
integration_installation.version_updated(new permissions accepted) orrepositories_addedfor an app that already has write access.
Write rules against action and token fields, not display names: users and repositories are renamed, while hashes and IDs stay stable. Suppress known automation by GitHub App ID or token hash rather than by actor name, and review the suppression list quarterly.
Where identity fits
Most high-impact GitHub events are performed by non-human credentials: fine-grained and classic personal access tokens used by scripts, GitHub App installation tokens, OAuth tokens held by SaaS tools, deploy keys and the tokens your SIEM uses to read the audit log. Treat each as an identity with an owner, an expected behaviour and an expiry. Build a list of known token hashes and app IDs with their owners, so that an alert on an unknown hash means something. The poller or stream credential is itself a privileged non-human identity: if it is stolen, the attacker can read your whole audit trail. See the CI/CD Pipeline Identity Security Guide and the GitHub Actions OIDC Federation Hardening Guide for replacing static secrets that these detections will otherwise keep finding.
Rolling it out
- Inventory: list enterprises, organisations, owners and current log collection. Confirm whether you have Enterprise Cloud (streaming) or only organisation logs (API).
- Collect: enable streaming or API polling; decide on IP display and API Request Events; store raw events immutably for at least a year, longer if regulation requires.
- Validate: in a test organisation, perform each high-value action (create a fine-grained token, bypass push protection, add an owner, clone a repository) and confirm the event, fields and token hash arrive in the SIEM within your target latency.
- Deploy no-baseline rules: switch on control tampering, bypass and privilege rules in alert mode for two weeks, tune, then route to on-call.
- Build baselines: after 30 days, add bulk clone, new-location token and workflow secret rules, starting in report-only mode.
- Rehearse: run a tabletop that starts from a leaked token hash and time how long it takes to list every action that token took.
- Roll back safely: if a rule floods the queue, move it back to report-only rather than deleting it, and never pause the stream to reduce noise; filter in the SIEM instead.
Measuring coverage
- Collection completeness: percentage of organisations whose events reach the SIEM, checked daily against the list of organisations (target 100%).
- Stream health: hours of stream gap per month, and time to fix a failed health check (well inside GitHub's six-day window).
- Event latency: median minutes from action to SIEM, measured with synthetic test events.
- Token attribution rate: share of programmatic events with a
hashed_tokenthat maps to a known owner. - Bypass rate: push protection bypasses per month, and the share followed by rotation within 24 hours.
- Time to scope: minutes from a leaked token report to a complete list of its actions, measured in exercises.
Framework mapping
| Framework | Reference | How GitHub audit log detection supports it |
|---|---|---|
| NIST CSF 2.0 | PR.PS-04, DE.CM-03, DE.CM-09, DE.AE-02 | Logs generated and available, personnel and software activity monitored, events analysed |
| NIST SP 800-53 Rev. 5 | AU-2, AU-6, AU-11, AU-12, SI-4, AC-2, IA-5 | Event logging, review, retention, generation, monitoring, account and authenticator management |
| CIS Controls v8.1 | Control 8 (8.2, 8.9, 8.10, 8.11) | Collect audit logs, centralise them, retain at least 90 days, review them |
| ISO/IEC 27001:2022 | Annex A 8.15, 8.16 | Logging and monitoring activities |
| MITRE ATT&CK v20 | T1078.004, T1098.001, T1528, T1213.003, T1567.001, T1195.002, T1485, T1685 | Cloud account abuse, extra credentials, token theft, repository collection and exfiltration, supply chain, destruction, impairing tools |
Common failure patterns
- Relying on the web view: Git events and workflow run events never appear there, and Git events disappear after seven days. Teams discover a bulk clone weeks later with no record of it.
- No token inventory: alerts carry a
hashed_tokennobody can map to an owner, so analysts close them. Keep a register of known hashes, app IDs and owners. - Suppressing all bots: excluding
actor_is_botevents removes the noise and also every action taken with a stolen app or bot token. Suppress specific, known identities instead. - Unprotected collection credential: a classic token with
admin:orgscope sits in a SIEM connector config with no expiry. Use the narrowest scope (read:audit_log), OIDC for S3 streaming where possible, and monitor that credential's own hash. - Treating push protection bypass as a developer issue: bypasses are logged for a reason. Without rotation follow-up, the secret stays live in Git history and in every clone made since the push.
- Silent stream failure: health check emails go to an enterprise owner mailbox nobody reads. Route them to the SOC and alert on gaps in the SIEM itself.
Practitioner checklist
- Stream enterprise audit and Git events to the SIEM and to immutable storage, or poll the organisation API hourly if you have no enterprise account.
- Decide on IP address display and API Request Events with your privacy team, and document the decision.
- Alert on SAML, 2FA, IP allow list, push protection and audit stream changes with no baseline required.
- Open a ticket for every push protection bypass and track rotation within 24 hours.
- Maintain a register of token hashes, GitHub App IDs and OAuth apps with owners.
- Build bulk clone and new-location token rules after 30 days of baseline data.
- Use
workflows.prepared_workflow_jobto scope which secrets a changed workflow could read. - Protect the audit log collection credential as a privileged identity and monitor its use.
- Test each detection quarterly with synthetic events in a test organisation.
- Exercise the leaked-token scenario and measure time to scope.
Standards and references
- GitHub Docs: Audit log events for your enterprise
- GitHub Docs: Identifying audit log events performed by an access token
- GitHub Docs: Streaming the audit log for your enterprise
- GitHub Docs: Using the audit log API for your enterprise
- GitHub Docs: Searching the audit log for your enterprise
- NIST: SP 800-53 Rev. 5
- NIST: Cybersecurity Framework 2.0
- MITRE ATT&CK: Steal Application Access Token
Related NHI Mgmt Group resources: GitHub and GitHub Actions Security Guide · GitHub Personal Access Tokens Security Guide · Push Protection Guide · CIS Control 8 Audit Log Management Guide