From f82313b16107da17005f157763f148f6c93b8614 Mon Sep 17 00:00:00 2001 From: spydisec <9101327+spydisec@users.noreply.github.com> Date: Thu, 12 Nov 2026 02:23:08 +0000 Subject: [PATCH] docs: add a docs site for GitHub Pages site/build.sh builds the site with MkDocs Material from the README, docs/guide.md, docs/integrations/ and rules/README.md, so no page is written twice. The site also serves the get.sh of the latest release. The pages workflow builds the site on a pull request and publishes it from main. The release workflow starts a run after each release. Co-Authored-By: Claude Fable 5.2 --- .github/dependabot.yml | 6 +++ .github/workflows/pages.yml | 78 +++++++++++++++++++++++++++++++++++ .github/workflows/release.yml | 6 +++ .gitignore | 3 ++ scripts/dev/ci-changes.bash | 2 + site/build.sh | 45 ++++++++++++++++++++ site/mkdocs.yml | 49 ++++++++++++++++++++++ site/requirements.txt | 2 + tests/bats/ci-changes.bats | 9 ++++ 9 files changed, 200 insertions(+) create mode 100644 .github/workflows/pages.yml create mode 100644 site/build.sh create mode 100644 site/mkdocs.yml create mode 100644 site/requirements.txt diff --git a/.github/dependabot.yml b/.github/dependabot.yml index ed6d310..92ae2ba 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -13,3 +13,9 @@ updates: default-days: 7 schedule: interval: weekly + - package-ecosystem: pip + directory: /site + cooldown: + default-days: 7 + schedule: + interval: weekly diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..0a89a08 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,78 @@ +--- +name: pages + +# Builds the docs site from the Markdown files and publishes it to GitHub Pages. A pull request +# only builds it. The release workflow starts a run, so the site serves the new get.sh. +on: + push: + branches: [main] + paths: + - README.md + - docs/guide.md + - docs/integrations/** + - rules/README.md + - site/** + - .github/workflows/pages.yml + pull_request: + paths: + - README.md + - docs/guide.md + - docs/integrations/** + - rules/README.md + - site/** + - .github/workflows/pages.yml + workflow_dispatch: + +permissions: {} + +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.12" + - name: Install tools + run: | + python -m venv .venv + .venv/bin/pip install -r site/requirements.txt + echo "$PWD/.venv/bin" >> "$GITHUB_PATH" + # The site serves the get.sh of the latest release, not the one on main. + - name: Download the released get.sh + env: + GH_TOKEN: ${{ github.token }} + run: | + mkdir release + gh release download --dir release --pattern get.sh --pattern SHA256SUMS + (cd release && grep ' get\.sh$' SHA256SUMS | sha256sum -c -) + - name: Build + run: sh site/build.sh _site release/get.sh + - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + if: github.event_name != 'pull_request' + with: + path: _site + + deploy: + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + steps: + - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 + id: deploy diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 519085d..f4aa62e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,6 +22,7 @@ jobs: contents: write id-token: write attestations: write + actions: write steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -60,3 +61,8 @@ jobs: run: | gh release create "v$VERSION" dist/* --target "$GITHUB_SHA" --title "v$VERSION" \ --generate-notes + # The docs site serves the newest get.sh, so build it again. + - name: Update the docs site + env: + GH_TOKEN: ${{ github.token }} + run: gh workflow run pages.yml --ref main diff --git a/.gitignore b/.gitignore index f639757..9d7afe6 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ dist/ # yamllint settings are in tests/lint.sh. .yamllint.yml + +# Pages that site/build.sh copies before it runs mkdocs. +site/.build/ diff --git a/scripts/dev/ci-changes.bash b/scripts/dev/ci-changes.bash index 42175a1..ad3c9d8 100644 --- a/scripts/dev/ci-changes.bash +++ b/scripts/dev/ci-changes.bash @@ -29,6 +29,8 @@ else ;; tests/lint.sh) lint=true ;; + site/*) + lint=true ;; tests/ci/real-kernel.sh | tests/ci/container-install.sh | tests/ci/vm-run.sh) lint=true; runtime=true ;; tests/bats/* | tests/fixtures/*) diff --git a/site/build.sh b/site/build.sh new file mode 100644 index 0000000..38ea694 --- /dev/null +++ b/site/build.sh @@ -0,0 +1,45 @@ +#!/bin/sh +# Build the docs site from the Markdown files in the repo. +# +# Usage: build.sh [get.sh] +# +# The pages are the README, docs/guide.md, docs/integrations/, and rules/README.md. The links +# between them are rewritten for the site, and links to other repo files point to GitHub. With a +# second argument, that file is served as /get.sh. +set -eu + +repo=$(CDPATH='' cd -- "$(dirname -- "$0")/.." >/dev/null && pwd) +blob=https://github.com/spydisec/auditd-kit/blob/main +tree=https://github.com/spydisec/auditd-kit/tree/main + +[ $# -ge 1 ] && [ $# -le 2 ] || { + echo "usage: build.sh [get.sh]" >&2 + exit 1 +} +mkdir -p "$1" +out=$(cd "$1" && pwd) + +src=$repo/site/.build +rm -rf "$src" +mkdir -p "$src/integrations" + +sed -e 's|](docs/adr/)|]('"$tree"'/docs/adr)|g' \ + -e 's|](docs/|](|g' \ + -e 's|](rules/README\.md|](rules.md|g' \ + -e 's|](\([A-Z][A-Z-]*\.md\))|]('"$blob"'/\1)|g' \ + -e 's|](LICENSE)|]('"$blob"'/LICENSE)|g' \ + "$repo/README.md" >"$src/index.md" + +sed -e 's|](\.\./rules/README\.md|](rules.md|g' \ + -e 's|](\.\./scripts/|]('"$blob"'/scripts/|g' \ + -e 's|](adr/|]('"$blob"'/docs/adr/|g' \ + "$repo/docs/guide.md" >"$src/guide.md" + +cp "$repo/rules/README.md" "$src/rules.md" +cp "$repo"/docs/integrations/*.md "$src/integrations/" + +if [ $# -eq 2 ]; then + cp "$2" "$src/get.sh" +fi + +mkdocs build --strict -f "$repo/site/mkdocs.yml" -d "$out" diff --git a/site/mkdocs.yml b/site/mkdocs.yml new file mode 100644 index 0000000..64f2e34 --- /dev/null +++ b/site/mkdocs.yml @@ -0,0 +1,49 @@ +--- +# Settings for the docs site. site/build.sh copies the pages into .build/ and runs mkdocs. +site_name: auditd-kit +site_description: Install a tested set of Linux audit rules (auditd) with one command. +repo_url: https://github.com/spydisec/auditd-kit +repo_name: spydisec/auditd-kit +edit_uri: "" +docs_dir: .build +copyright: Apache-2.0 + +theme: + name: material + font: false + features: + - content.code.copy + - navigation.sections + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-night + name: Dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-sunny + name: Light mode + +markdown_extensions: + - tables + - toc: + permalink: true + - pymdownx.highlight + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + +nav: + - Install: index.md + - Guide: guide.md + - Rules: rules.md + - Send events to a SIEM: + - Overview: integrations/send-audit-log.md + - Wazuh: integrations/wazuh.md + - Microsoft Sentinel: integrations/azure-ama.md + - syslog-ng: integrations/syslog-ng.md diff --git a/site/requirements.txt b/site/requirements.txt new file mode 100644 index 0000000..bca19f0 --- /dev/null +++ b/site/requirements.txt @@ -0,0 +1,2 @@ +# Exact version pin for the docs site. Dependabot updates it. +mkdocs-material==9.8.1 diff --git a/tests/bats/ci-changes.bats b/tests/bats/ci-changes.bats index e893601..314ae54 100644 --- a/tests/bats/ci-changes.bats +++ b/tests/bats/ci-changes.bats @@ -78,6 +78,15 @@ route() { [[ "$output" == *"runtime=false"* ]] } +@test "docs site files select lint only" { + run route site/build.sh site/mkdocs.yml site/requirements.txt + [ "$status" -eq 0 ] + [[ "$output" == *"lint=true"* ]] + [[ "$output" == *"bats=false"* ]] + [[ "$output" == *"runtime=false"* ]] + [[ "$output" == *"packaging=false"* ]] +} + @test "YAML extensions select lint outside known directories" { run route new/settings.yaml .github/ISSUE_TEMPLATE/bug.yml [[ "$output" == *"lint=true"* ]]