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.
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.
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:
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
In the left-hand navigation bar of your Panther Console, click Configure > Log Sources.
Click Create New.
Search for “GitHub Webhooks,” then click its tile.
In the slide-out panel, the Transport Mechanism dropdown in the upper right corner will be pre-populated with the HTTP option.
All Panther-managed GitHub detections include the filter_include_event helper function. You can customize this function to include or exclude certain logs based on a field value. This filter may be useful if you're using audit log streaming to ingest GitHub enterprise logs, but you'd like to filter out certain organizations. As an example, see it in use in the GitHub.Action.Failed detection.
Required fields in the schema are listed as "required: true" just below the "name" field.
GitHub.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.Webhookdescription:Webhooks events are generated whenever certain events occur on GitHubreferenceURL:https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloadsfields: - name:action description: Most webhook payloads contain an action property that contains the specific activity that triggered the event.
type:string - name:target_typedescription:Type of target of the eventtype:string - name:refdescription:The Git reference of the eventtype: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:branchdescription:The name of the branch.type:string - name:master_branchdescription:The name of the repository's default branch (usually main).type:string - name:pusher_typedescription:The pusher type for the event. Can be either user or a deploy key.type:string - name:ref_typedescription:'The type of Git ref object created in the repository. Can be one of: tag, branch'type:string - name:hook_iddescription:The id of the modified webhook.type:string - name:base_refdescription:The name of the base branch that the head_ref is based on.type:string - name:beforedescription:The SHA of the most recent commit on ref before the push.type:string - name:afterdescription:The SHA of the most recent commit on ref after the push.type:string - name:numberdescription:The pull request number.type:string - name:comparedescription:URL to examine the changestype:string - name:forceddescription:Whether this push was a force push of the ref.type:boolean - name:createddescription:Whether this push created the ref.type:boolean - name:deleteddescription:Whether this push deleted the ref.type:boolean - name:senderrequired:truedescription: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_rulesetdescription: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:enterprisedescription:The GitHub Enterprise the event is related totype: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_rundescription:A check performed on the code of a given code changetype:json - name:check_suitedescription:The check suitetype:json - name:alertdescription:The code scanning alert involved in the event.type:json - name:commentdescription:Commit comment resourcetype:json - name:descriptiondescription:Description of the eventtype:json - name:keydescription:The key of the eventtype:json - name:deploymentdescription:Deployment related event detailstype:json - name:workflowdescription:Workflow related event detailstype:json - name:workflow_rundescription:Workflow runtype:json - name:workflow_jobdescription:Workflow jobtype:json - name:environmentdescription:Environment where event occurredtype:json - name:eventdescription:Event detailstype:json - name:deployment_callback_urldescription:The URL to review the deployment protection rule.type:json - name:pull_requestsdescription:Pull requests related to the eventtype:json - name:pull_requestdescription:Pull request detailstype:json - name:reviewdescription:Pull request review detailstype:json - name:threaddescription:Pull request review comment thread detailstype:json - name:assigneedescription:The user that was assigned or unassigned from a pull request.type:json - name:approverdescription:The user that approved a deployment.type:json - name:deployment_statusdescription:Deployment status detailstype:json - name:discussiondescription:Discussion detailstype:json - name:answerdescription:Discussion answer detailstype:json - name:forkeedescription:The created repository resourcetype:json - name:pagesdescription:GitHub pages related to the eventtype:json - name:repositoriesdescription:Repository detailstype:json - name:requesterdescription:Who requested the eventtype:json - name:repositories_addeddescription:Repositories added in the eventtype:json - name:repositories_removeddescription:Repositories removed in the eventtype:json - name:repositories_selectiondescription:Describe whether all repositories have been selected or there's a selection involved.type:string - name:changesdescription:Changes detailstype:json - name:issuedescription:Issue detailstype:json - name:labeldescription:Label detailstype:json - name:teamdescription:GitHub team detailstype: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:releasedescription:Release detailstype:json - name:repository_advisorydescription:Repository security advisorytype:json - name:locationdescription:Location detailstype:json - name:security_advisorydescription:Security advisory detailstype:json - name:inputsdescription:Input detailstype:json - name:statusdescription:Status of the eventtype:json - name:pusherdescription:Metaproperties for Git author/committer information.type:json - name:head_commitdescription:Head commit detailstype:json - name:commitsdescription:Commit detailstype:json - name:commitdescription:Commit detailstype:json - name:shadescription:The SHA of the committype:string - name:statedescription:The state of the status. Can be one of pending, success, error, or failure.type:string - name:contextdescription:Context details when the status of a Git commit changes.type:string - name:memberdescription:Member details. Only present when there is activity relating to collaborators.type:json - name:membershipdescription:The membership between the user and the organization. Not present when the action is member_invited.type:json - name:blocked_userdescription:Details of the blocked user (if any)type:json - name:invitationdescription:The invitation for the user or email if the action is member_invited.type:json - name:userdescription:The user that was invited. Only present when the action is member_invited.type:json - name:packagedescription:Information about the GitHub Package.type:json - name:builddescription:Information about the build of a GitHub Pages site.type:json - name:personal_access_token_requestdescription:Information about the personal access token request.type:json - name:zendescription:Random string of GitHub zen.type:string - name:projectdescription:Classic project detailstype:json - name:project_carddescription:Classic project card details.type:json - name:project_columndescription:Classic project column details.type:json - name:projects_v2description:Project detailstype:json - name:projects_v2_itemdescription:An item belonging to a projecttype:json - name:registry_packagedescription:Information about the GitHub Registry package.type:json - name:client_payloaddescription:Client payload when creating a repository dispatch event.type:json - name:sponsorshipdescription:Details relating to a sponsorship listing.type:json - name:marketplace_purchasedescription:Details relating to a GitHub Marketplace purchase.type:json - name:previous_marketplace_purchasedescription:Details relating to a previous GitHub Marketplace purchase.type:json - name:effective_datedescription: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.Auditdescription: 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_iddescription:Document id for the audit log eventstype:string - name:workflow_iddescription:Workflow id if the event is CI workflowtype:string - name:workflow_run_iddescription:Workflow run id if the event is CI workflowtype:string - name:actionrequired:truedescription:The action performedtype:string - name:actordescription:Actor that performed the actiontype:stringindicators: - username - name:created_atdescription:Creation timestamp for audit eventtype:timestamptimeFormats: - unix_msisEventTime:true - name:'@timestamp'description:Timestamp for the eventtype:timestamptimeFormats: - unix_msisEventTime:true - name:completed_atdescription:Completion timestamp for audit eventtype:string - name:actor_locationdescription:Actor locationtype:objectfields: - name:country_coderequired:truedescription:Country code for the actor's location'type:string - name:country_namedescription:Country name for the actor's locationtype:string - name:regiondescription:Region code of where this action originated fromtype:string - name:region_namedescription:Region name of where this action originated fromtype:string - name:citydescription:Name of the city where this action originated fromtype:string - name:postal_codedescription:Postal code where this action originated fromtype:string - name:locationdescription:Actor's location in longitude/latitudetype:objectfields: - name:latdescription:Latitude fieldtype:float - name:londescription:Longitude fieldtype:float - name:orgdescription:The Organization where the action was performedtype:json - name:configdescription:Webhook configurationtype:objectfields: - name:content_typedescription:content type for the webhooktype:string - name:insecure_ssldescription:Boolean value if ssl connection is securetype:string - name:urldescription:payload URL for webhooktype:string - name:config_wasdescription:Previous webhook configurationtype:objectfields: - name:content_typedescription:content type for the webhooktype:string - name:insecure_ssldescription:Boolean value if ssl connection is securetype:string - name:urldescription:payload URL for webhooktype:string - name:hook_iddescription:Webhook IDtype:string - name:namedescription:name of the event action categorytype:string - name:activedescription:Webhook is activetype:boolean - name:repodescription:Name, or names of the repositories involved in the actiontype:json - name:visibilitydescription:Visibility of the repositorytype:string - name:eventsdescription:List of events which will send webhook payloadtype:arrayelement:type:string - name:userdescription:User added/removed for certain permissiontype:stringindicators: - username - name:teamdescription:Team name for team category actiontype:string - name:eventdescription:Workflow eventtype:string - name:transport_protocol_namedescription:Transport protocol name for git audit eventstype:string - name:transport_protocoldescription:Transport protocol for git audit eventstype:int - name:repositorydescription:Repository name for git eventtype:string - name:repository_publicdescription:If the repository for git audit event is publictype:boolean - name:business_iddescription:ID of the enterprise affected by the action (if applicable)type:string - name:numberdescription:Number fieldtype:bigint - name:active_wasdescription:Webhook was activetype:boolean - name:actor_iddescription:The id of the actor who performed the actiontype:stringindicators: - actor_id - name:blocked_userdescription:The username of the account being blockedtype:stringindicators: - username - name:businessdescription:The name of the business that relates to this actiontype:string - name:content_typedescription:Type of contenttype:string - name:datadescription:Additional data related to this actiontype:json - name:deploy_key_fingerprintdescription:Fingerprint of deploy keytype:string - name:emojidescription:Emoji that relates to this actiontype:string - name:events_weredescription:List of events which were senttype:arrayelement:type:json - name:explanationdescription:An explanation of the actiontype:string - name:fingerprintdescription:Fingerprint related to this actiontype:string - name:limited_availabilitydescription:Limited availabilitytype:boolean - name:messagedescription:Message related to this actiontype:string - name:old_userdescription:The old user related to this actiontype:string - name:openssh_public_keydescription:Public Open SSH key related to this actiontype:string - name:operation_typedescription:Type of operationtype:string - name:org_iddescription:The Organization ID where the action was performedtype:json - name:previous_visibilitydescription:Visibility of repository prior to this actiontype:string - name:read_onlydescription:Whether the item related to this action is read onlytype:boolean - name:target_logindescription:Target logintype:string - name:user_iddescription:User IDtype:stringindicators: - 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:stringindicators: - 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_nameiddescription:Displayed when SAML SSO identity was used as a means of authenticationtype:stringindicators: - username - name:external_identity_usernamedescription:Displayed when SAML SSO identity was used as a means of authentication with Enterprise Managed Userstype:stringindicators: - username - name:actor_sessiondescription:Actor's session IDtype:string - name:branchdescription:Branch that relates to this actiontype:string - name:category_typedescription:Type of category this action is fromtype:string - name:client_iddescription:ID of the client being used in this actiontype:string - name:conclusiondescription:Workflow run conclusiontype:string - name:controller_actiondescription:Action of the controllertype:string - name:device_cookiedescription:Cookie of the actor's session from this actiontype:string - name:environment_namedescription:Environment name of workflowtype:string - name:fork_sourcedescription:Source repository of this forktype:string - name:fork_source_iddescription:Source repository ID of this forktype:string - name:fromdescription:Namespace that this action is fromtype:string - name:head_branchdescription:Name of branch of the head at the time of this workflow runtype:string - name:head_shadescription:SHA hash of the head at the time of this workflow runtype:stringindicators: - sha1 - name:is_hosted_runnerdescription:Whether the workflow runner is hostedtype:boolean - name:job_namedescription:Name of workflow jobtype:string - name:job_workflow_refdescription:Reference of workflow jobtype:string - name:keydescription:Name of key related to this actiontype:string - name:methoddescription:HTTP Method of this actiontype:string - name:programmatic_access_typedescription:The type of access for programmatic actionstype:string - name:public_repodescription:Whether the repository for git audit event is publictype:boolean - name:referrerdescription:Referrer URL of where this action took placetype:stringindicators: - url - name:repo_iddescription:Repository ID related to this actiontype:json - name:repositories_removeddescription:IDs of Repositories that were removed in this actiontype:arrayelement:type:string - name:repositories_removed_namesdescription:Names of Repositories that were removed in this actiontype:arrayelement:type:string - name:repository_selectiondescription:Type of selection for this action related to the repositorytype:string - name:request_categorydescription:Category of this requesttype:string - name:request_iddescription:ID of this action's requesttype:string - name:run_attemptdescription:Workflow run attempttype:bigint - name:run_numberdescription:Workflow run numbertype:bigint - name:runner_iddescription:ID of this workflow runnertype:string - name:runner_group_iddescription:ID of workflow runner grouptype:string - name:runner_group_namedescription:Name of workflow runner grouptype:string - name:runner_labelsdescription:List of labels of this workflowtype:arrayelement:type:string - name:runner_namedescription:Name of the Workflow runner of this actiontype:string - name:secrets_passeddescription:List of names of secrets passed to this workflow actiontype:json - name:server_iddescription:ID of the Enterprise Servertype:string - name:started_atdescription:Time that the workflow startedtype:timestamptimeFormats: - rfc3339 - name:token_iddescription:ID of the token used in this actiontype:string - name:topicdescription:Topic related to workflow runtype:string - name:trigger_iddescription:ID of Trigger that triggered this workflowtype:string - name:urldescription:URL where this action took placetype:stringindicators: - url - name:user_agentdescription:User agent of the actor who performed this actiontype:string - name:user_programmatic_access_namedescription:Name of the user who performed the actiontype:stringindicators: - username - name:admin_enforceddescription:Repository management policy settings for the admintype:boolean - name:pull_request_reviews_enforcement_leveldescription:Enforcement level for PR reviewstype:json - name:required_status_checks_enforcement_leveldescription:Enforcement level for PR required status checkstype:json - name:linear_history_requirement_enforcement_leveldescription:Enforcement level for linear history requirementtype:json - name:required_approving_review_countdescription:How many reviewers must approve the actiontype:int - name:require_code_owner_reviewdescription:Whether the codeowner's approval is required on this PRtype:boolean - name:signature_requirement_enforcement_leveldescription:Enforcement level of the signaturetype:int - name:old_namedescription:Previous name of the entity being modifiedtype:string
