Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/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
https://github.com/github/ghec-audit-log-cli
audit-log enterprise github services-toolbox
Last synced: 3 months ago
JSON representation
Query the GitHub Audit Log for your organization to send it over to other services like elastic, splunk or sentinel for visualization and security
- Host: GitHub
- URL: https://github.com/github/ghec-audit-log-cli
- Owner: github
- License: mit
- Created: 2020-05-07T10:00:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T00:58:57.000Z (over 1 year ago)
- Last Synced: 2024-09-30T00:20:39.468Z (3 months ago)
- Topics: audit-log, enterprise, github, services-toolbox
- Language: JavaScript
- Homepage: https://github.com/github/ghec-audit-log-cli
- Size: 378 KB
- Stars: 63
- Watchers: 214
- Forks: 11
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
> [!WARNING]
> ### This repository has been deprecated and is no longer maintained
>
> The features of this tool are now natively supported in GitHub, please explore the following options;
> - [Audit Log Streaming](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise)
> - Access the Audit Log directly via our APIs
> - [REST API: Audit Log](https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/audit-log?apiVersion=2022-11-28)
> - [GraphQL: Audit Log](https://docs.github.com/en/enterprise-cloud@latest/graphql/reference/unions#organizationauditentry)
> - Query the Audit Log APIs via our [`gh` CLI](https://cli.github.com/manual/gh_api)
# 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:
```shell
> node ghec-audit-log-cli.js "--help"
Usage: audit-log-ghec-cli [options]
Options:
-v, --version Output the current version
-t, --token the token to access the API (mandatory)
-o, --org the organization we want to extract the audit log from
-cfg, --config 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 a maximum limit on the number of items retrieved
-f, --file the output file where the result should be printed
-a, --api the version of GitHub API to call (default: "v4")
-at, --api-type Only if -a is v3. API type to bring, either all, web or git (default: "all")
-c, --cursor 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.
```yaml
org: org-name
token: xxxxxxxxxxxxxxxx
```
### About tokens and scopes
To use this CLI you will need to use a [personal access token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) 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:
```shell script
$ git clone https://github.com/github/ghec-audit-log-cli
$ cd ghec-audit-log-cli
$ npm install
```
### npm
```shell script
$ npm run start -- --pretty
```
### node
```shell script
$ 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:
```shell script
$ 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:
```shell script
$ 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](workflows/forward-v3-workflow.yml) or [v4](workflows/forward-v4-workflow.yml)
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](https://github.com/github/ghec-audit-log-cli/releases/new) using [semantic versioning](https://semver.org/)
- 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](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-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](https://docs.github.com/en/free-pro-team@latest/graphql/overview/schema-previews#audit-log). 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.