GitHub Logs
Panther supports pulling GitHub logs directly and audit log streaming
Panther supports the following methods of ingesting logs from GitHub:
- Panther can ingest GitHub audit logs using GitHub's audit log streaming feature via AWS S3 or Google Cloud Storage.
If you have GitHub Enterprise Cloud, using the audit log streaming method to ingest logs is recommended, as it permits you to collect logs from your entire enterprise with a single integration. The API method can fetch logs for just one GitHub organization.
Your Github Organization needs to be part of a Github Enterprise Cloud deployment. The Github Enterprise Server self-hosted option is not yet supported.
There are two different options to authorize Panther to receive GitHub audit logs:
- Create a new OAuth App in GitHub and provide the app credentials to Panther
- Generate a Personal Access Token in GitHub and provide credentials to Panther
OAuth App
Personal Access Token
The steps below can only be performed if you have organization owner permission in your GitHub organization and a GitHub Enterprise subscription. If you need to configure multiple integrations for different GitHub Organizations using the same credentials, you can either use a Personal Access Token or an OAuth2 App that is created on the user account, instead of the Organization account. If any Organizations have enabled OAuth2 App Access Restrictions, the app must be first approved by an Organization admin.
- 1.Log in to your GitHub Enterprise account.
- 2.On the homepage of your organization's account, click on the Settings tab.
- 3.Scroll to the bottom of the page and click on Developer Settings and then OAuth Apps.
- 4.Click on Register an application. Fill in the form:
- Enter a memorable application name into the Name field e.g.
Panther Integration. - Enter your Panther instance's primary URL into the Homepage URL field e.g.
https://test.runpanther.xyz - Copy the Redirect URL from Panther and paste into the Authorization Callback URL field.
- To do this, you will need to log into Panther and set up GitHub as a log source by following the directions below. Once you've made it to the step where you see a Redirect URL, you can copy it and continue setting up your GitHub app.
- 5.Once all necessary fields are filled in, click Register Application.
- 6.Once the application is registered, you can view the Client ID and generate a new Client Secret. Store them in a secure location – you will need them in the next steps.
The steps below can only be performed if you have organization owner permission in your GitHub organization and a GitHub Enterprise subscription. You can read more on generating a Personal Access Token in GitHub here.
- 1.Log in to your Github Enterprise account.
- 2.Click on your profile then click on the Settings option.
- 3.Scroll to the bottom of the page and click on Developer Settings and then Personal Access Token.
- 4.Click Generate new token and enter a descriptive token name, e.g.,
Panther Integration. - 5.Select the scopes, or permissions, you'd like to grant this token.
- Select the
read:audit_logscope.- If the
read:audit_logscope is not available to you, select theadmin:org>read:orgpermission instead.
- You do not need to enable the
write:orgpermission.
- 6.Click Generate token.
- Copy the token and store it in a secure location – you will need it in the next steps.
- 1.In the lefthand navigation bar of your Panther Console, click Configure > Log Sources.
- 2.Click Create New.
- 3.Search for “GitHub API,” then click its tile.
- 4.On the slide-out panel, click Start Setup.
- 5.On the next screen, enter a descriptive name for the source (for example,
My Github Audit logs) and the name of the Github organization you want to monitor. - 6.Click Setup.
- 7.Authorize Panther to receive logs from GitHub - depending on the option you chose above, follow the steps below:
- Use OAuth2 Authorization Flow: Enter the App Client ID and the Client Secret that you acquired from Github. You can find this information on the details page of the OAuth app in your Github account once you register the application.
- Use a Personal Access Token: Copy the personal access token key and paste it into Personal Access token field.
- 8.Click Setup.
- 9.You will be presented with the option to Grant Access.
- 10.Click Authorize.
- 11.You will be directed to a success screen:
- The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.
There are two steps to configure GitHub audit log streaming with Panther:
- 1.Set up audit log streaming from GitHub to a storage destination.
- 2.Create a new GitHub Audit Log Streaming source in Panther.
- Audit log streaming must be configured in GitHub by your GitHub enterprise owner.
Panther supports ingesting GitHub audit log streaming data from two storage destinations. Choose one of the storage destinations below:
- AWS S3
- Google Cloud GCS
- 1.In the lefthand navigation bar of the Panther Console, click Configure > Log Sources.
- 2.Click Create.
- 3.Search for GitHub. Select the GitHub Audit Log Streaming tile.
- 4.Select either S3 or GCS, depending on the transport method you chose.
- 5.Follow the onboarding process for your chosen destination method:
- 1.After creating your S3 bucket in Panther, navigate to the source's Schema tab, and click Advanced Edit & Test with Raw Events.
- 2.Set an S3 Exclusion Filter with a value of
_check.
Panther supports ingesting GitHub webhook events directly via HTTP.
GitHub webhook event ingestion is in open beta starting with Panther version 1.79, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.
- 1.In the left-hand navigation bar of your Panther Console, click Configure > Log Sources.
- 2.Click Create New.
- 3.Search for “GitHub Webhooks,” then click its tile.
- 4.In the slide-out panel, the Transport Mechanism dropdown in the upper right corner will be pre-populated with the HTTP option.
- Click Start Setup.
- 5.
- During setup, for Logs Stream Type, choose JSON.
- During setup, the Auth method will be preset to HMAC, and the HMAC Header Name will be preset to
X-Hub-Signature-256.- Save the Secret Key Value you enter, as you'll need it in the next step.
See detailed instructions for creating a GitHub webhook in GitHub's Creating webhooks documentation.
- 1.In GitHub, navigate to your organization.
- 2.In the left-hand navigation bar, click Webhooks.
- 3.Click Add Webhook.
- 4.Enter values for the following fields:
- Content Type: Set to to
application/json. - Payload URL: Set to the HTTP Source URL you generated in Panther in Step 1.
- Secret value: Set this as the value you used during HTTP source creation in Step 1.
- 5.Choose which events you want Panther to receive. All event types are supported, but not all of them have security value.
- 6.Click Add Webhook.
All Panther-managed GitHub detections include the
filter_include_event helper function. You can customize this function to include or exclude certain logs based on a field value. This filter may be useful if you're using audit log streaming to ingest GitHub enterprise logs, but you'd like to filter out certain organizations. As an example, see it in use in the GitHub.Action.Failed detection. Required fields in the schema are listed as "required: true" just below the "name" field.
GitHub webhooks emit notifications for any event generated within your GitHub organization or repository. For more information, see GitHub's webhook documentation.
schema: GitHub.Webhook
description: Webhooks events are generated whenever certain events occur on GitHub
referenceURL: https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloads
fields:
- name: action
description: Most webhook payloads contain an action property that contains the specific activity that triggered the event.
type: string
- name: target_type
description: Type of target of the event
type: string
- name: ref
description: The Git reference of the event
type: string
- name: commit_oid
description: The commit SHA of the code scanning alert. When the action is reopened_by_user or closed_by_user, the event was triggered by the sender and this value will be empty.
type: string
- name: branch
description: The name of the branch.
type: string
- name: master_branch
description: The name of the repository's default branch (usually main).
type: string
- name: pusher_type
description: The pusher type for the event. Can be either user or a deploy key.
type: string
- name: ref_type
description: 'The type of Git ref object created in the repository. Can be one of: tag, branch'
type: string
- name: hook_id
description: The id of the modified webhook.
type: string
- name: base_ref
description: The name of the base branch that the head_ref is based on.
type: string
- name: before
description: The SHA of the most recent commit on ref before the push.
type: string
- name: after
description: The SHA of the most recent commit on ref after the push.
type: string
- name: number
description: The pull request number.
type: string
- name: compare
description: URL to examine the changes
type: string
- name: forced
description: Whether this push was a force push of the ref.
type: boolean
- name: created
description: Whether this push created the ref.
type: boolean
- name: deleted
description: Whether this push deleted the ref.
type: boolean
- name: sender
required: true
description: The user that triggered the event. This property is included in every webhook payload.
type: json
- name: repository
description: The repository where the event occurred. Webhook payloads contain the repository property when the event occurs from activity in a repository.
type: json
- name: repository_ruleset
description: A set of rules to apply when specified conditions are met.
type: json
- name: organization
description: Webhook payloads contain the organization object when the webhook is configured for an organization or the event occurs from activity in a repository owned by an organization.
type: json
- name: installation
description: The GitHub App installation. Webhook payloads contain the installation property when the event is configured for and sent to a GitHub App.
type: json
- name: enterprise
description: The GitHub Enterprise the event is related to
type: json
- name: rule
description: The branch protection rule. Includes a name and all the branch protection settings applied to branches that match the name. Binary settings are boolean. Multi-level configurations are one of off, non_admins, or everyone. Actor and build lists are arrays of strings.
type: json
- name: check_run
description: A check performed on the code of a given code change
type: json
- name: check_suite
description: The check suite
type: json
- name: alert
description: The code scanning alert involved in the event.
type: json
- name: comment
description: Commit comment resource
type: json
- name: description
description: Description of the event
type: json
- name: key
description: The key of the event
type: json
- name: deployment
description: Deployment related event details
type: json
- name: workflow
description: Workflow related event details
type: json
- name: workflow_run
description: Workflow run
type: json
- name: workflow_job
description: Workflow job
type: json
- name: environment
description: Environment where event occurred
type: json
- name: event
description: Event details
type: json
- name: deployment_callback_url
description: The URL to review the deployment protection rule.
type: json
- name: pull_requests
description: Pull requests related to the event
type: json
- name: pull_request
description: Pull request details
type: json
- name: review
description: Pull request review details
type: json
- name: thread
description: Pull request review comment thread details
type: json
- name: assignee
description: The user that was assigned or unassigned from a pull request.
type: json
- name: approver
description: The user that approved a deployment.
type: json
- name: deployment_status
description: Deployment status details
type: json
- name: discussion
description: Discussion details
type: json
- name: answer
description: Discussion answer details
type: json
- name: forkee
description: The created repository resource
type: json
- name: pages
description: GitHub pages related to the event
type: json
- name: repositories
description: Repository details
type: json
- name: requester
description: Who requested the event
type: json
- name: repositories_added
description: Repositories added in the event
type: json
- name: repositories_removed
description: Repositories removed in the event
type: json
- name: repositories_selection
description: Describe whether all repositories have been selected or there's a selection involved.
type: string
- name: changes
description: Changes details
type: json
- name: issue
description: Issue details
type: json
- name: label
description: Label details
type: json
- name: team
description: GitHub team details
type: json
- name: hook
description: 'The modified webhook. This will contain different keys based on the type of webhook it is: repository, organization, business, app, or GitHub Marketplace.'
type: json
- name: release
description: Release details
type: json
- name: repository_advisory
description: Repository security advisory
type: json
- name: location
description: Location details
type: json
- name: security_advisory
description: Security advisory details
type: json
- name: inputs
description: Input details
type: json
- name: status
description: Status of the event
type: json
- name: pusher
description: Metaproperties for Git author/committer information.
type: json
- name: head_commit
description: Head commit details
type: json
- name: commits
description: Commit details
type: json
- name: commit
description: Commit details
type: json
- name: sha
description: The SHA of the commit
type: string
- name: state
description: The state of the status. Can be one of pending, success, error, or failure.
type: string
- name: context
description: Context details when the status of a Git commit changes.
type: string
- name: member
description: Member details. Only present when there is activity relating to collaborators.
type: json
- name: membership
description: The membership between the user and the organization. Not present when the action is member_invited.
type: json
- name: blocked_user
description: Details of the blocked user (if any)
type: json
- name: invitation
description: The invitation for the user or email if the action is member_invited.
type: json
- name: user
description: The user that was invited. Only present when the action is member_invited.
type: json
- name: package
description: Information about the GitHub Package.
type: json
- name: build
description: Information about the build of a GitHub Pages site.
type: json
- name: personal_access_token_request
description: Information about the personal access token request.
type: json
- name: zen
description: Random string of GitHub zen.
type: string
- name: project
description: Classic project details
type: json
- name: project_card
description: Classic project card details.
type: json
- name: project_column
description: Classic project column details.
type: json
- name: projects_v2
description: Project details
type: json
- name: projects_v2_item
description: An item belonging to a project
type: json
- name: registry_package
description: Information about the GitHub Registry package.
type: json
- name: client_payload
description: Client payload when creating a repository dispatch event.
type: json
- name: sponsorship
description: Details relating to a sponsorship listing.
type: json
- name: marketplace_purchase
description: Details relating to a GitHub Marketplace purchase.
type: json
- name: previous_marketplace_purchase
description: Details relating to a previous GitHub Marketplace purchase.
type: json
- name: effective_date
description: Effective date of the billing event.
type: string
The audit log allows organization administrators to quickly review actions performed by members of your organization. For more information, see GitHub's documentation on accessing audit logs.
schema: GitHub.Audit
description: The audit log allows organization admins to quickly review the actions performed by members of your organization.
referenceURL: https://docs.github.com/en/organizations/keeping-your-organization-secure/reviewing-the-audit-log-for-your-organization#using-the-rest-api
fields:
- name: _document_id
description: Document id for the audit log events
type: string
- name: workflow_id
description: Workflow id if the event is CI workflow
type: string
- name: workflow_run_id
description: Workflow run id if the event is CI workflow
type: string
- name: action
required: true
description: The action performed
type: string
- name: actor
description: Actor that performed the action
type: string
indicators:
- username
- name: created_at
description: Creation timestamp for audit event
type: timestamp
timeFormats:
- unix_ms
isEventTime: true
- name: '@timestamp'
description: Timestamp for the event
type: timestamp
timeFormats:
- unix_ms
isEventTime: true
- name: completed_at
description: Completion timestamp for audit event
type: string
- name: actor_location
description: Actor location
type: object
fields:
- name: country_code
required: true
description: Country code for the actor's location'
type: string
- name: country_name
description: Country name for the actor's location
type: string
- name: region
description: Region code of where this action originated from
type: string
- name: region_name
description: Region name of where this action originated from
type: string
- name: city
description: Name of the city where this action originated from
type: string
- name: postal_code
description: Postal code where this action originated from
type: string
- name: location
description: Actor's location in longitude/latitude
type: object
fields:
- name: lat
description: Latitude field
type: float
- name: lon
description: Longitude field
type: float
- name: org
description: The Organization where the action was performed
type: json
- name: config
description: Webhook configuration
type: object
fields:
- name: content_type
description: content type for the webhook
type: string
- name: insecure_ssl
description: Boolean value if ssl connection is secure
type: string
- name: url
description: payload URL for webhook
type: string
- name: config_was
description: Previous webhook configuration
type: object
fields:
- name: content_type
description: content type for the webhook
type: string
- name: insecure_ssl
description: Boolean value if ssl connection is secure
type: string
- name: url
description: payload URL for webhook
type: string
- name: hook_id
description: Webhook ID
type: string
- name: name
description: name of the event action category
type: string
- name: active
description: Webhook is active
type: boolean
- name: repo
description: Name, or names of the repositories involved in the action
type: json
- name: visibility
description: Visibility of the repository
type: string
- name: events
description: List of events which will send webhook payload
type: array
element:
type: string
- name: user
description: User added/removed for certain permission
type: string
indicators:
- username
- name: team
description: Team name for team category action
type: string
- name: event
description: Workflow event
type: string
- name: transport_protocol_name
description: Transport protocol name for git audit events
type: string
- name: transport_protocol
description: Transport protocol for git audit events
type: int
- name: repository
description: Repository name for git event
type: string
- name: repository_public
description: If the repository for git audit event is public
type: boolean
- name: business_id
description: ID of the enterprise affected by the action (if applicable)
type: string
- name: number
description: Number field
type: bigint
- name: active_was
description: Webhook was active
type: boolean
- name: actor_id
description: The id of the actor who performed the action
type: string
indicators:
- actor_id
- name: blocked_user
description: The username of the account being blocked
type: string
indicators:
- username
- name: business
description: The name of the business that relates to this action
type: string
- name: content_type
description: Type of content
type: string
- name: data
description: Additional data related to this action
type: json
- name: deploy_key_fingerprint
description: Fingerprint of deploy key
type: string
- name: emoji
description: Emoji that relates to this action
type: string
- name: events_were
description: List of events which were sent
type: array
element:
type: json
- name: explanation
description: An explanation of the action
type: string
- name: fingerprint
description: Fingerprint related to this action
type: string
- name: limited_availability
description: Limited availability
type: boolean
- name: message
description: Message related to this action
type: string
- name: old_user
description: The old user related to this action
type: string
- name: openssh_public_key
description: Public Open SSH key related to this action
type: string
- name: operation_type
description: Type of operation
type: string
- name: org_id
description: The Organization ID where the action was performed
type: json
- name: previous_visibility
description: Visibility of repository prior to this action
type: string
- name: read_only
description: Whether the item related to this action is read only
type: boolean
- name: target_login
description: Target login
type: string
- name: user_id
description: User ID
type: string
indicators:
- actor_id
- name: actor_ip
description: Actor IP (only included if explicitly enabled in your GitHub settings https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise)
type: string
indicators:
- ip
- name: hashed_token
description: Hash of the token used to perform this action (see https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token#searching-on-github)
type: string
- name: external_identity_nameid
description: Displayed when SAML SSO identity was used as a means of authentication
type: string
indicators:
- username
- name: external_identity_username
description: Displayed when SAML SSO identity was used as a means of authentication with Enterprise Managed Users
type: string
indicators:
- username
- name: actor_session
description: Actor's session ID
type: string
- name: branch
description: Branch that relates to this action
type: string
- name: category_type
description: Type of category this action is from
type: string
- name: client_id
description: ID of the client being used in this action
type: string
- name: conclusion
description: Workflow run conclusion
type: string
- name: controller_action
description: Action of the controller
type: string
- name: device_cookie
description: Cookie of the actor's session from this action
type: string
- name: environment_name
description: Environment name of workflow
type: string
- name: fork_source
description: Source repository of this fork
type: string
- name: fork_source_id
description: Source repository ID of this fork
type: string
- name: from
description: Namespace that this action is from
type: string
- name: head_branch
description: Name of branch of the head at the time of this workflow run
type: string
- name: head_sha
description: SHA hash of the head at the time of this workflow run
type: string
indicators:
- sha1
- name: is_hosted_runner
description: Whether the workflow runner is hosted
type: boolean
- name: job_name
description: Name of workflow job
type: string
- name: job_workflow_ref
description: Reference of workflow job
type: string
- name: key
description: Name of key related to this action
type: string
- name: method
description: HTTP Method of this action
type: string
- name: programmatic_access_type
description: The type of access for programmatic actions
type: string
- name: public_repo
description: Whether the repository for git audit event is public
type: boolean
- name: referrer
description: Referrer URL of where this action took place
type: string
indicators:
- url
- name: repo_id
description: Repository ID related to this action
type: json
- name: repositories_removed
description: IDs of Repositories that were removed in this action
type: array
element:
type: string
- name: repositories_removed_names
description: Names of Repositories that were removed in this action
type: array
element:
type: string
- name: repository_selection
description: Type of selection for this action related to the repository
type: string
- name: request_category
description: Category of this request
type: string
- name: request_id
description: ID of this action's request
type: string
- name: run_attempt
description: Workflow run attempt
type: bigint
- name: run_number
description: Workflow run number
type: bigint
- name: runner_id
description: ID of this workflow runner
type: string
- name: runner_group_id
description: ID of workflow runner group
type: string
- name: runner_group_name
description: Name of workflow runner group
type: string
- name: runner_labels
description: List of labels of this workflow
type: array
element:
type: string
- name: runner_name
description: Name of the Workflow runner of this action
type: string
- name: secrets_passed
description: List of names of secrets passed to this workflow action
type: json
- name: server_id
description: ID of the Enterprise Server
type: string
- name: started_at
description: Time that the workflow started
type: timestamp
timeFormats:
- rfc3339
- name: token_id
description: ID of the token used in this action
type: string
- name: topic
description: Topic related to workflow run
type: string
- name: trigger_id
description: ID of Trigger that triggered this workflow
type: string
- name: url
description: