gh-audit 0.1.2

GitHub audit, governance, and inventory for organizations

gh-audit

GitHub audit, governance, and inventory for organizations.

gh-audit produces a comprehensive inventory of your GitHub organization -- repositories, members, Actions workflows, security posture, packages, and projects -- and generates JSON, HTML, and Excel reports. It supports standard (fast) and deep (thorough) scan profiles, multi-organization scanning via YAML config, and both PAT and GitHub App authentication.

A free tool by N8 Group -- DevOps Transformation. Executed with Precision.

Installation

pip (Python 3.11+)

pip install gh-audit
gh-audit --version

Homebrew (macOS / Linux)

brew tap n8group-oss/tap
brew install gh-audit

Chocolatey (Windows)

choco install gh-audit --source="https://github.com/n8group-oss/gh-audit/releases"

Direct download

Download standalone binaries from GitHub Releases. Available for Linux (amd64), macOS (amd64, arm64), and Windows (amd64).

Quick Start

Single organization (PAT)

gh-audit discover --organization myorg --token ghp_xxxxx

Single organization (GitHub App -- recommended)

gh-audit discover \
  --organization myorg \
  --app-id 12345 \
  --private-key-path /path/to/key.pem \
  --installation-id 67890

Multi-organization (config file)

gh-audit discover --config gh-audit.yml --output-dir ./results

See examples/gh-audit.yml for the config format.

Interactive setup

gh-audit init

Creates a .env file with your credentials. Then run:

gh-audit discover

Scan Profiles

Profile	Default	What it does
standard	Yes	Repository metadata, PR/issue/branch counts, workflow listing, security feature status, users, packages, projects
deep	No	Everything in standard + recursive tree walk (large file detection), workflow YAML parsing (action usage, self-hosted runners), exact security alert counts

gh-audit discover --organization myorg --token ghp_xxx --scan-profile deep

Individual deep features can be toggled independently:

gh-audit discover --organization myorg --token ghp_xxx \
  --scan-large-files \
  --scan-workflow-contents \
  --security-alert-counts

Output

Every scan produces three artifacts:

Format	File	Purpose
JSON	{org}-inventory.json	Machine-readable inventory
HTML	{org}-report.html	Self-contained visual report (offline, no CDN)
Excel	{org}-inventory.xlsx	10-sheet workbook for analysis and sharing

Regenerate reports from an existing inventory:

gh-audit report --inventory myorg-inventory.json

Authentication

Personal Access Token (PAT)

Required scopes (classic): repo, read:org, read:packages, read:project, security_events

Set via CLI flag, environment variable, or .env file:

export GH_AUDIT_TOKEN=ghp_xxxxx
export GH_AUDIT_ORGANIZATION=myorg

GitHub App (recommended)

Better rate limits (15,000 req/hr vs 5,000) and org-level permissions.

Required permissions: Repository metadata (read), Organization members (read), Actions (read), Packages (read), Security events (read).

export GH_AUDIT_APP_ID=12345
export GH_AUDIT_PRIVATE_KEY_PATH=/path/to/key.pem
export GH_AUDIT_INSTALLATION_ID=67890
export GH_AUDIT_ORGANIZATION=myorg

GitHub Enterprise Server

export GH_AUDIT_API_URL=https://github.mycompany.com/api/v3

Multi-Organization Config

Scan multiple organizations with different credentials in one run:

defaults:
  scan_profile: standard
  concurrency: 8

organizations:
  - name: org-one
    token: ${GH_TOKEN_ORG_ONE}

  - name: org-two
    app_id: 12345
    private_key_path: /path/to/key.pem
    installation_id: 67890
    scan_profile: deep

gh-audit discover --config gh-audit.yml --output-dir ./results

Each organization gets its own output directory. A cross-org summary (summary.json + summary.html) is generated at the root.

License

Business Source License 1.1 -- free to use for internal purposes. See LICENSE for full terms.

Contact

N8 Group -- European leader in AI-powered DevOps solutions.

• Web: n8-group.com
• Email: [e-mail]
• LinkedIn: N8 Group
• Phone: [phone]