audit-labs/audit-tools

 1> **NOTE**: The token used across all collectors needs at least the `read_api`
 2> scope. Some checks need more:
 3> - **Approval rules** and **audit events** require a GitLab Premium or Ultimate
 4>   subscription.
 5> - **Password policy** reads instance application settings, which require an
 6>   admin token on a self-hosted instance (not available on GitLab.com).
 7>
 8> Checks that are unavailable are skipped with a warning; the rest still run.
 9
10---
11
12# `audit.py` — Unified GitLab Audit Tool
13
14Runs all collectors against a GitLab group (including its subgroups) and writes
15a timestamped audit package to disk.
16
17## Setup
18
19```bash
20export GITLAB_TOKEN=your_token
21export GITLAB_GROUP=your_group_id_or_path
22# Self-hosted only:
23export GITLAB_URL=https://gitlab.example.com/api/v4
24```
25
26## Usage
27
28```bash
29# Basic run — uses GITLAB_TOKEN and GITLAB_GROUP from environment
30python audit.py
31
32# Override group, set output directory
33python audit.py --group my-group --out ./output
34
35# Point at a self-hosted instance
36python audit.py --url https://gitlab.example.com/api/v4
37```
38
39The group may be a numeric ID (`1234567`) or a URL path (`my-group/sub-group`).
40
41## Output
42
43Creates a directory: `<out>/gitlab_audit_<group>_<YYYY-MM-DD>/`
44
45| File | Contents |
46|---|---|
47| `group_members.csv` | Group members with access level and role |
48| `projects.csv` | All projects in the group and subgroups |
49| `project_members.csv` | Members and access levels for every project |
50| `branch_protections.csv` | Protected-branch settings across all projects |
51| `pipelines.csv` | CI/CD pipeline history across all projects |
52| `approval_rules.csv` | Merge-request approval rules (Premium/Ultimate) |
53| `audit_events.csv` | Group membership audit events (Premium/Ultimate) |
54| `password_policy.csv` | Instance password policy (self-hosted, admin token) |
55| `summary.txt` | Row counts per section |
56
57The per-project checks reuse a single enumeration of the group's projects, so
58the group is listed only once per run.