* Audit Tools

*Audit Tools* is a collection of open-source Python scripts and related resources
intended to support auditors, risk professionals, and data analysts in
automating common audit procedures and analyses.

This repository includes practical examples that can be used as-is or adapted to
specific audit environments.

It also ships an interactive terminal UI (=audit_tui.py=) that walks you through
running an audit against GitHub, GitLab, or AWS — pick a platform, enter
connection details, choose which checks to run, and watch live progress.

[[./docs/screenshots/menu.png]]

** Contents

| Directory            | Description                                                                  |
|----------------------+------------------------------------------------------------------------------|
| =applications/aws/=    | AWS IAM users, account/root security, password policy, S3 public access, open security groups, CloudTrail, Config, SSO |
| =applications/github/= | GitHub admin enumeration, org security settings, webhooks, deploy keys, secret-scanning/Dependabot alerts, audit log, branch protections, commits |
| =applications/gitlab/= | GitLab group/project members, branch protections, approvals, pipelines, audit events |
| =databases/mongo/=     | MongoDB admin enumeration                                                    |
| =databases/mysql/=     | MySQL admin and password queries                                             |
| =databases/oracle/=    | Oracle admin queries                                                         |
| =databases/postgres/=  | PostgreSQL admin and password queries                                        |
| =databases/sql/=       | Generic SQL admin queries and password analysis                              |
| =os/linux/=            | Linux OS reporting, password file analysis, and SSH root login checks        |
| =project_management/=  | Audit project tracking dashboards (Alteryx, Dash, Power BI)                  |
| =sampling/=            | Random and stratified sampling tools                                         |
| =tui/=                 | Interactive terminal UI that walks you through running an audit              |

** Getting Started

*Clone the Repository*

#+begin_src bash
git clone https://github.com/audit-labs/audit-tools
cd audit-tools
#+end_src

#+RESULTS:

*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 ".[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:

#+begin_src bash
./os/linux/report/linux.sh
#+end_src

Or to run a Python script:

#+begin_src bash
python sampling/sample.py
#+end_src

Output will be shown in the terminal or saved to a file, depending on the
script.

*Interactive TUI*

To pick a platform and be walked through an audit interactively:

#+begin_src bash
python audit_tui.py
#+end_src

Each run writes the same package the platform's =audit.py= produces — one CSV per
check plus a summary — with a progress bar and per-check results:

[[./docs/screenshots/run.png]]

See =tui/README.md= for details. GitHub, GitLab, and AWS are supported.

** Stability

*Audit Tools* is stable as of *v1.0.0*. It is a curated collection of runnable
scripts and an interactive TUI rather than an importable library, so each release
is tagged to give an engagement an exact revision to pin to.

** Contributing

Contributions are welcome. You can contribute by:

- Adding new audit-related scripts
- Suggesting improvements or feature ideas
- Enhancing documentation
- Testing the tools on additional datasets and reporting any issues

To contribute:

1. Fork the repository
2. Create a new branch:
   #+begin_src bash
   git checkout -b my-feature
   #+end_src
3. Commit your changes:
   #+begin_src bash
   git commit -m 'Added new audit test'
   #+end_src
4. Push your branch:
   #+begin_src bash
   git push origin my-feature
   #+end_src
5. Open a pull request