audit-labs/audit-tools
A collection of scripts, queries, and other goodies you can use in an audit.
clone: git clone https://gitbay.org/audit-labs/audit-tools.git
1# Audit Tools — Interactive TUI
2
3A terminal UI that walks you through running an audit. It presents a platform
4menu, collects connection details and check selection, then runs the existing
5collectors with live progress.
6
7GitHub, GitLab, and AWS are supported. Adding a platform is a matter of writing
8a runner and a `Platform` descriptor in `tui/platforms.py` — the screens are
9platform-agnostic.
10
11| Pick a platform | Choose checks | Watch it run |
12|---|---|---|
13|  |  |  |
14
15## Run it
16
17```bash
18pip install ".[tui]" # textual + the AWS/GitHub/GitLab collector deps
19python audit_tui.py
20```
21
22The connection fields are pre-filled from environment variables if set:
23
24```bash
25# GitHub
26export GITHUB_ORG=my-org
27export GITHUB_TOKEN=ghp_... # needs read:org and repo scopes
28
29# GitLab
30export GITLAB_GROUP=my-group
31export GITLAB_TOKEN=glpat-... # needs read_api scope
32export GITLAB_URL=https://gitlab.example.com/api/v4 # self-hosted only
33
34# AWS (credentials come from the standard AWS chain, not a form field)
35export AWS_PROFILE=my-profile
36export AWS_DEFAULT_REGION=us-east-1
37export AWS_AUDIT_ACCOUNT=my-account # optional; only for the SSO check
38```
39
40AWS never asks for an access key in the UI — it uses your configured profile /
41credential chain (env vars, `~/.aws`, SSO). Read-only permissions are enough.
42
43## Walkthrough
44
451. **Platform** — choose GitHub or GitLab.
462. **Connection** — the audit subject (org / group), a masked token, and any
47 platform-specific fields (branch for GitHub; API base URL for GitLab).
483. **Checks** — toggle which checks to run. Plan-restricted checks (GitHub's
49 Enterprise audit log; GitLab's Premium and self-hosted checks) are off by
50 default.
514. **Run** — a progress bar and live log show each check completing with its row
52 count. Errors on a single check are reported without stopping the run.
53
54## Output
55
56The TUI writes the same package the platform's `audit.py` produces —
57`github_audit_<org>_<date>/`, `gitlab_audit_<group>_<date>/`, or
58`aws_audit_<profile>_<date>/` under the output directory — one CSV per check
59plus a `summary.txt`. It reuses each platform's collectors and CSV reporter
60unchanged; the TUI is only an interactive driver around them.
61
62## Keys
63
64- `Esc` — back / return to menu
65- `Ctrl+P` — command palette
66- `q` — quit (from the menu)
67
68## Tests
69
70```bash
71python -m pytest tui/tests
72```
73
74The tests stub the network-bound collectors, so they run offline: one suite
75covers the run orchestration, another drives the app headlessly through every
76screen.