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
Srules 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.lockdirectly but adds a second vulnerability database to a Python-only repository;pip-auditis 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.