GitHub Logs

Panther supports pulling GitHub logs directly and audit log streaming

Overview

Panther supports the following methods of ingesting logs from GitHub:

• GitHub API

  • 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.

• GitHub audit log streaming

  • 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.

• GitHub webhook events

  • Panther supports ingesting GitHub webhooks directly via HTTP.

  • This method works at GitHub's Organization level.

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.

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

OAuth App

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.

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.

Personal Access Token

Option 2: Generate a 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. 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_log scope.

     • If the read:audit_log scope is not available to you, select the admin:org > read:org permission instead.

   • You do not need to enable the write:org permission.

6. Click Generate token.

   • Copy the token and store it in a secure location – you will need it in the next steps.

Step 2: Create a new GitHub API source in Panther

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:

    

    • 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:

1. Set up audit log streaming from GitHub to a storage destination.

2. Create a new GitHub Audit Log Streaming source in Panther.

Prerequisite

• 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

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:

   • For S3, follow the documentation on how to enable Panther to pull logs from S3.

     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.
   • For GCS, follow the documentation on how to enable Panther to pull logs from GCS.

How to onboard GitHub webhook events

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.

Step 1: Create a GitHub Webhooks source in Panther

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. Follow Panther's instructions for configuring an HTTP Source, beginning at Step 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.

Step 2: Create the webhook in GitHub

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.

   • See descriptions of event types in GitHub's Webhook events and payloads documentation.
6. Click Add Webhook.

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

Required fields in the schema are listed as "required: true" just below the "name" field.

GitHub.Webhook

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

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: user_programmatic_access_name
    description: Name of the user who performed the action
    type: string
    indicators:
      - username
  - 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
  - name: required_approving_review_count
    description: How many reviewers must approve the action
    type: int
  - name: require_code_owner_review
    description: Whether the codeowner's approval is required on this PR
    type: boolean
  - name: signature_requirement_enforcement_level
    description: Enforcement level of the signature
    type: int
  - name: old_name
    description: Previous name of the entity being modified
    type: string