Skip to content

ADR-0015: The security baseline is nine named controls, each either failing the build or only reporting, with evidence per release

Status: accepted (2026-10-28) · Scope: CI, the release job and repository settings of pykit

Decision

pykit's baseline is these controls, all on free tooling for public repositories. "Fails" means a finding stops CI or the release; "reports" means the result is recorded and never blocks.

Control Tool Effect
Dependency audit pip-audit over uv export --frozen of uv.lock Fails on a known vulnerability; an ignore needs a written reason
Licence inventory pip-licenses over the locked environment Fails on GPL, AGPL, SSPL or an unknown licence; otherwise reports the inventory
Source scan ruff's S rules (Bandit's checks, including the Django ones) over packages/ Fails
Secret scan gitleaks over the full history Fails
Push protection GitHub secret scanning push protection, enabled by the owner Blocks the push; not in CI
SBOM cyclonedx-py (CycloneDX JSON), one per package tag Reports; the release fails if it cannot be generated
Attestation actions/attest-build-provenance on the built files, and PEP 740 attestations from pypi-attestations, uploaded by uv publish (E21) The release fails if either cannot be produced
SECURITY.md GitHub private vulnerability reporting as the channel Reports
Scorecard OpenSSF Scorecard action, SARIF to code scanning Reports; no threshold

Dependabot watches uv as well as github-actions. Evidence lives beside each release, in docs/releases/release-<n>/, and lists every control's result at the cut.

A consumer verifies the PyPI files or the GitHub Release files. A git+…@<tag> build from source is not covered, and the guide steers consumers to PyPI. Tags are not signed.

The baseline claims that each release was scanned by these controls, with the results published. It does not claim that pykit is secure, certified or free of unknown vulnerabilities, nor that a passing Scorecard means safety. Auth-specific security tests (denied paths, privilege boundaries, token expiry) and the auth threat model stay in E13.

Consequences

  • A new vulnerability in a locked dependency can fail an unrelated change until the lock moves or the finding is ignored with a reason.
  • The licence deny list is maintained by hand.
  • Ruff's S rules cover fewer Django patterns than Semgrep's rulesets; the Sonar gate keeps covering first-party code beyond them.
  • PyPI attestations depend on E21's upload; a version released before the attestation step exists carries only the GitHub attestation.

Influences

E20 and its features F20.2, F20.3, F20.4 and F20.5. The release job in .github/workflows/main.yml carries the attestation and SBOM steps; ADR-0012 keeps their logic in rn-forge-devops. Revised 2026-11-07 (F16.3): after the kiln cutover the release job is .github/workflows/_release.yml, called by ci.yml.

Alternatives considered

  • OSV-Scanner for the audit. It reads uv.lock directly but adds a second vulnerability database to a Python-only repository; pip-audit is the conventional PyPI-advisory tool.
  • Semgrep for the source scan. Better Django coverage, but a separate runner and rule set to maintain; ruff already runs on every change.
  • Sigstore tooling directly. GitHub attestations and PEP 740 attestations use Sigstore already, with no extra keys or commands to maintain.
  • Signed tags for git+ consumers. It needs a key to manage for a path the PyPI move retires.
  • Failing on every Scorecard check. Several checks (code review count, maintained) depend on contributor count, not on controls pykit can add.

Background

Accepted 2026-10-28. Revised on 2026-10-30: trusted publishing alone attaches no PEP 740 attestation to an upload, so the release job signs them with pypi-attestations, and uv publish uploads the files it finds.