"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>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 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)
07e0acfLinter: add Dockerfile Sanity📊 Changes
1 file changed (+1 additions, -0 deletions)
View changed files
📝
README.md(+1 -0)📄 Description
"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 . .beforenpm 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 inENV/ARG, whichdocker historyreads back out of the shipped image even if a later layer deletes it.secret-arg-to-env— anARGwith a secret-shaped name promoted toENV, so whatever--build-argsupplied 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 unpinnedFROMand easier to miss.The number I would want to see if I were you
baked-secretis the onlyerror-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: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-envproduced 1 hit, a true positive —PrefectHQ/prefectpromotingVITE_AMPLITUDE_API_KEYfromARGtoENV. 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_cachewas 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 runanalyze.jsover them, because the rule is a pure function of the Dockerfile text.What you should hold against it
cache-orderacross stages,secret-arg-to-env, and running with nothing installed.package.jsonhas asponsorlink. 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.make lint— no Go toolchain on this machine. Instead I portedinternal/parser/parser.go's entry regex and all four rules ininternal/linter/rules.goto 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 betweendocker-image-size-limitandHadolint. 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.