README
¶
imgvet
Scan and optimize container images in one pass.
imgvet combines what today takes three tools — vulnerability scanning (Trivy), layer/size analysis (Dive), and image linting (Dockle) — into a single CLI with one unified, actionable report: terminal, JSON, or a self-contained HTML file.
$ imgvet scan myapp:latest --dockerfile Dockerfile
Image: index.docker.io/library/myapp:latest
Size: 376.9 MB (compressed, 9 layers)
LAYERS
# SIZE FILES COMMAND
0 48.3 MB 9296 ADD rootfs.tar /
...
VULNERABILITIES
SEVERITY ID PACKAGE INSTALLED FIXED IN
HIGH CVE-2026-1234 libssl3 3.0.2 3.0.9
...
TOP WASTED FILES
20.0 MB deleted /tmp/bigfile
2.2 MB overwritten /var/cache/debconf/templates.dat
FINDINGS
[WARN] IV-DF-001: apt install without cleaning /var/lib/apt/lists ... (Dockerfile:12)
[ERROR] IV-DF-008: ENV API_KEY looks like a secret baked into the image (Dockerfile:4)
BASE IMAGE RECOMMENDATIONS
buildpack-deps:bookworm → node:18-slim or node:18-alpine
SUMMARY
Vulnerabilities: 2 high, 8 medium, 17 low
Wasted: 22.4 MB
Efficiency: 39.1/100
Install
go install github.com/anaskmh/imgvet@latest
Or grab a binary from Releases. For vulnerability scanning, also install trivy (brew install trivy) — without it, imgvet still runs all optimization analysis.
Usage
# Full scan: vulnerabilities + optimization
imgvet scan node:18
# Include Dockerfile lint findings with line numbers
imgvet scan myapp:latest --dockerfile ./Dockerfile
# Self-contained HTML report (works offline, email/CI-artifact friendly)
imgvet scan myapp:latest --format html -o report.html
# JSON for tooling; re-render it later without rescanning
imgvet scan myapp:latest --format json -o report.json
imgvet render report.json --format html -o report.html
# CI gates: exit code 2 on policy failure
imgvet scan myapp:latest --fail-on high --min-score 80
# Optimization-only (air-gapped, no trivy)
imgvet scan ./image.tar --scanner none
Image sources: plain references try the local Docker daemon first, then the registry (using your existing Docker credentials and credential helpers). Force a source with daemon://ref or tar://path, or pass a .tar from docker save. --platform linux/amd64 selects a variant of multi-arch images.
Exit codes: 0 success · 1 error · 2 policy gate failed (--fail-on, --min-score).
What it checks
Vulnerabilities — via a pluggable scanner interface; the default backend execs trivy against the image tar (pulled once) and normalizes its JSON. Each CVE is tied to the layer that introduced it.
Wasted space — streams every layer's tar headers (contents are never extracted) and diffs the file trees across layers: files overwritten by later layers, deleted files (OCI whiteouts/opaque dirs) that still ship in earlier layers, per-layer waste attribution.
Dockerfile lint (IV-DF-* rules) — uncleaned apt/apk/yum/pip caches, COPY . . bloat, ADD misuse, unpinned base tags, missing non-root USER, secrets in ENV, single-stage builds that compile code. When no Dockerfile is given, a reduced rule set runs against the image history.
Base image recommendations — detects the runtime (node/python/go/java from official-image env vars, OS from /etc/os-release, base from OCI annotations) and suggests slim/alpine/distroless alternatives. Best-effort and informational; never gates CI.
Efficiency score
score = 100 × (1 − wastedBytes / totalFileBytes), minus a capped penalty for lint findings (2 points per error, 1 per warning, max 15), floored at 0. A clean minimal image scores 100.
Comparison
| imgvet | trivy | dive | dockle | |
|---|---|---|---|---|
| CVE scanning | ✅ (via trivy) | ✅ | – | – |
| Layer waste analysis | ✅ | – | ✅ (TUI) | – |
| Dockerfile lint | ✅ | ✅ (misconfig) | – | ✅ |
| Base image recommendations | ✅ | – | – | – |
| Single unified report (JSON/HTML) | ✅ | – | – | – |
| CI gates on both CVEs and size | ✅ | CVEs only | score only | ✅ |
JSON schema
The report follows a versioned schema (schemaVersion: 1) defined in pkg/report — Go consumers can import that package directly.
Contributing
See CONTRIBUTING.md — adding a lint rule or a scanner backend (grype is a natural next one) is deliberately easy. Security reports: SECURITY.md.
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
analyze/dockerfile
Package dockerfile lints Dockerfiles with size- and security-focused heuristics.
|
Package dockerfile lints Dockerfiles with size- and security-focused heuristics. |
|
analyze/filetree
Package filetree streams every layer's tar headers (bodies are never read) and diffs the resulting file trees across layers to find wasted bytes: files that a later layer overwrites or deletes (OCI whiteouts), which still ship in the image.
|
Package filetree streams every layer's tar headers (bodies are never read) and diffs the resulting file trees across layers to find wasted bytes: files that a later layer overwrites or deletes (OCI whiteouts), which still ship in the image. |
|
analyze/layers
Package layers extracts per-layer metadata: sizes and the Dockerfile command that created each layer (from config history).
|
Package layers extracts per-layer metadata: sizes and the Dockerfile command that created each layer (from config history). |
|
analyze/recommend
Package recommend suggests smaller or safer base images.
|
Package recommend suggests smaller or safer base images. |
|
cli
Package cli defines the imgvet command tree.
|
Package cli defines the imgvet command tree. |
|
engine
Package engine orchestrates the scan pipeline: image resolution, analyzer fan-out, and report assembly.
|
Package engine orchestrates the scan pipeline: image resolution, analyzer fan-out, and report assembly. |
|
image
Package image acquires container images from the local daemon, a remote registry, or a tarball, and exposes them as go-containerregistry v1.Image.
|
Package image acquires container images from the local daemon, a remote registry, or a tarball, and exposes them as go-containerregistry v1.Image. |
|
render/htmlreport
Package htmlreport renders a self-contained single-file HTML report: the embedded template carries inline CSS/JS and the report JSON, so the file works offline as a CI artifact or email attachment.
|
Package htmlreport renders a self-contained single-file HTML report: the embedded template carries inline CSS/JS and the report JSON, so the file works offline as a CI artifact or email attachment. |
|
render/jsonout
Package jsonout emits the canonical JSON form of a report.
|
Package jsonout emits the canonical JSON form of a report. |
|
render/table
Package table renders a human-readable terminal report.
|
Package table renders a human-readable terminal report. |
|
scan
Package scan defines the pluggable vulnerability scanner interface.
|
Package scan defines the pluggable vulnerability scanner interface. |
|
scan/trivy
Package trivy adapts the trivy CLI as a scan.Scanner.
|
Package trivy adapts the trivy CLI as a scan.Scanner. |
|
pkg
|
|
|
report
Package report defines the unified imgvet report schema.
|
Package report defines the unified imgvet report schema. |