Dockerfile Pack
URL slug: dockerfile
The Dockerfile pack reviews changed build stages for security, performance, and reliability issues. It accepts a unified git diff or a complete Dockerfile. It checks for unpinned base images, unchecked downloads, secrets in the image, a final stage that runs as root, inefficient layer order, and shutdown signals that may not reach the process.
Which files it reads
Section titled “Which files it reads”A diff file reaches this pack when its path matches one of these globs:
| Glob | Matches |
|---|---|
*Dockerfile | Dockerfile, services/api/Dockerfile |
*Dockerfile.* | Dockerfile.dev, docker/Dockerfile.prod |
*.dockerfile | worker.dockerfile |
*Containerfile | Containerfile |
BuildKit’s Dockerfile.dockerignore matches a glob, but the pack skips files ending in .dockerignore.
The pack also recognises a complete Dockerfile pasted on its own (sniff() returns 0.9). The content must start with FROM, optionally preceded by ARG instructions, and another Dockerfile instruction must follow the FROM. A Markdown page or SQL query that merely contains a FROM line does not match.
How the pack parses input
Section titled “How the pack parses input”parse_dockerfile_input (opentremor_pack_dockerfile/parser.py) handles input in these steps:
- A complete Dockerfile becomes a diff that adds every line. Both input types then use the same stage splitter and rules.
- The parser reads a diff file by file with core’s
split_unified_diffanditer_hunks(opentremor_core.libs.diff). It joins each file’s hunks in order and inserts a line containing only@@where the diff skips lines. - Each
FROMline opens a stage. A stage runs up to the nextFROM. When a diff replaces aFROMline (-FROM node:18then+FROM node:20), both lines stay in one stage. Changed lines before the firstFROMshown in the input form anunknownunit. These lines may be the end of a stage whoseFROMis above the diff or globalARGlines. - The parser keeps only stages with a real change. Core’s
change_kindsets each unit’s action.
Stage identity
Section titled “Stage identity”| Unit | type | name |
|---|---|---|
FROM golang:1.23 AS build, followed by another stage | stage | build |
FROM gcr.io/distroless/static:nonroot, the last stage | final-stage | gcr.io/distroless/static:nonroot |
Changed lines before any FROM shown in the input | stage or final-stage | unknown |
The parser marks the last stage that survives the change as final-stage; rules treat it as the image that ships. A diff may stop before the end of the file, so a later stage may exist that the diff does not show. Rules about the final stage therefore have MEDIUM confidence at most.
How diff markers set the action
Section titled “How diff markers set the action”| Markers in the stage | action |
|---|---|
+ only | add |
- only | delete |
| both | modify |
Unit shape
Section titled “Unit shape”{ "hash": "<sha256 of the normalised body>", "type": "final-stage", "name": "node:20-slim", "action": "add", "body": "+FROM node:20-slim\n+WORKDIR /app\n+CMD npm start", "metadata": { "generated_at_utc": "2026-10-26T10:30:00Z", "source_path": "services/api/Dockerfile", "group_path": null }}source_path comes from the diff header’s b/... side. It is null for a complete Dockerfile. group_path is always null.
The body keeps its +, -, and space markers. A rule such as “the diff removes the USER line” needs to distinguish a removed line from an unchanged one.
Rulesets
Section titled “Rulesets”Rules live as Markdown in the package’s opentremor_pack_dockerfile/rules/ directory:
| File | Served at |
|---|---|
dockerfile-rules.md | GET /v1/dockerfile/rules |
What the default ruleset covers
Section titled “What the default ruleset covers”| Rule ID | Area | What it catches |
|---|---|---|
| DOCK-001 | Supply chain | A changed FROM line uses a mutable tag without a digest, or pulls from a registry outside the default list (which orgs can replace). |
| DOCK-003 | Supply chain | ADD fetches a remote URL without --checksum=sha256:.... |
| DOCK-004 | Supply chain | A RUN command downloads a script, archive, or binary and uses it without an integrity check. |
| DOCK-007 | Supply chain | A package manager uses plain HTTP or has signature checks disabled. |
| DOCK-005 | Secrets | ARG or ENV carries a secret, or COPY or ADD brings in a secret file. |
| DOCK-006 | Secrets | A stage copies a secret file or directory from an earlier stage. |
| DOCK-010 | Secrets | The diff removes a RUN --mount=type=secret and passes the same secret another way. |
| DOCK-011 | Secrets | The final stage copies the whole build context; asks the reader to check .dockerignore. |
| DOCK-002 | Privilege | The final stage runs as root or the diff removes the line that dropped privileges. |
| DOCK-008 | Privilege | A command makes a path world-writable. |
| DOCK-009 | Privilege | The final stage installs an SSH server or sudo. |
| DOCK-012 | Build commands | A RUN command expands a build argument without quotes. |
| DOCK-PERF-001 to -004 | Performance | Dependency layer order, apt lists, build tools in the runtime image, or caches and build outputs shipped in the image. |
| DOCK-REL-001, -002 | Reliability | The diff removes HEALTHCHECK; shell-form CMD or ENTRYPOINT may not pass SIGTERM. |
Performance and Reliability rules have LOW or MEDIUM severity and do not fail the merge check on their own. Core syncs built-in rules from the pack file for orgs that have not edited them (OpenTremor-core#0034).
Worked example
Section titled “Worked example”diff --git a/services/api/Dockerfile b/services/api/Dockerfilenew file mode 100644--- /dev/null+++ b/services/api/Dockerfile@@ -0,0 +1,10 @@+FROM node:20 AS build+ARG NPM_TOKEN+WORKDIR /app+COPY . .+RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && npm ci++FROM node:20-slim+COPY --from=build /app /app+RUN curl -fsSL https://get.example.com/agent/install.sh | sh+CMD npm startThe parser creates two units, both with action add:
- A
stagenamedbuild. The LLM matches DOCK-005 because the build argument is written to.npmrc. It also matches DOCK-001 becausenode:20has no digest, and DOCK-PERF-001 becauseCOPY . .comes beforenpm ci. - A
final-stagenamednode:20-slim. The LLM matches DOCK-006 because the copied/appcontains the token, DOCK-004 because the command pipes a download tosh, DOCK-002 because the stage has noUSER, and DOCK-REL-002 becauseCMDuses shell form.
The pack includes a similar demo sample so an org can review example findings before connecting a repository.