Dockttier 🐳🛡
Dockerfile templates, real-time security and optimization analysis, one-click fixes, scores, a CI command-line tool and AI review, all in VS Code.
Dockttier helps teams ship containers that are secure by default, small and fast to build. Start from a verified template, get problems underlined as you type, fix them with one click, and run the same checks in CI.
✨ Features
📦 Template library (26 templates, all grade A)
|
Templates |
| Basic · Single-stage |
Node.js, Python, Static site (unprivileged NGINX) |
| Basic · Multi-stage |
Frontend SPA → NGINX, Go → Alpine |
| Production · Multi-stage |
Node.js (deps/build/runtime + tini), Python (venv + gunicorn), Java Spring Boot (layered jar), .NET (Alpine ASP.NET), Rust (distroless cc) |
| Production · Security |
Node.js on distroless, Python on distroless with hash-verified deps, Go on scratch |
| Production · Security (new in 1.1, score 100/100/100) |
PHP on FrankenPHP, Laravel, Rust static binary on scratch, Ruby on Rails, Elixir/Phoenix release, Bun, Deno with least-privilege permissions, Java on distroless, ASP.NET Core on chiseled Ubuntu, Next.js standalone |
| Production · Optimization |
Node.js with pnpm + BuildKit cache, Python with uv, Java with a custom jlink JRE |
- Quick Pick (
Dockttier: Insert Dockerfile Template…) grouped Basic / Production, with security and optimization scores.
- Template Gallery webview: search, filter by goal or language, inspect, fill in variables (
{{NODE_VERSION}}, {{PORT}} …) and create.
- Generate Dockerfile for Project detects your stack (
package.json, next.config.*, bun.lock, pnpm-lock.yaml, uv.lock, go.mod, pom.xml, *.csproj, Cargo.toml, composer.json, artisan, Gemfile, mix.exs, deno.json …) and recommends the best template.
- The 1.1 security templates pin every base image by tag and digest. Each runs as a numeric non-root user with root-owned, read-only application files and ships a
runHint for a hardened docker run (--read-only --cap-drop=ALL --security-opt=no-new-privileges, tmpfs). The PHP and Laravel templates use a hardened php.ini and opcache. Each one was build-tested with Docker; see docs/template-verification.md.
- Template tree view in the Dockttier activity bar.
- Team templates: save any Dockerfile as a template into
.dockttier/templates/ and commit it. Add personal folders with dockttier.templates.paths, or a shared cloud repository with dockttier.templates.remoteUrl (HTTPS JSON, cached offline).
- Template scores are computed by the analyzer, not hand-written, so they can't drift.
🔍 Real-time analysis: 53 rules
Problems appear in the Problems panel as you type (debounced, typically < 5 ms per file).
- 🛡 Security (18): root user,
latest / untagged images, secrets in ENV/ARG, hardcoded credentials (AWS, GitHub, Slack, Stripe, private keys …), curl | sh, ADD <url> without checksum, sudo, chmod 777, SSH port, disabled TLS verification, unsigned packages, copied .env / keys, end-of-life images, digest pinning, secrets leaking from the build context (.env, keys, cloud and registry credentials, Terraform state or .git that a broad COPY would bake into the image), trusted registries and banned images policies.
- 🚀 Optimization (13): consecutive
RUNs, COPY . . before dependency install, apt/apk/pip/yum cache cleanup, --no-install-recommends, slim/alpine bases, multi-stage for compiled languages, npm ci, missing .dockerignore, large build context, BuildKit cache mounts.
- ✅ Best practice (22): empty or
FROM-less files (graded F, never A), missing CMD/ENTRYPOINT, exec-form CMD/ENTRYPOINT, pipefail, absolute WORKDIR, HEALTHCHECK, OCI labels, duplicate CMD, invalid JSON form, invalid EXPOSE, bad COPY --from references, duplicate stage names, MAINTAINER, legacy ENV k v, apt vs apt-get, typos in instructions ("Did you mean RUN?") …
See the full rule list below.
⚡ Quick fixes
More than 25 rules have one-click fixes (Ctrl+.), for example: pin a base image, add a non-root user (aware of Alpine, Debian and distroless), reorder COPY for caching, merge RUNs, add cache cleanup, convert to exec form, npm install → npm ci --omit=dev, add pipefail (uses SHELL bash on Debian, where dash has no pipefail). Every finding also offers ignore for this line, disable rule and learn more.
Fix All (Dockttier: Fix All, CodeLens, or source.fixAll.dockttier on save) applies safe fixes repeatedly until nothing changes.
📊 Scores, report and status bar
- Status bar:
Dockttier B 84 with a hover breakdown.
- CodeLens: scores, fix count and per-stage issue counts above the file; an empty file offers templates instead.
- Live analysis report that updates as you type, without reloading:
- A grade hero with a plain-language verdict, the score change since your last edit and a score-history sparkline.
- Animated security, optimization and best-practice gauges with per-category error and warning tallies.
- Fix All with a projected grade (for example,
Fix 6 issues → B · 84), computed by actually applying the fixes.
- Next best moves: the findings whose fix raises the score most, with the exact point gain.
- Findings you can filter by severity, search and group by category, severity or line. Each one has "Why it matters", go to line and one-click fix, and new findings flash when they appear.
- A hardening checklist with progress, a build pipeline view of stages and their
COPY --from dependencies, build context size and leaked secrets with a one-click .dockerignore fix.
- Run it hardened: Compose, Kubernetes and
docker run configs for this image.
- Export to Markdown, SARIF or JSON.
- Grading is strict on purpose: any error caps the score at F, an open security warning rules out an A, and a file with nothing to build is F 0.
🔒 Run it hardened
Dockttier: Generate Hardened Runtime Config turns what the Dockerfile declares (user, ports, health check, volumes, stop signal) into a least-privilege Compose service, Kubernetes Deployment + Service or docker run command:
- read-only root filesystem with a
noexec tmpfs for /tmp
- all capabilities dropped, plus
NET_BIND_SERVICE only when a port below 1024 needs it
no-new-privileges, PID and memory/CPU limits, ports bound to localhost
- In Kubernetes:
runAsNonRoot with the numeric UID pinned (Kubernetes can't verify named users like node), the RuntimeDefault seccomp profile and automountServiceAccountToken: false
- readiness and liveness probes derived from your
HEALTHCHECK URL
- notes when the image itself needs changing, for example "runs as root"
🔑 Build context secret scan
Dockttier walks the build context next to each Dockerfile, applies .dockerignore exactly the way Docker does, and flags sensitive files a broad COPY would bake into a layer: .env*, private keys (*.pem, *.key, id_rsa …), .npmrc/.pypirc/.netrc, cloud credentials, Terraform state and .git. Docker's patterns are root-anchored, so *.key does not exclude certs/tls.key, and Dockttier catches that. The quick fix adds them to .dockerignore. The CLI runs the same scan (--no-context to skip).
🎓 Learning mode
- Hover a keyword for instruction docs, hover
FROM images for size, recommended tags and EOL warnings.
- Hover a problem for the explanation and a before/after example.
- Rules & Learning view and a Learn panel documenting every rule.
- A Getting Started walkthrough.
- Completions for instructions (snippets), base images with recommended tags, distroless images, stage names and BuildKit
--mount options.
✨ AI-powered suggestions (optional)
If a VS Code language model is available (e.g. GitHub Copilot):
- Dockttier: AI Review streams a context-aware review plus an improved Dockerfile, using the static findings as grounding.
@dockttier chat participant: /review, /template <what you're building>, /explain DT1002.
Everything else works fully offline with no AI.
🏗 CI/CD integration
The extension bundles the same engine as a command-line tool:
node out/cli.js . # scan all Dockerfiles, fail on errors
node out/cli.js . --fail-on warning # stricter
node out/cli.js . -f sarif -o dockttier.sarif # GitHub code scanning
node out/cli.js . -f markdown >> $GITHUB_STEP_SUMMARY
node out/cli.js Dockerfile --fix # apply safe fixes
node out/cli.js . --min-score 80 # quality gate
node out/cli.js harden Dockerfile --target kubernetes --image ghcr.io/acme/api:1.4.2
node out/cli.js templates # list built-in templates
node out/cli.js new sec-laravel -o Dockerfile --set PHP_VERSION=8.4
Dockttier: Add Dockttier Check to GitHub Actions writes .github/workflows/dockttier.yml, which uploads SARIF to code scanning and fails the build on errors or a low score. It runs the CLI with npx dockttier, so it needs the CLI published to npm (see PUBLISHING.md). A ready-made workflow also ships in examples/github-actions.yml.
⚙️ Configuration
Team config: .dockttierrc.json
Shared by the editor and the CLI (JSON with comments, schema-validated in VS Code):
{
"rules": { "DT3009": "off", "no-sudo": "error" }, // id or name → off | error | warning | info | hint
"trustedRegistries": ["docker.io/library", "ghcr.io/acme"],
"bannedImages": ["ubuntu:1*", "*/deprecated-base*"],
"requiredLabels": ["org.opencontainers.image.source"],
"requireDigests": false
}
Inline suppression
# dockttier-ignore DT1002 DT3006
FROM gcr.io/my/base:1.0
# dockttier-ignore-file DT3009
Settings
| Setting |
Default |
Description |
dockttier.enable |
true |
Enable analysis |
dockttier.analyzeOnType / debounceMs |
true / 250 |
Live analysis |
dockttier.rules |
{} |
Severity overrides |
dockttier.trustedRegistries, bannedImages, requiredLabels, requireDigests |
|
Policy (same as rc file) |
dockttier.checkBuildContext / buildContextWarningMB |
true / 100 |
Build context size warning |
dockttier.hover.enable, learningMode, codeLens.enable, statusBar.enable |
true |
UI |
dockttier.templates.paths, templates.remoteUrl |
|
Extra template sources |
dockttier.ai.enable, ai.modelFamily |
true, "" |
AI features |
📋 Rules
| ID |
Category |
Default |
Name |
Rule |
| DT1001 |
security |
warning |
pin-base-image-tag |
Pin base image versions instead of using latest |
| DT1002 |
security |
warning |
run-as-non-root |
Final image should not run as root |
| DT1003 |
security |
warning |
no-root-user |
Do not switch the final stage back to root |
| DT1004 |
security |
error |
no-secrets-in-env-arg |
Do not pass secrets through ENV or ARG |
| DT1005 |
security |
warning |
no-curl-pipe-shell |
Do not pipe remote scripts into a shell |
| DT1006 |
security |
warning |
no-add-remote-url |
Avoid ADD with remote URLs without a checksum |
| DT1007 |
security |
warning |
no-sudo |
Do not use sudo in Dockerfiles |
| DT1008 |
security |
warning |
no-world-writable |
Avoid world-writable permissions |
| DT1009 |
security |
warning |
no-ssh-port |
Do not expose SSH (port 22) |
| DT1010 |
security |
error |
no-insecure-tls |
Do not disable TLS certificate verification |
| DT1011 |
security |
error |
no-sensitive-files |
Do not copy credentials or keys into the image |
| DT1012 |
security |
hint |
pin-base-image-digest |
Pin base images by digest for reproducible builds |
| DT1013 |
security |
error |
no-unverified-packages |
Do not install unsigned or unverified packages |
| DT1014 |
security |
warning |
no-eol-base-image |
Do not use deprecated or end-of-life base images |
| DT1015 |
security |
error |
trusted-registry |
Base images must come from trusted registries |
| DT1016 |
security |
error |
banned-image |
Do not use banned base images |
| DT1017 |
security |
error |
no-hardcoded-credentials |
Do not hardcode credentials |
| DT1018 |
security |
error |
context-secret-leak |
Do not copy secrets from the build context |
| DT2001 |
optimization |
info |
combine-consecutive-run |
Combine consecutive RUN instructions |
| DT2002 |
optimization |
warning |
copy-before-install |
Copy dependency manifests before the full source |
| DT2003 |
optimization |
warning |
apt-cleanup |
Clean the apt cache in the same layer |
| DT2004 |
optimization |
info |
apt-no-install-recommends |
Use --no-install-recommends with apt-get |
| DT2005 |
optimization |
info |
apk-no-cache |
Use apk add --no-cache |
| DT2006 |
optimization |
info |
pip-no-cache-dir |
Use pip install --no-cache-dir |
| DT2007 |
optimization |
info |
prefer-slim-base |
Prefer a smaller base image for the runtime stage |
| DT2008 |
optimization |
warning |
use-multi-stage |
Use a multi-stage build for compiled applications |
| DT2009 |
optimization |
info |
yum-dnf-cleanup |
Clean yum/dnf/zypper caches in the same layer |
| DT2010 |
optimization |
info |
prefer-npm-ci |
Use npm ci for reproducible installs |
| DT2011 |
optimization |
warning |
missing-dockerignore |
Add a .dockerignore file |
| DT2012 |
optimization |
warning |
large-build-context |
Keep the build context small |
| DT2013 |
optimization |
hint |
use-cache-mounts |
Use BuildKit cache mounts for package managers |
| DT3001 |
best-practice |
warning |
no-maintainer |
MAINTAINER is deprecated |
| DT3002 |
best-practice |
warning |
absolute-workdir |
Use absolute paths for WORKDIR |
| DT3003 |
best-practice |
info |
use-workdir |
Use WORKDIR instead of cd |
| DT3004 |
best-practice |
warning |
single-cmd-entrypoint |
Only one CMD, ENTRYPOINT and HEALTHCHECK per stage |
| DT3005 |
best-practice |
warning |
exec-form |
Use exec (JSON) form for CMD and ENTRYPOINT |
| DT3006 |
best-practice |
info |
healthcheck |
Define a HEALTHCHECK for long-running services |
| DT3007 |
best-practice |
warning |
apt-get-yes |
Use -y with apt-get install |
| DT3008 |
best-practice |
warning |
prefer-apt-get |
Use apt-get instead of apt in scripts |
| DT3009 |
best-practice |
info |
oci-labels |
Add OCI image labels |
| DT3010 |
best-practice |
info |
uppercase-instruction |
Write instructions in uppercase |
| DT3011 |
best-practice |
error |
unknown-instruction |
Unknown instruction |
| DT3012 |
best-practice |
error |
from-first |
Dockerfile must have a FROM, and start with it |
| DT3013 |
best-practice |
error |
valid-stage-reference |
COPY --from must reference an earlier stage |
| DT3014 |
best-practice |
error |
unique-stage-names |
Stage names must be unique and not reserved |
| DT3015 |
best-practice |
warning |
pipefail |
Set pipefail when using pipes |
| DT3016 |
best-practice |
error |
valid-expose |
EXPOSE must use valid ports |
| DT3017 |
best-practice |
error |
copy-dest-directory |
COPY with multiple sources needs a directory destination |
| DT3018 |
best-practice |
info |
env-key-value |
Use ENV key=value syntax |
| DT3019 |
best-practice |
error |
valid-json-form |
Exec form must be valid JSON |
| DT3020 |
best-practice |
warning |
prefer-copy |
Use COPY instead of ADD for local files |
| DT3021 |
best-practice |
warning |
apt-update-alone |
Do not run apt-get update in a separate layer |
| DT3022 |
best-practice |
info |
final-command |
Define CMD or ENTRYPOINT for the final image |
🧱 Architecture
src/
core/ Pure TypeScript, no VS Code dependency (shared by extension and CLI)
parser.ts Position-preserving Dockerfile parser (directives, continuations, heredocs, stages, flags, JSON form)
shell.ts Quote-aware shell command splitter for RUN analysis
rules/ 53 rules: security.ts, optimization.ts, bestPractice.ts
contextScan.ts .dockerignore semantics and build-context secret detection
harden.ts Hardened Compose / Kubernetes / docker run generator
analyzer.ts Rule engine, config/ignores, scoring, fix application
templates.ts Template model, validation, rendering, recommendation
insights.ts Image profile (non-root, multi-stage, minimal base …)
vscode/ Diagnostics, code actions, hover, completion, CodeLens, status bar,
tree views, gallery/report/learn webviews, AI and chat
node/ Build-context walker shared by the extension and CLI
cli.ts CI command line (text, JSON, SARIF, Markdown; --fix; quality gates; harden; templates)
media/ Report webview script and styles
templates/ JSON template library
schemas/ JSON schemas for .dockttierrc.json and team templates
🧪 Development
npm install
npm run typecheck
npm test # 219 unit tests: parser, every rule (positive + negative), fixes, templates, CLI, performance
npm run build # bundles out/extension.js and out/cli.js with esbuild
npm run package # produces dockttier-<version>.vsix
Press F5 in VS Code to launch an Extension Development Host.
📄 License
MIT
| |