ci: answer the Scorecard report, and pin what the scanner cannot see

[donislawdev]

What this is

The first OpenSSF Scorecard report raised 16 findings on master. This closes the
five that are worth closing in the tree, answers four in writing, and leaves seven
to time or to arithmetic. The interesting half is what it does not do.

Fixed

release.yml grants write on the job, not on the file (Token-Permissions, high,
0/10). contents: write, id-token: write and attestations: write moved onto the
single release job; the file grants contents: read. ci.yml, pages.yml and
scorecard.yml already worked this way, so this was an inconsistency, not a
decision. It is not cosmetic while there is one job: a permission written at the top
is inherited by every job added later, by an author with no reason to scroll up, in
the one workflow that publishes under this project's name.

pip install --upgrade pip is gone from all five places it appeared. It fetched
an unpinned pip from the index and then used it to verify the artefact hashes on the
next line - the one unchecked link in a hash-checked chain. The pip that checks them
is now the one setup-python shipped, and that action is pinned by SHA.

requirements-lint.txt is hash-checked and holds its whole closure (13 packages:
ruff, mypy, diff-cover and the ten underneath them). Resolved with pip for
Python 3.14 and identical on manylinux2014_x86_64 and win_amd64, which is why no
line carries an environment marker.

requirements-scan.txt is new and is the one file here pinned by version and not
by bytes: semgrep and pip-audit. Reasoning is written in the file.

The tests job installs the lint file whole instead of grepping diff-cover out
of it. A hash cannot travel through a command substitution - grep hands pip a bare
pin and pip stays out of hash-checking mode.

The measurement behind it

🔴 Scorecard does not read workflow steps that run in a Windows shell. From its
source: "Skip unsupported shells. We don't support Windows shells". Three of the
five --upgrade pip lines were in windows-latest jobs, as were two
pip install -r requirements-lint.txt lines it never mentioned. It listed 8 of the
13 unpinned pip commands in this repository.

Fixing exactly what it named would have produced Pinned-Dependencies 10/10 with five
unpinned installs still in the tree. An alert list is a sample, not an inventory -
which is why the guard for this lives in the suite and not in the scanner.

Also read from source rather than assumed: --require-hashes is the only thing
that makes a pip command count as pinned (a version in the file does not), and the
flag cannot be added for show, because pip refuses the install without hashes behind
it.

Deliberately not done

• requirements-dev.txt stays unpinned. pytest, hypothesis and pytest-cov
  track latest on purpose - that drift is what the weekly run exists to see. Freezing
  them to satisfy a scanner trades a real signal for a number. Two alerts closed as
  won't-fix.
• Branch-Protection (4/10) cannot rise here. computeFinalScore returns early
  when a tier is not maxed, so the nine required status checks this repository
  already has (Tier 3) are never reached while Tier 2 (at least one approving review)
  is unmet - and nobody can approve their own pull request. Raising the approval count
  behind an admin bypass would move the number and make the rule theatre. Code-Review
  (0/29 approved) is the same wall from the other side.
• Fuzzing (0/10) is unreachable with the fuzzing already here. Scorecard
  recognises Python through exactly one pattern, import atheris in a *.py file.
  Property-based testing counts for six other languages and not for Python, so the
  hypothesis suites on the filter mini-language and the CLI are invisible to it.
• Maintained (0/10), SAST (9/10) and CI-Tests (9/10) are arithmetic. A repository
  younger than 90 days, and one pull request out of 29 predating those jobs. They
  close themselves.

Guards

Five checks in tests/test_version_and_release.py and four mutation-registry
entries, all four caught on the first run: the two requirement files each held to
its own promise, no workflow bootstrapping pip from the index, every install of a
hashed file passing --require-hashes, and no write permission at the file level in
release.yml.

Verification

• Full suite: 1201 passed. GUI smoke: OK. ruff --select F,B,C90: clean. mypy: clean.
• The lint file installed into a clean virtual environment under --require-hashes.
• The tests job's three install commands replayed in order, because pytest and the
  lint closure share pluggy.
• The regeneration command documented in the file was run, and returns the same 13
  packages.

Also in this branch

The first commit is unrelated to the above: a changelog line telling users they can
check where a download came from, which the previous change shipped without
announcing.

🤖 Generated with Claude Code