audit-labs/audit-report

 1# Example GitHub Actions workflow: collect evidence, then report on it.
 2#
 3# Copy into .github/workflows/audit.yml in a repository owned by the org you
 4# want to audit and adjust as needed. It runs on a schedule and on demand,
 5# produces a control-mapped report, and fails the run if any high-severity
 6# control is unsupported.
 7#
 8# audit-tools is not published to PyPI — it is a set of per-platform scripts, so
 9# this checks the repo out and runs applications/github/audit.py directly.
10# audit-report *is* pip-installable from git.
11#
12# Required repository/org secret:
13#   AUDIT_GITHUB_TOKEN  a read-only token with org + security-events scope
14# Required variable (Settings > Variables), or hard-code below:
15#   AUDIT_ORG           the organization login to audit
16
17name: compliance-evidence
18
19on:
20  schedule:
21    - cron: "0 6 * * 1" # every Monday 06:00 UTC
22  workflow_dispatch: {}
23
24permissions:
25  contents: read
26
27jobs:
28  audit:
29    runs-on: ubuntu-latest
30    steps:
31      - name: Check out audit-tools (the collector)
32        uses: actions/checkout@v4
33        with:
34          repository: audit-labs/audit-tools
35          path: audit-tools
36
37      - uses: actions/setup-python@v5
38        with:
39          python-version: "3.12"
40
41      - name: Install collector deps and the reporter
42        run: |
43          python -m pip install --upgrade pip
44          pip install -r audit-tools/requirements.txt
45          pip install "audit-report @ git+https://github.com/audit-labs/audit-report"
46
47      - name: Collect GitHub evidence
48        env:
49          GITHUB_TOKEN: ${{ secrets.AUDIT_GITHUB_TOKEN }}
50          GITHUB_ORG: ${{ vars.AUDIT_ORG }}
51        run: |
52          # Writes $GITHUB_WORKSPACE/output/github_audit_<org>_<date>/
53          python audit-tools/applications/github/audit.py \
54            --org "$GITHUB_ORG" --out "$GITHUB_WORKSPACE/output"
55
56      - name: Locate the newest package
57        id: pkg
58        run: echo "dir=$(ls -d "$GITHUB_WORKSPACE"/output/*_audit_* | sort | tail -n1)" >> "$GITHUB_OUTPUT"
59
60      - name: Generate evidence report
61        run: |
62          audit-report "${{ steps.pkg.outputs.dir }}" \
63            --format md,html,json --out ./report
64
65      - name: Fail on any high-severity finding
66        run: audit-report "${{ steps.pkg.outputs.dir }}" --fail-on high
67
68      - name: Publish the report as a build artifact
69        if: always()
70        uses: actions/upload-artifact@v4
71        with:
72          name: evidence-report
73          path: report/
74          retention-days: 90