registry

type Assessment struct {
	Verdict Verdict `json:"verdict"`
	Reason  string  `json:"reason"`
	// Platforms lists the platforms that prove a PHP version.
	Platforms []PlatformVerdict `json:"platforms,omitempty"`
	// VulnerablePlatforms lists the vulnerable ones ("linux/amd64 (PHP 8.3.35)").
	VulnerablePlatforms []string `json:"vulnerable_platforms,omitempty"`
	// WithoutPHP lists platforms whose config proves no PHP version.
	WithoutPHP []string `json:"without_php,omitempty"`
}

type Error struct {
	Kind ErrorKind
	Ref  string
	Err  error
}

type ErrorKind int

type Options struct {
	// Offline makes no network requests. Only a docker.io/library/php
	// reference with an exact X.Y.Z tag and no digest resolves (the official
	// tags are the PHP version); everything else returns an Error of kind
	// KindOffline.
	Offline bool
	// Keychain supplies registry credentials (default authn.DefaultKeychain,
	// which reads the Docker config and credential helpers).
	Keychain authn.Keychain
	// Transport is the base HTTP transport (default: go-containerregistry's
	// remote.DefaultTransport with a 30 s response header timeout).
	Transport http.RoundTripper
	// Timeout bounds each Resolve and Tags call (default 2 minutes).
	Timeout time.Duration
	// Retries is how many times a request is retried after HTTP 429, 500, 502,
	// 503, 504 or a transient network error (default 4; negative for none).
	Retries int
	// MinBackoff and MaxBackoff bound the exponential backoff between retries
	// (defaults 1 s and 30 s). A Retry-After header longer than MaxRetryAfter
	// (default 60 s) is not waited for: the request fails as rate limited.
	MinBackoff, MaxBackoff, MaxRetryAfter time.Duration
	// Concurrency is the most registry requests in flight (default 4).
	Concurrency int
	// Mirrors sends requests for a registry to another host
	// ({"index.docker.io": "mirror.example.com"}). The reference keeps its
	// name; only the host contacted changes. Tests point Docker Hub at an
	// in-memory registry this way.
	Mirrors map[string]string
	// UserAgent is sent with every request (default "php2shell-scan").
	UserAgent string
	// Platforms, when set, restricts every Resolution to these platforms
	// ("linux/amd64", "linux/arm64"; see PlatformMatches): images for other
	// platforms are left out and listed in Resolution.OmittedPlatforms.
	Platforms []string
	// RequestTimeout bounds the wait for each response's headers (default
	// 30 s) and, at twice that, for its body, whatever Transport is given. A
	// registry host that times out is not contacted again by this Resolver:
	// later requests to it fail at once (as KindTimeout).
	RequestTimeout time.Duration
}

type Platform struct {
	// Platform is os/arch[/variant]; "" when unknown (offline resolution).
	Platform string    `json:"platform"`
	Digest   string    `json:"digest,omitempty"`
	Created  time.Time `json:"created,omitempty"`
	// PHPVersion is set only when the image config proves it (see the package
	// documentation); Evidence says how.
	PHPVersion string   `json:"php_version,omitempty"`
	Evidence   []string `json:"evidence,omitempty"`
	// BaseOS is the base operating system release the image is built on,
	// normalized ("alpine:3.21", "debian:bookworm"), from the
	// org.opencontainers.image.base.name annotation (BaseSource
	// "annotation") or, failing that, from the first history entry the
	// docker-library build leaves (BaseSource "history"); "" when unknown.
	BaseOS     string `json:"base_os,omitempty"`
	BaseSource string `json:"base_source,omitempty"`
	// ImageVersion is the org.opencontainers.image.version annotation; for
	// the official php image it is the explicit tag ("8.3.20-fpm-alpine3.21").
	ImageVersion string `json:"image_version,omitempty"`
}

type PlatformVerdict struct {
	Platform   string                   `json:"platform"`
	PHPVersion string                   `json:"php_version"`
	Status     knowledge.UpstreamStatus `json:"status"`
	Reason     string                   `json:"reason"`
}

type Reference struct {
	// Original is the reference as given.
	Original string
	// Registry is the registry host as go-containerregistry normalizes it
	// ("index.docker.io" for Docker Hub).
	Registry string
	// Path is the repository path within the registry ("library/php").
	Path string
	// Tag is the tag as written, "" when there is none (for a reference
	// without a digest that means "latest").
	Tag string
	// Digest is the digest as written, "" when there is none.
	Digest string
}

type Resolution struct {
	// Ref is the reference as given; Reference is its parsed form.
	Ref       string    `json:"ref"`
	Reference Reference `json:"-"`
	// Digest is the digest of the manifest or index the reference points at.
	Digest    string `json:"digest,omitempty"`
	MediaType string `json:"media_type,omitempty"`
	// Index is true when the reference points at an image index (manifest
	// list).
	Index bool `json:"index,omitempty"`
	// Empty is true when the reference exists but holds no images: an index
	// whose only manifests are attestations, or none at all. Docker Hub
	// publishes new tags this way before their builds finish.
	Empty bool `json:"empty,omitempty"`
	// Platforms lists every image the reference holds, in index order.
	Platforms []Platform `json:"platforms,omitempty"`
	// Offline is true when the result comes from offline rules.
	Offline bool `json:"offline,omitempty"`
	// OmittedPlatforms lists the platforms left out by a platform filter
	// (Options.Platforms, FilterPlatforms).
	OmittedPlatforms []string `json:"omitted_platforms,omitempty"`
}

type Resolver struct {
	// contains filtered or unexported fields
}

type Stats struct {
	// ManifestGets are GET requests for manifests: the requests Docker Hub
	// counts against pull rate limits.
	ManifestGets int `json:"manifest_gets"`
	// ManifestHeads are HEAD requests for manifests (not counted by Docker
	// Hub).
	ManifestHeads int `json:"manifest_heads"`
	// BlobGets are GET requests for blobs. The resolver only ever fetches
	// image configs, never layers.
	BlobGets int `json:"blob_gets"`
	// TagLists are tags/list requests (one per page).
	TagLists int `json:"tag_lists"`
	// Other counts everything else (token and ping requests).
	Other int `json:"other"`
	// Redirects counts requests that follow a redirect (blob CDNs).
	Redirects int `json:"redirects"`
	// Retries counts requests repeated after a 429, a 5xx or a network error.
	Retries int `json:"retries"`
	// RateLimitRemaining is the last "ratelimit-remaining" header Docker Hub
	// sent ("95;w=21600"), if any.
	RateLimitRemaining string `json:"rate_limit_remaining,omitempty"`
}

type Verdict string