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
f4be2a04d68a34f12de244932b8fd7e6dcf7a822
verified · cmc
author: Christian Cleberg <hello@cleberg.net> · 2026-08-07T02:20:23Z
README.org | 12 +++++++++++- applications/aws/README.md | 4 ++-- pyproject.toml | 46 ++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 27 ++++++++++++++------------- sampling/README.md | 4 ++-- tui/README.md | 2 +- 6 files changed, 76 insertions(+), 19 deletions(-) @@ -43,10 +43,20 @@ cd audit-tools *Install Dependencies* +Dependencies are optional /extras/, so you install only what a procedure needs +(a locked-down laptop never has to pull pandas/dash/plotly it won't run): + #+begin_src bash -pip install -r requirements.txt +pip install ".[analysis]" # sampling + data analysis (pandas, Excel) +pip install ".[aws]" # AWS collectors (boto3) +pip install ".[collectors]" # GitHub / GitLab collectors (requests) +pip install ".[dashboards]" # dash + plotly dashboards +pip install ".[tui]" # the terminal UI runner +pip install ".[all]" # everything #+end_src +=~pip install -r requirements.txt~= still works and installs everything. + *Run a Script* For example, to run the Linux OS report tool: @@ -25,8 +25,8 @@ export AWS_AUDIT_ACCOUNT=my-account # optional; only for the SSO check If you authenticate with `aws login` / IAM Identity Center (SSO), those credentials use the AWS Common Runtime provider, which needs the `crt` extra. -It is included via `botocore[crt]` in `requirements.txt`; if you installed -boto3 separately, run `pip install "botocore[crt]"`. Without it you'll see +It is included via `botocore[crt]` in the `aws` extra (`pip install ".[aws]"`); +if you installed boto3 separately, run `pip install "botocore[crt]"`. Without it you'll see `MissingDependencyException: ... requires an additional dependency`. ## Usage new file mode 100644 @@ -0,0 +1,46 @@ +[build-system] +requires = ["setuptools>=77"] +build-backend = "setuptools.build_meta" + +[project] +name = "audit-tools" +version = "0.1.0" +description = "Scripts for programmatically gathering IT audit evidence from cloud, source control, databases, and operating systems." +readme = { file = "README.org", content-type = "text/plain" } +requires-python = ">=3.10" +license = "GPL-3.0-or-later" +authors = [{ name = "Christian Cleberg", email = "hello@cleberg.net" }] +keywords = ["audit", "compliance", "evidence", "ITGC", "SOC2", "ISO27001"] + +# The core is deliberately empty: many collectors are shell scripts or use only +# the standard library. Install just the extras a given procedure needs, so a +# locked-down auditing laptop never pulls pandas/dash/plotly it will not run. +dependencies = [] + +[project.optional-dependencies] +# Sampling and data analysis (CSV + Excel wrangling). +analysis = ["pandas", "openpyxl", "xlrd", "PyYAML"] +# Interactive dashboards for project / findings data. +dashboards = ["dash", "plotly", "Werkzeug>=3.1.8"] +# AWS evidence collectors. +aws = ["boto3", "botocore[crt]", "urllib3>=2.7.0"] +# GitHub / GitLab REST collectors. +collectors = ["requests", "urllib3>=2.7.0"] +# MongoDB user / access collectors. +mongo = ["pymongo"] +# Terminal UI that drives the collectors. +tui = ["audit-tools[aws,collectors]", "textual"] +# Everything, for a full local install. +all = ["audit-tools[analysis,dashboards,aws,collectors,mongo,tui]"] +# Development: linting and tests. +dev = ["audit-tools[all]", "pytest", "ruff"] + +[project.urls] +Homepage = "https://audit-labs.dev" +Repository = "https://github.com/audit-labs/audit-tools" + +# This repo is a runnable script collection, not an importable library. Declare +# no modules so `pip install .` provisions dependencies (via extras) without +# trying to package the top-level scripts. +[tool.setuptools] +py-modules = [] @@ -1,13 +1,14 @@ -pandas -openpyxl -xlrd -PyYAML -pytest -requests -boto3 -botocore[crt] -textual -dash -plotly -urllib3>=2.7.0 -Werkzeug>=3.1.8 +# Dependencies are declared in pyproject.toml as optional "extras", so you only +# install what a given procedure needs. Installing this file pulls EVERYTHING. +# +# Lighter, targeted installs (run from the repo root): +# pip install ".[analysis]" # sampling + data analysis (pandas, Excel) +# pip install ".[dashboards]" # dash + plotly dashboards +# pip install ".[aws]" # AWS collectors (boto3) +# pip install ".[collectors]" # GitHub / GitLab collectors (requests) +# pip install ".[mongo]" # MongoDB collectors (pymongo) +# pip install ".[tui]" # the terminal UI runner +# pip install ".[dev]" # everything + pytest + ruff +# +# Full install (all optional features): +.[all] @@ -13,10 +13,10 @@ audit workpaper package. ## Installation -Install the repository requirements: +Sampling needs only the `analysis` extra (pandas + Excel support): ```bash -pip install -r requirements.txt +pip install ".[analysis]" ``` Supported input formats are `.csv`, `.xlsx`, `.xls`, and `.xlsm`. @@ -15,7 +15,7 @@ platform-agnostic. ## Run it ```bash -pip install -r requirements.txt +pip install ".[tui]" # textual + the AWS/GitHub/GitLab collector deps python audit_tui.py ```