From 287ffdf43e58cb934c631d6a127ac4c6ea818f8b Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 16 Nov 2026 23:33:53 +0000 Subject: [PATCH] REPO_POLICIES: Pin external references by hash 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 --- prompts/REPO_POLICIES.md | 74 +++++++++++++++------------------------- 1 file changed, 28 insertions(+), 46 deletions(-) diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 987ac53..7b4dc4f 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -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: `@` + - 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: `@` - - 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.