GitHub Logs
Panther supports pulling GitHub logs directly and audit log streaming
Overview
Panther supports the following methods of ingesting audit logs from GitHub:
Panther can fetch GitHub audit logs by querying the GitHub API for new events every one minute.
This method works at GitHub's Organization level.
Panther can ingest GitHub audit logs using GitHub's audit log streaming feature via AWS S3 or Google Cloud Storage.
This method works at GitHub's Enterprise level.
How to onboard GitHub Organization logs to Panther
Your Github Organization needs to be part of a Github Enterprise Cloud deployment. The Github Enterprise Server self-hosted option is not yet supported.
Step 1: Authorize Panther in GitHub
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
Option 1: Create a new OAuth App
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.
Log in to your GitHub Enterprise account.
On the homepage of your organization's account, click on the Settings tab.
Scroll to the bottom of the page and click on Developer Settings and then OAuth Apps.
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.
Once all necessary fields are filled in, click Register Application.
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.
Step 2: Create a new GitHub API source in Panther
In the lefthand navigation bar of your Panther Console, click Configure > Log Sources.
Click Create New.
Search for “GitHub API,” then click its tile.
On the slide-out panel, click Start Setup.
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.Click Setup.
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.
Click Setup.
You will be presented with the option to Grant Access.
Click Authorize [name of organization].
You will be directed to a success screen:
You can optionally enable one or more Detection Packs.
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.
How to onboard GitHub logs via audit log streaming to Panther
There are two steps to configure GitHub audit log streaming with Panther:
Set up audit log streaming from GitHub to a storage destination.
Create a new GitHub Audit Log Streaming source in Panther.
Audit log streaming must be configured in GitHub by your GitHub enterprise owner
Step 1: Set up audit log streaming from GitHub to a storage destination
Panther supports ingesting GitHub audit log streaming data from two storage destinations. Choose one of the storage destinations below:
AWS S3
Follow the instructions here: Setting up streaming for Amazon S3.
Google Cloud GCS
Follow the instructions here: Setting up streaming to Google Cloud Storage.
Step 2: Create a new GitHub audit log streaming source in Panther
In the lefthand navigation bar of the Panther Console, click Configure > Log Sources.
Click Create.
Search for GitHub. Select the GitHub Audit Log Streaming tile.
Select either S3 or GCS, depending on the transport method you chose.
Follow the onboarding process for your chosen destination method:
For S3, follow the documentation on how to enable Panther to pull logs from S3.
After creating your S3 bucket in Panther, navigate to the source's Schema tab, and click Advanced Edit & Test with Raw Events.
Set an S3 Exclusion Filter with a value of
_check
.
For GCS, follow the documentation on how to enable Panther to pull logs from GCS.
Panther-managed detections
See Panther-managed rules for GitHub in the panther-analysis GitHub repository.
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.
Querying logs in Data Explorer
To see examples of querying GitHub logs in Panther's Data Explorer, see Github Audit logs queries.
Supported log types
Github.Audit
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: URL where this action took place
type: string
indicators:
- url
- name: user_agent
description: User agent of the actor who performed this action
type: string
- name: admin_enforced
description: Repository management policy settings for the admin
type: boolean
- name: pull_request_reviews_enforcement_level
description: Enforcement level for PR reviews
type: json
- name: required_status_checks_enforcement_level
description: Enforcement level for PR required status checks
type: json
- name: linear_history_requirement_enforcement_level
description: Enforcement level for linear history requirement
type: json
Last updated
Was this helpful?