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
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 (install the app at the org level).
Click on Register an application. Fill in the form:
Enter a memorable application name into the Name field e.g. Panther Integration.
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.
Navigate to Permissions & events and set the Administration>Read permission in the permissions list.
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.
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.
Log in to your Github Enterprise account.
Click on your profile then click on the Settings option.
Scroll to the bottom of the page and click on Developer Settings and then Personal Access Token.
Click Generate new token andenter a descriptive token name, e.g., Panther Integration.
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.
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
In the lefthand navigation bar of your Panther Console, click Configure > LogSources.
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.
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.
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:
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.
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
- 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: token_scopes
description: List of scopes of the token used in this action
type: json
- 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: after
description: Git commit hash of the branch after the event occurred.
type: string
indicators:
- sha1
- name: before
description: Git commit hash of the branch before the event occurred.
type: string
indicators:
- sha1
- name: pull_request_url
description: URL of the pull request
type: string
indicators:
- url
- name: pull_request_title
description: Title of the pull request
type: string
- name: pull_request_id
description: ID of the pull request
type: string
- name: reasons
description: List of reasons for this action
type: array
element:
type: object
fields:
- name: code
description: Reason code
type: string
- name: message
description: Reason message
type: string
- name: overridden_codes
description: List of overridden codes for this action
type: array
element:
type: string
- name: authorized_actors
description: List of authorized actors for this action
type: array
element:
type: string
indicators:
- username
- name: authorized_actor_names
description: List of authorized actor names for this action
type: array
element:
type: string
indicators:
- username
- name: actions_cache_id
description: ID of the cache for this action
type: string
- name: actions_cache_key
description: Key of the cache for this action
type: string
- name: actions_cache_scope
description: Scope of the cache for this action
type: string
- name: actions_cache_version
description: Version of the cache for this action
type: string
- name: alert_number
description: Number of the alert
type: bigint
- name: allow_deletions_enforcement_level
description: Enforcement level for allow deletions
type: string
- name: allow_force_pushes_enforcement_level
description: Enforcement level for allow force pushes
type: string
- name: enforcement_level
description: Enforcement level for this action
type: string
- name: email
description: Email of the actor who performed this action
type: string
indicators:
- email
- name: ghsa_id
description: GitHub Security Advisory Identifier
type: string
- name: lock_allows_fetch_and_merge
description: Whether the lock allows fetch and merge
type: boolean
- name: lock_branch_enforcement_level
description: Enforcement level for lock branch
type: string
- name: required_deployments_enforcement_level
description: Enforcement level for PR required deployments
type: string
- name: required_review_thread_resolution_enforcement_level
description: Enforcement level for PR required review thread resolution
type: string
- name: merge_method
description: Merge method for this action
type: string
- name: merge_queue_enforcement_level
description: Enforcement level for merge queue
type: string
- name: new_repo_base_role
description: Base role for the new repository
type: string
- name: new_repo_permission
description: Permission for the new repository
type: string
- name: oauth_application
description: OAuth application
type: string
- name: oauth_application_id
description: ID of the OAuth application
type: string
- name: old_permission
description: Old permission
type: string
- name: old_permissions
description: List of old permissions
type: json
- name: old_repo_base_role
description: Old base role for the repository
type: string
- name: old_repo_permission
description: Old permission for the repository
type: string
- name: role_permissions
description: List of role permissions
type: json
- name: ruleset_bypass_actors
description: List of ruleset bypass actors
type: json
- name: ruleset_bypass_actors_added
description: List of ruleset bypass actors added
type: json
- name: ruleset_bypass_actors_deleted
description: List of ruleset bypass actors deleted
type: json
- name: ruleset_bypass_actors_updated
description: List of ruleset bypass actors updated
type: json
- name: ruleset_conditions
description: List of ruleset conditions
type: json
- name: ruleset_conditions_added
description: List of ruleset conditions added
type: json
- name: ruleset_conditions_deleted
description: List of ruleset conditions deleted
type: json
- name: ruleset_conditions_updated
description: List of ruleset conditions updated
type: json
- name: ruleset_enforcement
description: Enforcement level for ruleset
type: string
- name: ruleset_id
description: ID of the ruleset
type: string
- name: ruleset_name
description: Name of the ruleset
type: string
- name: ruleset_old_enforcement
description: Old enforcement level for ruleset
type: string
- name: ruleset_old_name
description: Old name of the ruleset
type: string
- name: ruleset_rules
description: List of ruleset rules added
type: json
- name: ruleset_rules_updated
description: List of ruleset rules updated
type: json
- name: ruleset_source_type
description: Source type of the ruleset
type: string
- name: source_version
description: Source version
type: string
- name: strict_required_status_checks_policy
description: Strict required status checks policy
type: boolean
- name: target_version
description: Target version
type: string
- name: check_run_id
description: ID of the check run
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
- 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
- name: permission
description: New permission for the user being modified.
type: string
- name: invitee
description: The user that accepted the invite.
type: string
indicators:
- username
- name: inviter
description: The user that sent the invite.
type: string
indicators:
- username
- name: package_published
description: A package was published or republished to an organization.
type: json
- name: package_version_published
description: A specific package version was published or respublished to a package.
type: json
- name: ecosystem
description: The package ecosystem.
type: string
- name: is_republished
description: Whether the package is republished.
type: boolean
- name: package
description: Name of package.
type: string
- name: version
description: Package version.
type: string
- name: version_count
description: How many package versions.
type: bigint
- name: ip_allow_list_entry
description: An IP address was added to an IP allow list.
type: json
- name: actor_is_bot
description: If actor is bot or not.
type: boolean
- name: integration
description: Name of integration.
type: string