diff --git a/Makefile b/Makefile index ea95f5d3..a662a85e 100644 --- a/Makefile +++ b/Makefile @@ -11,5 +11,11 @@ site-live: site-requirements.txt uvx --with-requirements $< mkdocs serve .PHONY: snippets -snippets: +snippets: trophies cargo run -- -h > docs/snippets/help.txt + +.PHONY: trophies +trophies: docs/snippets/trophies.md + +docs/snippets/trophies.md: docs/snippets/trophies.txt docs/snippets/render-trophies.py + uv run --no-project docs/snippets/render-trophies.py > $@ diff --git a/docs/development.md b/docs/development.md index ca76708c..054b1b31 100644 --- a/docs/development.md +++ b/docs/development.md @@ -167,6 +167,36 @@ INFO - [22:18:40] Browser connected: http://127.0.0.1:9999/zizmor/developmen Visit the listed URL to see your live changes. +### Updating the snippets + +`zizmor`'s website contains various static snippets. To update these: + +``` +make snippets +``` + +Most of the time, this should result in no changes, since the snippets +will already be up-to-date. + +### Updating the trophy case + +!!! tip + + Additions to the trophy case are welcome, but we currently limit them + to repositories with 100 or more "stars" to keep things tractable. + +The [Trophy Case](./trophy-case.md) is kept up-to-date through the data in +the `docs/snippets/trophies.txt` file. + +To add a new trophy to the trophy case, add it to that file *in the same +format* as the other entries. + +Then, regenerate the trophy case: + +``` +make trophies +``` + ## Adding or modifying an audit ### Before getting started @@ -245,11 +275,7 @@ The general procedure for changing an existing audit is: `zizmor`'s documentation contains a copy of `zizmor --help`, which the CI checks to ensure that it remains updated. If you change `zizmor`'s CLI, -you may need to regenerate the documentation snippets and check-in the results: - -```bash -make snippets -``` +you may need to [update the snippets](#updating-the-snippets). [clap]: https://docs.rs/clap/latest/clap/index.html diff --git a/docs/snippets/render-trophies.py b/docs/snippets/render-trophies.py new file mode 100644 index 00000000..38271614 --- /dev/null +++ b/docs/snippets/render-trophies.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python + +# render-trophies: take trophies.txt and produce a pretty +# mkdocs-material card grid list from it + +from pathlib import Path + + +_TROPHIES = Path(__file__).parent / "trophies.txt" + +_TEMPLATE = """ +- {{ width=\"40\" loading=lazy align=left }} {org}/{repo} + + --- + + {trophy}""" + +for trophy in sorted(_TROPHIES.open().readlines()): + trophy = trophy.strip() + if not trophy or trophy.startswith("#"): + continue + + org, rest = trophy.split("/") + repo, _ = rest.split("#") + # NOTE: We request 40x40 from GitHub, but sometimes it gives us a bigger one. + # Consequently, we also style with `width` to keep things consistent. + print(_TEMPLATE.format(org=org, repo=repo, trophy=trophy)) diff --git a/docs/snippets/trophies.md b/docs/snippets/trophies.md new file mode 100644 index 00000000..c7dfb03d --- /dev/null +++ b/docs/snippets/trophies.md @@ -0,0 +1,246 @@ + +- { width="40" loading=lazy align=left } DataDog/datadog-agent + + --- + + DataDog/datadog-agent#30871 + +- { width="40" loading=lazy align=left } Diaoul/subliminal + + --- + + Diaoul/subliminal#1190 + +- { width="40" loading=lazy align=left } Homebrew/brew + + --- + + Homebrew/brew#18662 + +- { width="40" loading=lazy align=left } NetApp/harvest + + --- + + NetApp/harvest#3247 + +- { width="40" loading=lazy align=left } PyO3/pyo3 + + --- + + PyO3/pyo3#4774 + +- { width="40" loading=lazy align=left } adafruit/circuitpython + + --- + + adafruit/circuitpython#9785 + +- { width="40" loading=lazy align=left } astral-sh/ruff + + --- + + astral-sh/ruff#14844 + +- { width="40" loading=lazy align=left } astropy/astropy + + --- + + astropy/astropy#17315 + +- { width="40" loading=lazy align=left } danmar/cppcheck + + --- + + danmar/cppcheck#7044 + +- { width="40" loading=lazy align=left } hugovk/em-keyboard + + --- + + hugovk/em-keyboard#148 + +- { width="40" loading=lazy align=left } hugovk/norwegianblue + + --- + + hugovk/norwegianblue#233 + +- { width="40" loading=lazy align=left } hugovk/pypistats + + --- + + hugovk/pypistats#460 + +- { width="40" loading=lazy align=left } hynek/argon2-cffi + + --- + + hynek/argon2-cffi#185 + +- { width="40" loading=lazy align=left } hynek/doc2dash + + --- + + hynek/doc2dash#225 + +- { width="40" loading=lazy align=left } hynek/environ-config + + --- + + hynek/environ-config#88 + +- { width="40" loading=lazy align=left } hynek/hatch-fancy-pypi-readme + + --- + + hynek/hatch-fancy-pypi-readme#57 + +- { width="40" loading=lazy align=left } hynek/pem + + --- + + hynek/pem#100 + +- { width="40" loading=lazy align=left } hynek/prometheus-async + + --- + + hynek/prometheus-async#70 + +- { width="40" loading=lazy align=left } hynek/stamina + + --- + + hynek/stamina#81 + +- { width="40" loading=lazy align=left } hynek/structlog + + --- + + hynek/structlog#663 + +- { width="40" loading=lazy align=left } marcusvolz/strava_py + + --- + + marcusvolz/strava_py#53 + +- { width="40" loading=lazy align=left } matplotlib/matplotlib + + --- + + matplotlib/matplotlib#29251 + +- { width="40" loading=lazy align=left } praetorian-inc/noseyparker + + --- + + praetorian-inc/noseyparker#228 + +- { width="40" loading=lazy align=left } prettytable/prettytable + + --- + + prettytable/prettytable#339 + +- { width="40" loading=lazy align=left } pyca/service-identity + + --- + + pyca/service-identity#75 + +- { width="40" loading=lazy align=left } pylast/pylast + + --- + + pylast/pylast#465 + +- { width="40" loading=lazy align=left } pypa/pip-audit + + --- + + pypa/pip-audit#851 + +- { width="40" loading=lazy align=left } python-attrs/attrs + + --- + + python-attrs/attrs#1368 + +- { width="40" loading=lazy align=left } python-attrs/cattrs + + --- + + python-attrs/cattrs#605 + +- { width="40" loading=lazy align=left } python-humanize/humanize + + --- + + python-humanize/humanize#221 + +- { width="40" loading=lazy align=left } python-pillow/Pillow + + --- + + python-pillow/Pillow#8526 + +- { width="40" loading=lazy align=left } python/cpython + + --- + + python/cpython#127749 + +- { width="40" loading=lazy align=left } python/miss-islington + + --- + + python/miss-islington#705 + +- { width="40" loading=lazy align=left } rust-lang/crates.io + + --- + + rust-lang/crates.io#10176 + +- { width="40" loading=lazy align=left } rustls/rustls + + --- + + rustls/rustls#2261 + +- { width="40" loading=lazy align=left } rustls/tokio-rustls + + --- + + rustls/tokio-rustls#96 + +- { width="40" loading=lazy align=left } sigstore/cosign + + --- + + sigstore/cosign#3959 + +- { width="40" loading=lazy align=left } sigstore/gitsign + + --- + + sigstore/gitsign#602 + +- { width="40" loading=lazy align=left } termcolor/termcolor + + --- + + termcolor/termcolor#89 + +- { width="40" loading=lazy align=left } tornadoweb/tornado + + --- + + tornadoweb/tornado#3438 + +- { width="40" loading=lazy align=left } vlang/v + + --- + + vlang/v#22681 diff --git a/docs/snippets/trophies.txt b/docs/snippets/trophies.txt new file mode 100644 index 00000000..514e1fa5 --- /dev/null +++ b/docs/snippets/trophies.txt @@ -0,0 +1,46 @@ +# one per line, order is not important +# trophies MUST be formatted as owner/repo#number, +# where owner/repo is the GitHub repo slug and +# number is the issue/PR that introduces or uses zizmor + +adafruit/circuitpython#9785 +astral-sh/ruff#14844 +astropy/astropy#17315 +danmar/cppcheck#7044 +DataDog/datadog-agent#30871 +Diaoul/subliminal#1190 +Homebrew/brew#18662 +hugovk/em-keyboard#148 +hugovk/norwegianblue#233 +hugovk/pypistats#460 +hynek/argon2-cffi#185 +hynek/doc2dash#225 +hynek/environ-config#88 +hynek/hatch-fancy-pypi-readme#57 +hynek/pem#100 +hynek/prometheus-async#70 +hynek/stamina#81 +hynek/structlog#663 +matplotlib/matplotlib#29251 +marcusvolz/strava_py#53 +NetApp/harvest#3247 +praetorian-inc/noseyparker#228 +prettytable/prettytable#339 +pyca/service-identity#75 +pylast/pylast#465 +pypa/pip-audit#851 +python/cpython#127749 +python/miss-islington#705 +python-attrs/attrs#1368 +python-attrs/cattrs#605 +python-humanize/humanize#221 +python-pillow/Pillow#8526 +PyO3/pyo3#4774 +rust-lang/crates.io#10176 +rustls/rustls#2261 +rustls/tokio-rustls#96 +sigstore/cosign#3959 +sigstore/gitsign#602 +termcolor/termcolor#89 +tornadoweb/tornado#3438 +vlang/v#22681 diff --git a/docs/trophy-case.md b/docs/trophy-case.md index e57f3292..8c659359 100644 --- a/docs/trophy-case.md +++ b/docs/trophy-case.md @@ -6,49 +6,13 @@ the software we all rely on. This page documents key examples where `zizmor` helped make big projects more secure! -!!! important +!!! tip "Give yourself a trophy!" Do you contribute to or maintain a big (>100 star) project that had its GitHub - Actions security improved by `zizmor`? Open a PR to add it to our list! + Actions security improved by `zizmor`? + [Add it to our list](./development.md#updating-the-trophy-case)! + +