Repository files navigation

This CLI made in node helps on querying the audit log. It can query the fullaudit providing all the data the API can serve, or, given a cursor, it canprovide the newest entries from that specific moment.

You can build an sh script on top of this one to store the data or query it.

This script can take the following arguments:

> node ghec-audit-log-cli.js"--help"Usage: audit-log-ghec-cli [options]Options:  -v, --version             Output the current version  -t, --token<string>      the token to access the API (mandatory)  -o, --org<string>        the organization we want to extract the audit log from  -cfg, --config<string>   locationfor the config yaml file. Default".ghec-audit-log" (default:"./.ghec-audit-log")  -p, --pretty              prints the json datain a readable format (default: false)  -l, --limit<number>      a maximum limit on the number of items retrieved  -f, --file<string>       the output file where the result should be printed  -a, --api<string>        the version of GitHub API to call (default:"v4")  -at, --api-type<string>  Onlyif -a is v3. APItype to bring, either all, web or git (default:"all")  -c, --cursor<string>if provided, this cursor will be used to query the newest entries from the cursor provided. If not present, the result will contain all the audit log from the org  -s, --source              indicate whatsource to usefor the audit logs. Valid options are enterprise or org. Default:"org"  -h, --help                displayhelpforcommand

Optionally, you can create a file called.ghec-audit-log that supportsthetoken andorganization, and omit the parameters while running the script.

org:org-nametoken:xxxxxxxxxxxxxxxx

To use this CLI you will need to use apersonal access token (PAT) with the correct scopes. The scopes will change depending on what source you are going to use to export the audit logs.

If you are running this utility against a GHEC account, we recommend that you create your PAT with both scopes.

Execute the command using node or npm

Install the node dependencies:

$ git clone https://github.com/github/ghec-audit-log-cli$cd ghec-audit-log-cli$ npm install

$ npm run start -- --pretty

$ node ghec-audit-log-cli --pretty

Optionally you can install the script as a CLI and run it from the command line. To install it run:

$ git clone https://github.com/github/ghec-audit-log-cli$cd ghec-audit-log-cli$ npm link

Then you can execute the script as a CLI using:

$ ghec-audit-log-cli -v

One of the most common uses of the CLI is to forward the log using GitHub actions. You canuse as an starter workflow the ones provided in this repository forv3 orv4and integrate it with your favorite service.

This workflow:

• Runs periodically
• Grabs any existing cursor as the last item grabbed from the log
• Grabs the latest changes from the audit log
• Forwards those changes to a service
• Commits the latest cursor for the next call

To create a new release of theghec-audit-log-cli:

• Create a new releasein the repository usingsemantic versioning
• Add the changelog details for the version
• Submit it as a draft until it's ready to be published

• Clone theaudit-log-cli repository to your Organization
• Set theAction to run on Cron
• Create theGitHub Secrets needed to authenticate
• Enjoy the logs

You will need to create the followingGithub Secrets To allow the tool to work:

• AUDIT_LOG_TOKEN
  • This is aGitHub Personal Access Token used to authenticate to your Organization
  • Note: The token must have theadmin:org set to be able to pull information
• ORG_NAME
  • Name of theGitHub Organization to poll the audit log
• WEBHOOK_URL
  • URL to a service where the generatedjson information is piped
• COMMITTER_EMAIL
  • Email address for one of the primary committers on the repository

• Modify the polling workflow to run on a cron, instead of push
• TheOrganizationmust be a part of aGitHub Enterprise or the API calls will fail
• ThePersonal Access tokenmust be SSO enabled to query the GitHub Organization if it is enabled

1. This CLI provides all the events that the GitHub API offers through theGraphQL API. This is a subset of all the events that you can see through the UI.
2. This tool will be deprecated when GitHub adds a forwarding behavior on GHEC.