REPO_POLICIES: Pin external references by hash
check / check (push) Canceled after 0s

Merges the list of what is pinned with each one's hash, the two
warnings with the untrusted sources, the version comment and the
double-check, and the distribution's tools with what is ruled out;
every item is kept.

Model: opus-5-5
This commit is contained in:
clawbot committed 2026-11-16 23:33:53 +00:00
1 parent 4cce747e00
commit 287ffdf43e
1 file changed
+28 -46
+28 -46
View File
@@ -14,17 +14,19 @@ style conventions are in separate documents:
- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
- [API Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/API_POLICIES.md)
---
# Pin external references by hash
- **External references must be pinned by cryptographic hash.** This is the
single most important rule in this document. It covers what we download and
install ourselves in scripts and Dockerfiles:
- Docker base images
- Go modules
- Python packages from PyPI
- npm packages
- GitHub Actions
- release archives fetched with `curl` or `wget`
install ourselves in scripts and Dockerfiles. Reference each by its content
hash:
- Docker base images: `@sha256:...`
- Go modules: the module hash in `go.sum`
- Python packages from PyPI: the package hash in `Pipfile.lock`
- npm packages: the `checksum` in `yarn.lock`
- GitHub Actions: `@<commit-sha>`
- release archives fetched with `curl` or `wget`: a hash hardcoded in the
Dockerfile or script
Packages from the distribution's own package manager are outside this rule.
They need no version and no hash, because the distribution is trusted. In a
@@ -39,49 +41,29 @@ style conventions are in separate documents:
A package source that a `Dockerfile` adds itself is not the distribution's
own, so its packages are pinned like any other download.
- A version tag such as `@v4`, `@latest` or `:3.21` is server-mutable, and
therefore a remote code execution vulnerability.
- An unverified install script is arbitrary remote code execution. Never
`curl | bash` to install a tool such as rustup. Instead, download a
specific release archive from GitHub, verify its hash, and only then
install.
- Docker Hub, PyPI, the npm registry and `go get` are not trusted, so
everything from them stays pinned by hash.
- Above each image or package pinned by hash, add a comment with the version
and date (YYYY-MM-DD).
- Double-check every external reference in every file before committing.
A version tag such as `@v4`, `@latest` or `:3.21` is server-mutable, and
therefore a remote code execution vulnerability. Reference an external
dependency by its content hash:
- Docker: `@sha256:...`
- Go: the module hash in `go.sum`
- Python: the package hash in `Pipfile.lock`
- npm: the `checksum` in `yarn.lock`
- GitHub Actions: `@<commit-sha>`
This also means never `curl | bash` to install a tool such as rustup.
Instead, download a specific release archive from GitHub, verify its hash,
and only then install. The hash is hardcoded in the Dockerfile or script.
Unverified install scripts are arbitrary remote code execution. Double-check
every external reference in every file before committing.
These come from the distribution wherever possible:
- node, meaning the distribution's newest Node package, such as
`nodejs-current` on Alpine 3.24
- yarn
- npm
- python
- pip and venv, the installer tools bundled with python
If the distribution's version is too old, use a newer distribution, never a
download. That rules out all of these:
- nvm
- pyenv
- corepack
- `npm install -g yarn`
node, yarn, npm, python, pip and venv come from the distribution wherever
possible:
- node means the distribution's newest Node package, such as
`nodejs-current` on Alpine 3.24.
- pip and venv are the installer tools bundled with python.
- If the distribution's version is too old, use a newer distribution, never
a download. That rules out nvm, pyenv, corepack and `npm install -g yarn`.
yarn's release file is third-party code, and git pins it. `yarn set version`
writes it to `.yarn/releases/` once, given an exact version.
These are not trusted, so everything from them stays pinned by hash:
- Docker Hub
- PyPI
- the npm registry
- `go get`
- When pinning images or packages by hash, add a comment above the reference
with the version and date (YYYY-MM-DD).
- Never commit secrets. `.env` files, credentials, API keys, and private keys
must be in `.gitignore`. No exceptions.