https://github.com/github/entitlements-gitrepo-auditor-plugin
Entitlements plugin for a robust audit log
https://github.com/github/entitlements-gitrepo-auditor-plugin
audit entitlements iam security
Last synced: 10 months ago
JSON representation
Entitlements plugin for a robust audit log
- Host: GitHub
- URL: https://github.com/github/entitlements-gitrepo-auditor-plugin
- Owner: github
- License: mit
- Created: 2022-06-07T16:08:58.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-05-05T12:40:19.000Z (10 months ago)
- Last Synced: 2025-05-10T20:02:06.524Z (10 months ago)
- Topics: audit, entitlements, iam, security
- Language: Ruby
- Homepage:
- Size: 27 MB
- Stars: 21
- Watchers: 43
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# entitlements-gitrepo-auditor-plugin
[](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/acceptance.yml) [](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/test.yml) [](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/lint.yml) [](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/build.yml) [](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/gem.yml) [](https://github.com/github/entitlements-gitrepo-auditor-plugin/actions/workflows/codeql-analysis.yml) [](https://img.shields.io/badge/coverage-100%25-success) [](https://github.com/github/rubocop-github)
`entitlements-gitrepo-auditor-plugin` is an [entitlements-app](https://github.com/github/entitlements-app) plugin allowing further auditing capabilities in entitlements by writing each deploy log to a separate GitHub repo.
## Usage
Your `entitlements-app` config `config/entitlements.yaml` runs through ERB interpretation automatically. You can extend your entitlements configuration to load plugins like so:
```ruby
<%-
unless ENV['CI_MODE']
begin
require_relative "/data/entitlements/lib/entitlements-and-plugins"
rescue Exception
begin
require_relative "lib/entitlements-and-plugins"
rescue Exception
# We might not have the plugins installed and still want this file to be
# loaded. Don't raise anything but silently fail.
end
end
end
-%>
```
You can then define `lib/entitlements-and-plugins` like so:
```ruby
#!/usr/bin/env ruby
# frozen_string_literal: true
ENV["BUNDLE_GEMFILE"] = File.expand_path("../../Gemfile", File.dirname(__FILE__))
require "bundler/setup"
require "entitlements"
# require entitlements plugins here
require "entitlements/auditor/gitrepo"
require "entitlements/util/gitrepo"
```
Any plugins defined in `lib/entitlements-and-plugins` will be loaded and used at `entitlements-app` runtime.
## Features
### Git Repo Auditing
You can add automatic auditing to a separate GitRepo by enabling the following `entitlements.yaml` config:
```ruby
<%-
# NOTE: GITREPO_SSH_KEY must be base64 encoded.
sshkey = ENV.fetch("GITREPO_SSH_KEY")
shipper = ENV.fetch("GIT_SHIPPER", "")
what = ["entitlements", ENV.fetch("GIT_BRANCH", "")].join("/")
sha = ENV.fetch("GIT_SHA1", "")
url = "https://github.com/github/entitlements-config/commit/#{sha}"
commit_message = "#{shipper} deployed #{what} (#{url})"
-%>
auditors:
- auditor_class: GitRepo
checkout_directory: <%= ENV["GITREPO_CHECKOUT_DIRECTORY"] %>
commit_message: <%= commit_message %>
git_name: GitRepoUser
git_email: gitrepousers@users.noreply
person_dn_format: uid=%KEY%,ou=People,dc=github,dc=net
repo: github/entitlements-config-auditlog
sshkey: '<%= sshkey %>'
<%- end -%>
```
At the end of each `entitlements-app` run, the `entitlements-gitrepo-auditor-plugin` will write a commit to the repo defined above with the details of the deployment.
## Release 🚀
To release a new version of this Gem, do the following:
1. Update the version number in the [`lib/version.rb`](lib/version.rb) file
2. Run `bundle install` to update the `Gemfile.lock` file with the new version
3. Commit your changes, push them to GitHub, and open a PR
Once your PR is approved and the changes are merged, a new release will be created automatically by the [`release.yml`](.github/workflows/gem.yml) workflow. The latest version of the Gem will be published to the GitHub Package Registry and RubyGems.