[PR #1522] Linter: add Dockerfile Sanity #38141

Open
opened 2026-08-20 02:56:18 -05:00 by GiteaMirror · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/veggiemonk/awesome-docker/pull/1522
Author: @sujeito-operator
Created: 8/11/2026
Status: 🔄 Open

Base: master ← Head: add-dockerfile-sanity


📝 Commits (1)

  • 07e0acf Linter: add Dockerfile Sanity

📊 Changes

1 file changed (+1 additions, -0 deletions)

View changed files

📝 README.md (+1 -0)

📄 Description

  • I HAVE READ .github/CONTRIBUTING.md

"This project exists to lint Dockerfiles for the mistakes that cost build time, image size, or a credential you cannot take back."

One line added to ### Linter. No other file touched, no heading added, no badge.

What it is

Dockerfile Sanity is a VS Code extension that reads the Dockerfile as text and reports diagnostics on open and on save. Dependency-free JavaScript — it does not shell out to hadolint, and it does not need Go or a Docker daemon installed, which is the only reason it exists next to hadolint rather than instead of it.

The rules it is actually for, as opposed to the hygiene ones:

  • cache-order — COPY . . before npm ci / pip install, checked in every stage, because in a multi-stage build the expensive install is usually in the builder.
  • baked-secret — a credential in ENV/ARG, which docker history reads back out of the shipped image even if a later layer deletes it.
  • secret-arg-to-env — an ARG with a secret-shaped name promoted to ENV, so whatever --build-arg supplied persists in the image. Nothing is wrong with the file; the leak happens at build time.
  • copy-from-latest — COPY --from= can name an external image, not just an earlier stage, and an unpinned tag there is as unreproducible as an unpinned FROM and easier to miss.

The number I would want to see if I were you

baked-secret is the only error-severity rule it ships, so its false-positive rate is the whole question. Measured on 114 Dockerfiles pulled from distinct public repositories and kept whatever was in them — not filtered to files that already score badly:

0.0.4  baked-secret       6 hits   -- every one a false positive
0.0.5  baked-secret       0 hits
0.0.5  secret-arg-to-env  0 hits

There is a second sample of 32 Dockerfiles, and it is kept separate rather than added to that number for two reasons: it is deliberately biased — the output of a scanner that drops every repository scoring zero, so it over-represents bad files — and 26 of its repositories are already in the corpus above, so it contributes only 6 new ones. On it 0.0.4 fired 5 times, also all false positives, and 0.0.5 fired 0. It is worth mentioning for one reason: secret-arg-to-env produced 1 hit, a true positive — PrefectHQ/prefect promoting VITE_AMPLITUDE_API_KEY from ARG to ENV. Prefect is one of the 6 repositories the unbiased corpus does not contain, which is why that rule shows zero above.

0.0.4 matched the key as a substring and never read the value, so ENV TIKTOKEN_CACHE_DIR=/code/.tiktoken_cache was an error because TIKTOKEN contains TOKEN. It hit NVIDIA, PostHog, open-webui and Prefect. 0.0.5 requires the key and the value to look like a credential; the unit tests still hold real ones at their previous count.

Every hit, the instruction that produced it, and the sampling frame — repository, path and branch of every file measured, with the shared set between the two populations listed explicitly — are published at precision/. Nothing there asks you to trust this repository: re-fetch the same files and run analyze.js over them, because the rule is a pure function of the Dockerfile text.

What you should hold against it

  • Almost nobody uses it. The Marketplace reads 1 install. It was published this month. If this list expects adoption before listing, that is a fair reason to close this and I will not argue it.
  • It is regex-level analysis, not a parser. It reads the Dockerfile as text; it does not build the image, resolve base images, or check that a package exists. The README says so under "Honest limits".
  • It overlaps hadolint, which is already listed and is better at the hygiene rules. The non-overlapping parts are cache-order across stages, secret-arg-to-env, and running with nothing installed.
  • Disclosure, because you would find it. The bottom of that README carries a paid consulting offer from me, and package.json has a sponsor link. The extension itself is free and MIT, with no telemetry and no paywalled rules, so I did not mark it :yen: — but you may read the README differently, and I would rather you close this than merge something you would regret. Say the word and I will close it.
  • I could not run make lint — no Go toolchain on this machine. Instead I ported internal/parser/parser.go's entry regex and all four rules in internal/linter/rules.go to a script and ran them against the spliced README: description starts with a capital, ends with a period, no duplicate URL anywhere in the document, and the section is sorted case-insensitively with the entry between docker-image-size-limit and Hadolint. If your CI disagrees, that is my port being wrong, not a disagreement — tell me and I will fix the line.

On the section

I put it under Building Images -> Linter because the object of work is the Dockerfile, which is the row your CONTRIBUTING table marks Accept. It is also arguably User Interfaces -> IDE Integrations, since it ships as an editor extension rather than a CLI. Happy to move it, reword it, shorten it, or close it — whichever is least work for you.


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/veggiemonk/awesome-docker/pull/1522 **Author:** [@sujeito-operator](https://github.com/sujeito-operator) **Created:** 8/11/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `add-dockerfile-sanity` --- ### 📝 Commits (1) - [`07e0acf`](https://github.com/veggiemonk/awesome-docker/commit/07e0acf6be4ecb5bb4f5dfe6a5f055950f5fceba) Linter: add Dockerfile Sanity ### 📊 Changes **1 file changed** (+1 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+1 -0) </details> ### 📄 Description - [x] I HAVE READ .github/CONTRIBUTING.md *"This project exists to **lint Dockerfiles for the mistakes that cost build time, image size, or a credential you cannot take back**."* One line added to `### Linter`. No other file touched, no heading added, no badge. ### What it is [Dockerfile Sanity](https://github.com/sujeito-operator/dockerfile-sanity) is a VS Code extension that reads the Dockerfile as text and reports diagnostics on open and on save. Dependency-free JavaScript — it does not shell out to `hadolint`, and it does not need Go or a Docker daemon installed, which is the only reason it exists next to hadolint rather than instead of it. The rules it is actually for, as opposed to the hygiene ones: - **`cache-order`** — `COPY . .` before `npm ci` / `pip install`, checked in *every* stage, because in a multi-stage build the expensive install is usually in the builder. - **`baked-secret`** — a credential in `ENV`/`ARG`, which `docker history` reads back out of the shipped image even if a later layer deletes it. - **`secret-arg-to-env`** — an `ARG` with a secret-shaped name promoted to `ENV`, so whatever `--build-arg` supplied persists in the image. Nothing is wrong with the file; the leak happens at build time. - **`copy-from-latest`** — `COPY --from=` can name an external image, not just an earlier stage, and an unpinned tag there is as unreproducible as an unpinned `FROM` and easier to miss. ### The number I would want to see if I were you `baked-secret` is the only `error`-severity rule it ships, so its false-positive rate is the whole question. Measured on **114 Dockerfiles pulled from distinct public repositories and kept whatever was in them** — not filtered to files that already score badly: 0.0.4 baked-secret 6 hits -- every one a false positive 0.0.5 baked-secret 0 hits 0.0.5 secret-arg-to-env 0 hits There is a second sample of 32 Dockerfiles, and it is kept separate rather than added to that number for two reasons: it is deliberately biased — the output of a scanner that drops every repository scoring zero, so it over-represents bad files — and 26 of its repositories are already in the corpus above, so it contributes only 6 new ones. On it 0.0.4 fired 5 times, also all false positives, and 0.0.5 fired 0. It is worth mentioning for one reason: `secret-arg-to-env` produced 1 hit, a true positive — `PrefectHQ/prefect` promoting `VITE_AMPLITUDE_API_KEY` from `ARG` to `ENV`. Prefect is one of the 6 repositories the unbiased corpus does not contain, which is why that rule shows zero above. 0.0.4 matched the *key* as a substring and never read the *value*, so `ENV TIKTOKEN_CACHE_DIR=/code/.tiktoken_cache` was an error because TIKTOKEN contains TOKEN. It hit NVIDIA, PostHog, open-webui and Prefect. 0.0.5 requires the key *and* the value to look like a credential; the unit tests still hold real ones at their previous count. Every hit, the instruction that produced it, and the sampling frame — repository, path and branch of every file measured, with the shared set between the two populations listed explicitly — are published at **[`precision/`](https://github.com/sujeito-operator/dockerfile-sanity/tree/main/precision)**. Nothing there asks you to trust this repository: re-fetch the same files and run `analyze.js` over them, because the rule is a pure function of the Dockerfile text. ### What you should hold against it - **Almost nobody uses it.** The Marketplace reads **1 install**. It was published this month. If this list expects adoption before listing, that is a fair reason to close this and I will not argue it. - **It is regex-level analysis, not a parser.** It reads the Dockerfile as text; it does not build the image, resolve base images, or check that a package exists. The README says so under "Honest limits". - **It overlaps hadolint**, which is already listed and is better at the hygiene rules. The non-overlapping parts are `cache-order` across stages, `secret-arg-to-env`, and running with nothing installed. - **Disclosure, because you would find it.** The bottom of that README carries a paid consulting offer from me, and `package.json` has a `sponsor` link. The extension itself is free and MIT, with no telemetry and no paywalled rules, so I did not mark it `:yen:` — but you may read the README differently, and I would rather you close this than merge something you would regret. Say the word and I will close it. - **I could not run `make lint`** — no Go toolchain on this machine. Instead I ported `internal/parser/parser.go`'s entry regex and all four rules in `internal/linter/rules.go` to a script and ran them against the spliced README: description starts with a capital, ends with a period, no duplicate URL anywhere in the document, and the section is sorted case-insensitively with the entry between `docker-image-size-limit` and `Hadolint`. If your CI disagrees, that is my port being wrong, not a disagreement — tell me and I will fix the line. ### On the section I put it under **Building Images -> Linter** because the object of work is the Dockerfile, which is the row your CONTRIBUTING table marks Accept. It is also arguably **User Interfaces -> IDE Integrations**, since it ships as an editor extension rather than a CLI. Happy to move it, reword it, shorten it, or close it — whichever is least work for you. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-08-20 02:56:19 -05:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/awesome-docker#38141