github / ghec-audit-log-cli

Query the GitHub Audit Log for your organization to send it over to other services like elastic, splunk or sentinel for visualization and security

CLI for the Audit Log using GHEC

This CLI made in node helps on querying the audit log. It can query the full audit providing all the data the API can serve, or, given a cursor, it can provide 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.

CLI arguments

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>   location for the config yaml file. Default ".ghec-audit-log" (default: "./.ghec-audit-log")
  -p, --pretty              prints the json data in 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>  Only if -a is v3. API type 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 what source to use for the audit logs. Valid options are enterprise or org. Default: "org"
  -h, --help                display help for command

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

org: org-name
token: xxxxxxxxxxxxxxxx

About tokens and scopes

To use this CLI you will need to use a personal 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.

Endpoint source	Needed scopes
User	read:user
Repository	public_repo
Organization	read:org
Enterprise	admin:enterprise

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

Running the CLI

Execute the command using node or npm

Pre-requisites

Install the node dependencies:

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

npm

$ npm run start -- --pretty

node

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

Installing as CLI

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

Forwarding the log using GitHub Actions

One of the most common uses of the CLI is to forward the log using GitHub actions. You can use as an starter workflow the ones provided in this repository for v3 or v4 and 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

Releases

To create a new release of the ghec-audit-log-cli:

• Create a new release in the repository using semantic versioning
• Add the changelog details for the version
• Submit it as a draft until it's ready to be published

How to use

• Clone the audit-log-cli repository to your Organization
• Set the Action to run on Cron
• Create the GitHub Secrets needed to authenticate
• Enjoy the logs

Secret Values

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

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

Notes

• Modify the polling workflow to run on a cron, instead of push
• The Organization must be a part of a GitHub Enterprise or the API calls will fail
• The Personal Access token must be SSO enabled to query the GitHub Organization if it is enabled

Disclaimer

1. This CLI provides all the events that the GitHub API offers through the GraphQL 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.

ghec-audit-log-cli's Issues

Add support for the new REST API for audit log

Is your feature request related to a problem? Please describe.
Currently this library is oriented only to the GraphQL API. Although it works fine, the path forward is the REST API as it's way easier to use. Because of that, we want to add the functionality of requesting the log using the REST API directly.

Describe the solution you'd like
Use the REST API with the [supported events (https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization#using-the-rest-api) and the API described

The functionality should allow to select the source of the events for streaming. We should also default it to the REST API instead of the GraphQL one

/cc @alwell-kevin

Cursor check is failing "Invalid Cursor"

Describe the bug
The cursor the CLI is commiting is causing the next run to fail because the cursor is not passing the regex expression.

The CLI is commiting the id of the Type.

Here are some example, of the new "cursor" it is commiting

"event_type": "cursor that is commited"
{
   "RepoAccessAuditEntry":"RAAE_kgC2dmxGYVowTlpYQlRUTzJsaE5VMDNFQQ",
   "OrgInviteMemberAuditEntry":"OIMAE_kgC2OGVGWlJlTGh5OWMyMTMxdURLWmVNUQ",
   "TeamAddMemberAuditEntry":"TAMAE_kgC2aEJOV3M1Tk5vQmkxSkd6LWJwSzhBZw",
   "TeamAddRepositoryAuditEntry":"TARAE_kgC2VVBWeFdHbWpNVHZLMVdOQzBJUWFRQQ",
   "RepoCreateAuditEntry":"RCAE_kgC2eU1jSUM2NkJrWXVHNnZXQXFVMnItdw",
   "RepoAddMemberAuditEntry":"RAMAE_kgC2TXpObGdGV21ISUxlTEttcmNreGtZZw",
   "OrgAddMemberAuditEntry":"OAMAE_kgC2aFl0YmFfaHdUdUJ4c1Rlbkl1X1U3Zw",
   "RepoRemoveMemberAuditEntry":"RRMAE_kgC2NVpuYlhLOW9kOHNOaDNzcWMyT2stQQ",
   "TeamChangeParentTeamAuditEntry":"TCPTAE_kgC2SWRzNTlwd2hnY0tWN0ZGZHBNb2cwQQ",
   "RepoArchivedAuditEntry":"RARAE_kgC2aVV3RjVsRlpTbC1VQUszNDVnM3hhZw",
   "OrgRemoveMemberAuditEntry":"ORMAE_kgC2VXQ0Y3JlV2xFbFBsTjBHTk1kOExzZw",
   "TeamRemoveRepositoryAuditEntry":"TRRAE_kgC2S0lXcUVYSGVmNW14T2xvWFRYaE0xZw",
   "TeamRemoveMemberAuditEntry":"TRMAE_kgC2SXVDZVBlY0xXTUNtSlRNeERmWG51Zw",
   "RepoDestroyAuditEntry":"RDAE_kgC2SmI4cXNYVGVOcFFlNWpMVlhsLThCQQ",
   "RepoChangeMergeSettingAuditEntry":"RCMSAE_kgC2Q1JVMjF6OTFhOVZYU2pWbkx1NkRZUQ",
   "RepoAddTopicAuditEntry":"RATAE_kgC2Y200cE5HSnU1VjdBdHNkVm4zdzhDQQ",
   "OrgRestoreMemberAuditEntry":"ORSMAE_kgC2ODhMQ1NkYk4zcktKWXR6NHh5ZXlpZw"
}

Removing the regex check, and letting the cli use the newly commited cursor looks like it allows the cli to gather new events, and it looks like it is not missing any events.

However, the graphql, always says there are new pages after the last event pulled, I'd assume this should be false when we pull the last event.

{
    "organization": {
        "auditLog": {
            "pageInfo": {
                "endCursor": "MS42MzI0MTMwNTQxNzZlKzEyfEsyNnFzbjktaHpaVm1ycFphU2s2THc=",
                "hasNextPage": true
            },
            "nodes": [{
                "__typename": "RepoCreateAuditEntry",
                "id": "RCAE_kgC2bE5VWGotUThlMll0ckZ4S2hfbG8tZw", #<---- this is what gets commited as the last cursor pulled
                "action": "repo.create",

To Reproduce
Steps to reproduce the behavior:
Run the CLI - check the output of the cursor it saves

Expected behavior
The CLI will output a valid cursor that it will use the next run to get all new events

Other

I'm not sure the reason for the change in behavior, but if we can confirm that the new formats are valid we can update the validation.

Update the token scopes needed

Describe the bug

This really isn't a bug, more like an issue with our docs. The README indicates that the token must have the admin:org scope to be able to read the audit log, yet the output I got mentions that more are required.

Some of the scopes needed that were mentioned in the output were"

• read:user
  • user:email
• public_repo

To Reproduce
Steps to reproduce the behavior:

1. Create a PAT that only has the admin:org scope
2. Run the cli or install the CLI
3. Pass the token and org CLI arguments
4. See error output

Expected behavior
A clear and concise description of what you expected to happen.

I think the CLI is behaving as expected. I think the README should be updated and maybe rearranged to indicate that the admin:org scope is the minimum scope needed.

Screenshots
If applicable, add screenshots to help explain your problem.

Not really screenshot but here's the copied CLI output: output.log

Additional context
Add any other context about the problem here.

I was testing this on an org that is part of a GHEC account.

Support for Enterprise export of the audit log

Is your feature request related to a problem? Please describe

We currently only support the audit log in organizations. There is a new API that would allow us to export the audit log from the enterprise itself.

Describe the solution you'd like

Add a new parameter for enterprises, and make it an exclusive operation and only available for v3. That requires some extra validations that we can perform in the utils.

Docs need to be edited so the token has enterprise scope, otherwise it wouldn't work.

Default behavior pulls too few logs

Describe the bug
The default behavior of this project pulls only organization level logs and no logs associated with the repos within an organization. In our case, that limits the usefulness of relying on the V4 API integration because it's missing many logs that we need to have available for our external audits. Switching to the V3 API works.

To Reproduce
Steps to reproduce the behavior:

1. ghec-audit-log-cli -t "PAT" -o "org-id" -p -l 5
2. Review results
3. In our well established org, see many events with "__typename": "OrgAddMemberAuditEntry", and no repo level events

Expected behavior
Expecting to see events taking place on the repo level, especially changes to settings on individual repos. For backstory, we have many audit relevant repositories that must have the Include Administrators option set on protected branches. We need to be able to audit logs that indicate this setting has been changed.

Desktop (please complete the following information):

• OS: Linux CLI

Filter by user

Would be nice to be able to filter by user.

node ghec-audit-log-cli -u paolo
node ghec-audit-log-cli --user paolo