audit-labs/audit-tools

 1> **NOTE**: The PAT used across all scripts needs the following minimum permissions:
 2> - Repository: Actions (read), Contents (read), Metadata (read), Workflows (read)
 3> - Organization: Administration (read), Members (read), Webhooks (read)
 4> - Secret scanning and Dependabot alerts require GitHub Advanced Security and
 5>   the corresponding read permissions; they are skipped with a warning if
 6>   unavailable.
 7> - Audit log collection also requires GitHub Enterprise Cloud. Classic PATs need
 8>   `read:audit_log`; fine-grained tokens need Organization Administration (read).
 9
10---
11
12# `audit.py` — Unified GitHub Audit Tool
13
14Runs all collectors against a GitHub organization and writes a timestamped
15audit package to disk.
16
17## Setup
18
19```bash
20export GITHUB_TOKEN=your_token
21export GITHUB_ORG=your_organization
22```
23
24## Usage
25
26```bash
27# Basic run — uses GITHUB_TOKEN and GITHUB_ORG from environment
28python audit.py
29
30# Override org, set output directory
31python audit.py --org my-org --out ./output
32
33# Collect commits from a non-default branch
34python audit.py --branch develop
35```
36
37## Output
38
39Creates a directory: `<out>/github_audit_<org>_<YYYY-MM-DD>/`
40
41| File | Contents |
42|---|---|
43| `member_roster.csv` | All org members with role (owner vs member) |
44| `two_factor_disabled.csv` | Org members without 2FA enabled |
45| `outside_collaborators.csv` | Non-org members with direct repo access |
46| `privileged_access.csv` | All users with admin permission on any repo |
47| `pending_invitations.csv` | Invitations not yet accepted, with age in days |
48| `team_permissions.csv` | Teams, their repos, permissions, and members |
49| `permission_matrix.csv` | Full user/repo/permission cross-reference |
50| `branch_protections.csv` | Per-branch protection across all repos, from classic branch protection **and** rulesets (`protection_source` records which) |
51| `commits.csv` | Commit history across all repos for the target branch |
52| `org_security.csv` | Org security settings (2FA requirement, default permission, repo creation, secret scanning defaults) |
53| `webhooks.csv` | Org and per-repo webhooks, flagging plain-HTTP delivery and disabled SSL verification |
54| `deploy_keys.csv` | Deploy keys across all repos (read-only vs read-write, last used) |
55| `secret_scanning.csv` | Open secret-scanning alerts (Advanced Security) |
56| `dependabot_alerts.csv` | Open Dependabot alerts with severity (Advanced Security) |
57| `audit_log.csv` | Branch protection and repository ruleset audit-log changes from the last 180 days (Enterprise Cloud only) |
58| `summary.txt` | Row counts per section |
59
60`audit_log.csv` is collected by default. GitHub only returns audit-log events
61from the past three months unless the query includes a date filter, so this
62tool filters with `created:>=<180-days-ago>` to cover GitHub's 180-day audit-log
63retention window for non-Git events. If the organization or token cannot access
64the audit log, the tool prints a warning and continues with the other evidence.