icon/x Created with Sketch.

Splunk Cookie Policy

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website. Learn more (including how to update your settings) here.
Accept Cookie Policy

We are working on something new...

A Fresh New Splunkbase
We are designing a New Splunkbase to improve search and discoverability of apps. Check out our new and improved features like Categories and Collections. New Splunkbase is currently in preview mode, as it is under active development. We welcome you to navigate New Splunkbase and give us feedback.
Log4Shell Vulnerability: Information and guidance for you. Get resources.

Accept License Agreements

This app is provided by a third party and your right to use the app is in accordance with the license provided by that third-party licensor. Splunk is not responsible for any third-party apps and does not provide any warranty or support. If you have any questions, complaints or claims with respect to this app, please contact the licensor directly.

Thank You

Downloading GitHub Audit Log Monitoring Add-On for Splunk
SHA256 checksum (github-audit-log-monitoring-add-on-for-splunk_111.tgz) db1070f3082422ba00d858552a869eef807c9174dfd2baa656f1636577229142 SHA256 checksum (github-audit-log-monitoring-add-on-for-splunk_100.tgz) 0664755531e73bf23cd1f0581e6031e3c542067e271335a88b3ab12c3136eb03
To install your download
For instructions specific to your download, click the Details tab after closing this window.

Flag As Inappropriate

splunk

GitHub Audit Log Monitoring Add-On for Splunk

Splunk Cloud
Splunk Labs
Overview
Details
Quickly collect Github Enterprise Audit Logs for expanded Github security and operations visibility. All Github audit log actions are collected for visibility across organizations, repositories, and users. Easily detect when a new user is added to a repo or when a new admin is invited.

GitHub Enterprise Audit Log Monitoring

This modular input makes an HTTPS request to the GitHub Enterprise's Audit Log REST API endpoint at a definable interval to fetch audit log data.

Prerequisites

  • Splunk Heavy Forwarder v8.0+
  • Python 3.7+
  • GitHub Enterprise Cloud

Installation

  1. Download the latest release from Splunkbase

  2. On a Splunk Heavy Forwarder, go to Apps > Manage Apps.

  3. On the Apps page, click Install app from file, and upload the SPL file you downloaded from Splunkbase. If an existing copy of the app already exists, please check the Upgrade app checkbox.

  4. Generate a Personal Access Token in GitHub Enterprise with the site_admin scope.

Configuration

Personal Access Token Scope

The following are the required scopes for the personal access token allowing the module to fetch the audit log entries successfully:

  • [x] admin:enterprise Full control of enterprises
  • [x] manage_billing:enterprise Read and write enterprise billing data
  • [x] read:enterprise Read enterprise profile data

Input Fields

  • name

  • This is name of your instance. You can have multiple modular inputs running simultaneously. However, this is not a recommended behavior for this module.

  • Takes: alpha-numeric, white spaces and symbol characters
  • Example: GHE-enterprise-name

  • Hostname

  • This is the hostname of your GitHub Enterprise instance. Make sure there are no leading http:///https:// or trailing / in the URL provided. This could either be a FQDN or an IP address. Do not append any paths beyond the tld.

  • Example: api.github.com

  • Enterprise

  • The enterprise name for which to fetch audit log events

  • Personal Access Token

  • This is your personal access token that you generate for your or a service account in GitHub Enterprise. This module requires that the personal access token be created with the site_admin scope. This is a very sensitive token so make sure to keep it secure at all times!

  • Security: The personal access token is encrypted and stored in Splunk's password storage. After you configure it the first time it will be replaced in Splunk's UI with a unique identifier. This identifier will be used by the module to fetch the personal access token before making the API request to GitHub Enterprise.
  • Takes: a 40 character token
  • Example: d0e117b6ad471der3rjdowcc401a95d09202119f

  • Event Types

  • The audit log contains multiple event types. This field allows you to specify which events to include:

    • web - returns web (non-Git) events
    • git - returns Git events
    • all - returns both web and Git events
  • More details

  • Maximum Entries Per Run

  • The maximum number of events / entries to fetch each time the script runs. To understand how to calculate the maximum number of entries and interval to best fit your organization go to the Tweaking throughput section below.

  • Verify Self-Signed Certificates

  • This is a parameter passed to the get() method in the Requests library. If the checkbox is cheked then the SSL certificate will be verified like a browser does and Requests will throw a SSLError if it’s unable to verify the certificate. Uncheck this box if you are using self-signed certificates.

  • Debug Mode

  • The personal access token will be leaked in the splunkd logs. DO NOT ENABLE unless you are ready to update your personal access token.

  • If you are experiencing issues and the module is not operating as intended, you can enable this mode to seethe module's debugging information in the splunkd logs.

  • Interval

  • Takes a cron expression as defined in the Splunk docs.

  • Example: 30 * * * *
    • At minute 30 of every hour. For example, if you set this CRON job at 11:02, your job will begin running at 11:30, 12:30, 1:30, etc...
  • Example: */5 * * * *
    • Every 5 minutes
  • Example: 300
    • Every 300 seconds or 5 minutes

Tweaking throughput

This modular input fetches events by calling the Enterprise Audit Log API. This API returns a maximum of 100 events / entries per page. The pagination algorithm can fetch events up to the maximum entries per run defined. It's important to tweak the maximum entries per run and interval parameters to have the ability to fetch your data in a timely manner and stay as close to real-time as possible.

Example:
| Enterprise | Events per minute | Maximum entries per run | Interval | API calls used | Guidance |
|--------------|-------------------|-------------------------|-------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Evil-Corp | 1000 | 1000 | /1 * | 600 per hour | The modular input should be able to handle this with ease. |
| Poizen-Inc | 5000 | 5000 | /1
* | 3000 per hour | We are approaching API rate limit per hour. Depending on latency, 5000 entries = 50 API calls per minute. One minute might not be sufficient to fetch all this data. |
| Monsters-Inc | 10000 | 2000 | /1 ** * | 1200 per hour | You will be fetching events with a slight delay. |

FAQs

How is my Personal Access Token secured?

On the first run the modular input will identify that your personal access token (PAT) is not encrypted. It will encrypt your PAT and store it in Splunk's credentials manager. It will replace the plaintext PAT with an md5 hash of an identifying key.

Your personal access token is only visible in plaintext from the time you configure the modular input instance until the first run.

Does the interval field access only cron syntax?

No, you can enter the number of seconds instead.

I enabled debug mode, what now?

If you've enabled debug mode be ready to change your personal access token because it will most likely be leaked into the Splunk logs in plain text.

Why can't I use a GitHub app instead of a personal access token?

GitHub apps cannot be installed on the enterprise level. The REST API requires enterprise admin privileges which are out of scope for GitHub apps.

Can I use this with GitHub Enterprise Server?

This tool has been designed to consume the Enterprise Audit Log API which is not available for GitHub Enterprise Server because the audit log on the latter can be forwarded via log forwarding directly to Splunk without the need to poll for data.

Support

Support for Github Audit Log Monitoring Add-On for Splunk is run through Github Issues. Please open a new issue for any support issues or for feature requests. You may also open a Pull Request if you'd like to contribute additional dashboards, eventtypes for webhooks, or enhancements you may have.

Troubleshooting

Read logs in Splunk

You can use this search query to fetch all the logs belonging to this module when Debug Mode is enabled.

index="_internal" source="/opt/splunk/var/log/splunk/splunkd.log" ghe_audit_log_monitoring

Test the modular input for syntax problems

Run this test if you don't see anything in the logs (which is a highly unlikely scenario). This will display any syntax errors if there are any.

sudo $SPLUNK_HOME/bin/splunk cmd python $SPLUNK_HOME/etc/apps/ghe_audit_log_monitoring/bin/ghe_audit_log_monitoring.py

Where are state files stored?

State files for enterprises are stored in this directory:

$SPLUNK_HOME/etc/apps/ghe_audit_log_monitoring/state/

Release Notes

Version 1.1.1
Nov. 29, 2021

This update includes support for paid Enterprise tier Organizations or collecting from a GitHub Enterprise Cloud account at the Organization level. Continued support for GitHub Enterprise Cloud collection at the Enterprise level. Replaces the 1.1.0 release with fixes for Splunk Cloud Vetting approval.

Version 1.0.0
June 20, 2021

Quickly collect Github Enterprise Audit Logs for expanded Github security and operations visibility. All Github audit log actions are collected for visibility across organizations, repositories, and users. Easily detect when a new user is added to a repo or when a new admin is invited.


Subscribe Share

Are you a developer?

As a Splunkbase app developer, you will have access to all Splunk development resources and receive a 10GB license to build an app that will help solve use cases for customers all over the world. Splunkbase has 1000+ apps from Splunk, our partners and our community. Find an app for most any data source and user need, or simply create your own with help from our developer portal.

Follow Us:
Splunk, Splunk>,Turn Data Into Doing, Data-to-Everything, and D2E are trademarks or registered trademarks of Splunk Inc. in the United States and other countries. All other brand names,product names,or trademarks belong to their respective owners.