GitHub Logs

Panther supports pulling GitHub logs directly and audit log streaming

Overview

Panther supports the following methods of ingesting audit 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.

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 memorable token name e.g. Panther Integration.

5. Select the scopes, or permissions, you'd like to grant this token.

   • Check the boxes next to admin:org > read:org.

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

6. Click Generate token.

7. 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 [name of organization].

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.

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.

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