audit-labs/audit-report
Turn audit-tools evidence packages into control-mapped, auditor-ready reports.
clone: git clone https://gitbay.org/audit-labs/audit-report.git
250db1702432770222690977496980122a4318de
verified · cmc
author: Christian Cleberg <hello@cleberg.net> · 2026-08-06T07:32:35Z
docs/ci.md | 27 +++++++++++++++++++++---- examples/github-actions-audit.yml | 42 +++++++++++++++++++++++---------------- examples/gitlab-ci-audit.yml | 31 ++++++++++++++++++++--------- 3 files changed, 70 insertions(+), 30 deletions(-) @@ -12,10 +12,29 @@ Ready-to-copy starting points: - [`examples/github-actions-audit.yml`](../examples/github-actions-audit.yml) - [`examples/gitlab-ci-audit.yml`](../examples/gitlab-ci-audit.yml) -> The collection step in the examples shows both a module entrypoint -> (`python -m audit_tools.github`) and a script fallback (`python audit.py`). -> Use whichever your installed `audit-tools` exposes; everything downstream only -> needs the `./output/<platform>_audit_<subject>_<date>/` directory it writes. +> `audit-tools` is not on PyPI — it is a set of per-platform scripts. Check the +> repo out (or clone it) and run `applications/<platform>/audit.py` directly; +> Python puts the script's own directory on `sys.path`, so no `cd` is needed. +> Pass an absolute `--out` so every platform's package lands in one folder. +> Everything downstream only needs the +> `<out>/<platform>_audit_<subject>_<date>/` directory it writes. + +## Exact collection commands + +Install `audit-tools`' dependencies once (`pip install -r audit-tools/requirements.txt`), +export the platform's credentials, then: + +```bash +# AWS — credentials come from the standard AWS chain (env vars, profile, OIDC role) +python audit-tools/applications/aws/audit.py --out "$PWD/output" + +# GitHub — needs GITHUB_TOKEN (read-only) in the environment +python audit-tools/applications/github/audit.py --org "$ORG" --out "$PWD/output" + +# GitLab — needs GITLAB_TOKEN (read_api) in the environment +python audit-tools/applications/gitlab/audit.py \ + --group "$GROUP" --url "$API_V4_URL" --out "$PWD/output" +``` ## Gating strategies @@ -1,12 +1,18 @@ # Example GitHub Actions workflow: collect evidence, then report on it. # -# Copy into .github/workflows/audit.yml in the repository you want to audit and -# adjust the collection step to your platform. It runs on a schedule and on -# demand, produces a control-mapped report, and fails the run if a high-severity -# control regresses against the previous package committed to the repo. +# Copy into .github/workflows/audit.yml in a repository owned by the org you +# want to audit and adjust as needed. It runs on a schedule and on demand, +# produces a control-mapped report, and fails the run if any high-severity +# control is unsupported. # -# Requires two org/repo secrets for the GitHub collector: AUDIT_GITHUB_TOKEN -# (a read-only token for the org you audit) and the org name in AUDIT_ORG. +# audit-tools is not published to PyPI — it is a set of per-platform scripts, so +# this checks the repo out and runs applications/github/audit.py directly. +# audit-report *is* pip-installable from git. +# +# Required repository/org secret: +# AUDIT_GITHUB_TOKEN a read-only token with org + security-events scope +# Required variable (Settings > Variables), or hard-code below: +# AUDIT_ORG the organization login to audit name: compliance-evidence @@ -22,32 +28,34 @@ jobs: audit: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Check out audit-tools (the collector) + uses: actions/checkout@v4 + with: + repository: audit-labs/audit-tools + path: audit-tools - uses: actions/setup-python@v5 with: python-version: "3.12" - - name: Install tools + - name: Install collector deps and the reporter run: | python -m pip install --upgrade pip - # The reporter: + pip install -r audit-tools/requirements.txt pip install "audit-report @ git+https://github.com/audit-labs/audit-report" - # The collector (audit-tools ships CLIs per platform): - pip install "audit-tools @ git+https://github.com/audit-labs/audit-tools" - - name: Collect evidence (GitHub example) + - name: Collect GitHub evidence env: GITHUB_TOKEN: ${{ secrets.AUDIT_GITHUB_TOKEN }} - GITHUB_ORG: ${{ secrets.AUDIT_ORG }} + GITHUB_ORG: ${{ vars.AUDIT_ORG }} run: | - # Produces ./output/github_audit_<org>_<date>/ - python -m audit_tools.github --out ./output || \ - python audit.py --out ./output # fall back to the script entrypoint + # Writes $GITHUB_WORKSPACE/output/github_audit_<org>_<date>/ + python audit-tools/applications/github/audit.py \ + --org "$GITHUB_ORG" --out "$GITHUB_WORKSPACE/output" - name: Locate the newest package id: pkg - run: echo "dir=$(ls -d ./output/*_audit_* | sort | tail -n1)" >> "$GITHUB_OUTPUT" + run: echo "dir=$(ls -d "$GITHUB_WORKSPACE"/output/*_audit_* | sort | tail -n1)" >> "$GITHUB_OUTPUT" - name: Generate evidence report run: | @@ -1,11 +1,17 @@ # Example GitLab CI configuration: collect evidence, then report on it. # -# Copy into .gitlab-ci.yml (or include it) in the project you want to audit. -# It produces a control-mapped report as a job artifact and fails the pipeline -# if any high-severity control is not supported. +# Copy into .gitlab-ci.yml (or `include:` it) in a project under the group you +# want to audit. It produces a control-mapped report as a job artifact and fails +# the pipeline if any high-severity control is unsupported. # -# Set CI/CD variables GITLAB_TOKEN (read-only) and GITLAB_GROUP for the group -# you audit. +# audit-tools is not published to PyPI — it is a set of per-platform scripts, so +# this clones the repo and runs applications/gitlab/audit.py directly. +# audit-report *is* pip-installable from git. +# +# Required CI/CD variable (Settings > CI/CD > Variables): +# GITLAB_TOKEN a token with read_api scope for the group +# GITLAB_GROUP defaults to this project's top-level group and the API URL to the +# instance running the pipeline, so it audits "where it lives" out of the box. stages: [audit] @@ -17,13 +23,20 @@ compliance-evidence: - if: $CI_PIPELINE_SOURCE == "web" # manual "Run pipeline" variables: PIP_DISABLE_PIP_VERSION_CHECK: "1" + GITLAB_GROUP: $CI_PROJECT_ROOT_NAMESPACE before_script: + - apt-get update && apt-get install -y --no-install-recommends git + - git clone --depth 1 https://github.com/audit-labs/audit-tools.git + - pip install -r audit-tools/requirements.txt - pip install "audit-report @ git+https://github.com/audit-labs/audit-report" - - pip install "audit-tools @ git+https://github.com/audit-labs/audit-tools" script: - # Produces ./output/gitlab_audit_<group>_<date>/ - - python -m audit_tools.gitlab --out ./output || python audit.py --out ./output - - PKG=$(ls -d ./output/*_audit_* | sort | tail -n1) + # Writes $CI_PROJECT_DIR/output/gitlab_audit_<group>_<date>/ against this + # instance's API ($CI_API_V4_URL is provided automatically by GitLab). + - > + python audit-tools/applications/gitlab/audit.py + --group "$GITLAB_GROUP" --url "$CI_API_V4_URL" + --out "$CI_PROJECT_DIR/output" + - PKG=$(ls -d "$CI_PROJECT_DIR"/output/*_audit_* | sort | tail -n1) - audit-report "$PKG" --format md,html,json --out ./report - audit-report "$PKG" --fail-on high artifacts: