Documentation
¶
Overview ¶
Package refs finds container image references in a source repository: Dockerfiles and Containerfiles, Compose files, Kubernetes, OpenShift and Knative manifests (including rendered Helm output), Helm values files, and CI configuration (GitHub Actions, GitLab CI, Bitbucket Pipelines).
Every reference records exactly where it was written, byte by byte (see Part), so a fix can edit the one place that determines the part of the reference it changes: the FROM line, the ARG default that feeds it, the Compose default or .env value, the values.yaml tag line.
The scanner never guesses. A reference whose value is decided outside the repository (an ARG with no default, a Compose variable with no default and no .env value, a Helm template, a CI expression) is reported as a Skip with the reason, not as a Ref.
Known limits: Kustomize images: transformers (newName/newTag) are not applied, so a base manifest is reported as written; Kubernetes manifests in JSON are not read; GitLab CI files pulled in with include: are read only when named *.gitlab-ci.yml; Compose files read the .env file of their own directory (not one chosen with --project-directory or --env-file); a Helm chart may assemble repository and tag differently from registry/repository:tag; Dockerfiles are parsed with heredocs enabled (the BuildKit default since Dockerfile frontend 1.4).
Index ¶
- func CleanText(s string, max int) string
- func SafePath(root, rel string) (string, error)
- func Scan(root string, opts Options) ([]Ref, []Skip, error)
- func ScanFiles(root string, files []string, opts Options) ([]Ref, []Skip, error)
- func TagStart(ref string) int
- type Kind
- type Options
- type Part
- type Ref
- type Skip
- type VarUse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanText ¶
CleanText makes text safe for a one-line message: control characters (including newlines) become spaces, runs of spaces collapse, and the result is cut to max bytes on a rune boundary, with "..." appended when cut.
func SafePath ¶
SafePath joins a repository-relative path to root, refusing paths that are absolute, leave root, or pass through a symbolic link (checked with Lstat on every directory component). The final component may not exist.
func Scan ¶
Scan walks root without following symbolic links and returns every image reference it can resolve, and a Skip for everything it could not.
Skipped directories: .git, .hg and .svn (version control metadata), and, unless opts.IncludeDependencyDirs, third-party dependency directories (see dependencyDir). Each skipped dependency directory is recorded as a Skip.
Types ¶
type Options ¶
type Options struct {
// MaxFileSize is the largest file parsed, in bytes (default 4 MiB). Larger
// candidate files are skipped with a reason.
MaxFileSize int64
// IncludeDependencyDirs scans node_modules, bower_components and
// Composer/Go vendor directories, which are skipped by default.
IncludeDependencyDirs bool
// Overlay replaces the content of repository-relative paths (forward
// slashes) for this scan. A fix uses it to re-scan an edited file in
// memory.
Overlay map[string][]byte
}
Options control a scan.
type Part ¶
type Part struct {
Text string `json:"text"`
// File and Line locate the text; Line is 0 for text with no single
// location (a separator the scanner added, such as the ":" between a Helm
// values repository and tag).
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
// Column is the 1-based byte column at which Text appears verbatim on Line,
// or 0 when it does not (it was quoted with escapes, folded, ...). Only a
// Part with a Column can be edited.
Column int `json:"column,omitempty"`
// Var names the variable (Dockerfile ARG, Compose or .env variable) whose
// value supplied the text, or "" for text written in the reference itself
// (including a ${VAR:-default} default written there).
Var string `json:"var,omitempty"`
}
Part is a piece of a resolved image reference and where it was written. Concatenating the Text of a Ref's Parts gives its Image.
type Ref ¶
type Ref struct {
// File is the repository-relative path, with forward slashes.
File string `json:"file"`
// Line is the 1-based line of the reference: the FROM instruction's first
// line, or the line of the YAML scalar (for Helm values, the repository
// line).
Line int `json:"line"`
// Column is the 1-based byte column of Text on Line, when it starts there.
Column int `json:"column,omitempty"`
Kind Kind `json:"kind"`
// Context says where in the file the reference sits, for example
// "FROM", "services.web.image", "spec.template.spec.containers[0].image",
// "jobs.test.services.db.image".
Context string `json:"context,omitempty"`
// Text is the reference as written, before variable substitution.
Text string `json:"text"`
// Image is the resolved reference string.
Image string `json:"image"`
// Platform is the literal value of FROM --platform, if any.
Platform string `json:"platform,omitempty"`
// Stage is the build stage name a FROM declares (FROM image AS name).
Stage string `json:"stage,omitempty"`
// Vars lists the variables the resolved reference depends on.
Vars []VarUse `json:"vars,omitempty"`
// Parts locate every byte of Image.
Parts []Part `json:"parts"`
// EditFile, EditLine and EditText say where a fix of the tag would edit:
// the Part holding the start of the tag (or, without a tag, the end of the
// name). EditText is that Part's text.
EditFile string `json:"edit_file,omitempty"`
EditLine int `json:"edit_line,omitempty"`
EditText string `json:"edit_text,omitempty"`
}
Ref is one image reference.
type Skip ¶
type Skip struct {
File string `json:"file"`
Line int `json:"line,omitempty"`
Kind Kind `json:"kind,omitempty"`
Text string `json:"text,omitempty"`
Reason string `json:"reason"`
}
Skip is a file or reference the scanner could not resolve, with the reason.
type VarUse ¶
type VarUse struct {
Name string `json:"name"`
// File and Line locate the definition that supplied the value (the ARG
// instruction, the .env line); Line is 0 when the variable was not set and
// a default written in the reference was used.
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
// Default is true when the value came from a ${VAR:-default} written in
// the reference rather than from the variable.
Default bool `json:"default,omitempty"`
}
VarUse is a variable a reference depends on and where its value was set.
Source Files