GitHub Integration

Version 2.29.0 (View all)
Managed integration release status
Subscription level
What's this?
Basic
Developed by
What's this?
Elastic
Ingestion method(s) API, AWS S3, Azure Blob Storage, Azure Event Hub, Google Cloud Storage
Minimum Kibana version(s) 9.3.0
9.2.4
9.1.10
8.19.10
Important - Managed integrations on Elastic Cloud Hosted

You can use this integration as an Elastic Managed integration on Elastic Cloud Hosted deployments running this version or later.

The GitHub integration collects events from the GitHub API and Azure Eventhub. It can also retrieve global advisories (reviewed or unreviewed) from the GitHub Security Advisories database, and collect an inventory of organization members for entity analytics.

Agentless integrations allow you to collect data without having to manage Elastic Agent in your cloud. They make manual agent deployment unnecessary, so you can focus on your data instead of the agent that collects it. For more information, refer to Agentless integrations and the Agentless integrations FAQ. Agentless deployments are only supported in Elastic Serverless and Elastic Cloud environments. This functionality is in beta and is subject to change. Beta features are not subject to the support SLA of official GA features.

To use this integration, the following prerequisites must be met:

For GitHub Enterprise Cloud:

  • You must be an enterprise owner.
  • Your enterprise account must be on a GitHub Enterprise Cloud plan that includes audit log access.

For GitHub Enterprise Server:

  • You need to be a site administrator to access the audit log for the entire instance.
  • The audit log is part of the server deployment. Ensure audit logging is enabled in the server configuration.

For Organizations:

  • You must be an organization owner.
  • You must be using GitHub Enterprise Cloud.
  • The organization must be part of an enterprise plan that includes audit log functionality.

The GitHub audit log records all events related to the GitHub organization/enterprise. See Organization audit log actions and Enterprise audit log actions for more details.

The GitHub integration can collect audit logs from the following sources: GitHub API, Azure Event Hubs, Azure Blob Storage, AWS S3 or AWS SQS and Google Cloud Storage.

When using GitHub API to collect audit log events, below requirements must be met for Personal Access Token (PAT):

  • You must use a Personal Access Token with read:audit_log scope. This applies to both organization and enterprise admins.
  • If you're an enterprise admin, ensure your token also includes admin:enterprise scope to access enterprise-wide logs.

To collect audit log events from Azure Event Hubs, follow the guide to setup audit log streaming.

Authentication (Azure Event Hub): The Event Hub input supports two authentication methods: connection string (default) and client secret (Microsoft Entra ID). For setup steps, required RBAC roles (Azure Event Hubs Data Receiver, Storage Blob Data Contributor), and configuration options, see the Azure Logs integration or Filebeat azure-eventhub input documentation.

To collect audit log events from Azure Blob Storage, follow the guide to setup audit log streaming. To collect audit log events from AWS S3 or AWS SQS, follow the guide to setup audit log streaming. For more details, refer to this documentation. To collect audit log events from Google Cloud Storage, follow the guide to setup audit log streaming.

For Filebeat input documentation, refer to the following pages:

This integration is not compatible with GitHub Enterprise server.

The Code Scanning lets you retrieve all security vulnerabilities and coding errors from a repository setup using GitHub Advanced Security Code Scanning feature. Refer to About code scanning for more details.

To use this integration, GitHub Apps must have the security_events read permission. Or use a personal access token with the security_events scope for private repos or public_repo scope for public repos. Refer to List code scanning alerts.

The GitHub Secret Scanning lets you retrieve secret scanning for advanced security alerts from a repository setup using GitHub Advanced Security Secret Scanning feature. Refer to About Secret scanning for more details.

To use this integration, GitHub Apps must have the secret_scanning_alerts read permission. Or you must be an administrator for the repository or for the organization that owns the repository, and you must use a personal access token with the repo scope or security_events scope. For public repositories, you may instead use the public_repo scope. Refer to List secret scanning alerts

The GitHub Dependabot lets you retrieve known vulnerabilites in dependencies from a repository setup using GitHub Advanced Security Dependabot feature. Check About Dependabot for more details.

To use this integration, you must be an administrator for the repository or for the organization that owns the repository, and you must use a personal access token with the repo scope or security_events scope. For public repositories, you may instead use the public_repo scope. Check Authenticating with GraphQL and Token Issue

The GitHub Issues datastream lets you retrieve github issues, including pull requests, issue assignees, comments, labels, and milestones. Check About Issues for more details. You can retrieve issues for specific repository or for entire organization. Since GitHub API considers pull requests as issues, users can use github.issues.is_pr field to filter for only pull requests.

All issues including closed are retrieved by default. If users want to retrieve only open requests, you need to change State parameter to open.

To use this integration, users must use GitHub Apps or Personal Access Token with read permission to repositories or organization. Refer to GitHub Apps Permissions Required and Personal Access Token Permissions Required for more details.

Note

The Issues API can fetch a maximum of 30,000 issues when querying at the organization level. No limitation exists when querying for the repository level.

Note

Ensure the GitHub Personal Access Token includes following fine-grained permission for the repository:

  • At least Read-only permission on Issues
  • At least Read-only permission on Metadata If misconfigured, the integration could run successfully without any data being processed. Alternatively, you might encounter an error like ⁠GET: server returned a 404 (Not Found).

The GitHub Security Advisories datastream lets you retrieve reviewed and unreviewed global security advisories from the GitHub advisory database. Check Working with security advisories for more details.

To use this integration, you may create a fine-grained personal access token (GitHub App user access tokens, GitHub App installation access tokens, Fine-grained personal access tokens). This fine-grained token does not require any permissions. Authentication is not required when accessing data from public repositories, so you can leave the API key field blank in that case.

The GitHub Members data stream collects a snapshot of all organization members and their security-relevant attributes using the GitHub GraphQL API. Each collection cycle produces one document per member, making this an entity inventory stream suited for identity analytics, entity risk scoring, and SIEM identity graphs.

Data collected per member includes: organization role (MEMBER or ADMIN), two-factor authentication enrollment status (optional, see below), full profile attributes (name, email, company, location, bio), and team memberships including the member's role within each team (MAINTAINER or MEMBER).

The data stream issues two GraphQL queries per collection cycle against POST https://api.github.com/graphql:

  1. organization.membersWithRole — paginated list of all org members with their role and 2FA status.
  2. organization.teams (with nested team.members) — paginated list of all teams and their members, used to populate team membership and entity relationship fields.

Authentication: This data stream requires a Classic Personal Access Token (PAT). Fine-grained PATs do not support the admin:org scope or the membersWithRole GraphQL query reliably and cannot be used.

The required scopes depend on which fields you want to collect:

Scope Required? Data unlocked
read:org Required Member roster (role, member list) and team memberships
read:user Required Profile fields: name, email, company, location, bio, pronouns, avatarUrl, websiteUrl, twitterUsername, createdAt, updatedAt, and boolean flags (isSiteAdmin, isEmployee, isHireable, etc.)
admin:org Optional hasTwoFactorEnabled MFA status. The token holder must also be an organization owner. Without this scope the field is omitted rather than set to false. Enable the Collect MFA Status option in the integration config alongside this scope.

To generate a Classic PAT: navigate to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic), select the scopes above, then paste the generated token into the Personal Access Token field of the integration.

SAML SSO organizations: If the organization enforces SAML single sign-on, the token must be explicitly authorized for the organization after creation. On the token list page, click Configure SSO next to the token, then click Authorize next to the organization name. Without this step the API returns a SAML enforcement error regardless of which scopes are selected.

Refer to Creating a personal access token (classic) and Scopes for OAuth apps for more details.

Note

GitHub App bot accounts (login ending in [bot]) are excluded by default. Enable the Include Bot Accounts option to include them.

Note

The billing_manager organization role is only available via the REST API (GET /orgs/{org}/memberships/{username}) and is not returned by the GraphQL membersWithRole query. Members with this role appear with role MEMBER in this data stream.

Note

For GitHub Enterprise Server, override the API URL setting to point to your GHES instance (e.g. https://github.example.com/api). This data stream appends /graphql to the API URL, and GHES serves GraphQL at <HOSTNAME>/api/graphql — the /api/v3 prefix used by the REST-based data streams does not apply here.

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration. The screenshots below illustrate how the ingested data is displayed.