Documentation
¶
Overview ¶
Package dockerproxy implements a pull-through Docker Registry V2 proxy that gates images on Trivy (CVE/secrets) and ClamAV (signature malware) before serving them. It is isolated from proxy.Handler and reuses Jōei's existing policy, supply-chain, cache, and telemetry subsystems via their interfaces.
Index ¶
- func New(d HandlerDeps) http.Handler
- type Adapter
- func (a *Adapter) FetchBlob(ctx context.Context, repo, digest string) (io.ReadCloser, int64, error)
- func (a *Adapter) FetchManifest(ctx context.Context, repo, ref string) ([]byte, string, string, error)
- func (a *Adapter) ImageConfig(ctx context.Context, repo string, manifestBody []byte) (created time.Time, configDigest string, layers []string, err error)
- func (a *Adapter) ResolveDigest(ctx context.Context, repo, ref string) (string, error)
- type Config
- type GateVerdict
- type Handler
- type HandlerDeps
- type ImageScanResult
- type ImageScanner
- type ParsedPath
- type RequestKind
- type Revalidator
- type TrivyScanner
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(d HandlerDeps) http.Handler
New assembles a ready-to-serve Docker Registry V2 proxy handler.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter talks to upstream Docker registries, handling bearer-token auth. It is safe for concurrent use.
func NewAdapter ¶
NewAdapter creates an Adapter over the given ordered upstream base URLs (e.g. "https://registry-1.docker.io"). Trailing slashes are trimmed. A nil client uses a private one with a 120s timeout; pass a shared client whose transport caps per-host concurrency to keep registry requests under the rate limit.
func (*Adapter) FetchBlob ¶
FetchBlob opens a blob (config or layer) stream from the first working upstream. The caller must close the returned ReadCloser.
func (*Adapter) FetchManifest ¶
func (a *Adapter) FetchManifest(ctx context.Context, repo, ref string) ([]byte, string, string, error)
FetchManifest fetches the raw manifest for ref (a tag or digest) and returns its body, content type, and canonical digest. A multi-arch index is returned as-is, NOT resolved to a platform: the Docker client performs platform selection itself by requesting the concrete child manifest by digest, which the proxy then gates on its own. This guarantees the image the client actually pulls is the one scanned, on any host architecture.
func (*Adapter) ImageConfig ¶
func (a *Adapter) ImageConfig(ctx context.Context, repo string, manifestBody []byte) (created time.Time, configDigest string, layers []string, err error)
ImageConfig parses a schema2/OCI manifest, fetches its config blob, and returns the image's created time, the config blob digest, and the ordered layer digests. The config digest is returned so the caller can cache the config blob alongside the layers (required for docker pull to succeed).
type Config ¶
type Config struct {
Adapter *Adapter
Gate *manifestGate
Store *verdictStore
Tags *tagIndex
Recorder gate.Recorder
Logger zerolog.Logger
}
Config groups the Docker proxy handler dependencies.
type GateVerdict ¶
type GateVerdict struct {
Allowed bool
Reason string // "ok" | "index_passthrough" | "attestation_passthrough" | "cve_found" | "denylisted" | "malware_found" | supply-chain reason
BlockedBy string // "supply_chain" | "cve" | "denylist" | "malware" (empty when allowed)
Findings []gate.CVEFinding
ManifestPath string // cached manifest body (allowed only)
ContentType string
PublishedAt time.Time
BlockUntil time.Time // non-zero only for supply-chain holds (drives the quarantine view)
// Passthrough is true when the served manifest was not gated because it has
// no scannable image content (a multi-arch index, or an attestation
// manifest). The real image content is gated when the client requests the
// concrete platform image manifest by digest.
Passthrough bool
// FromCache is true when this verdict was served from a previously cached
// gate decision rather than freshly evaluated. The handler records it as a
// CACHE event so repeat pulls are distinguishable from first-time passes.
FromCache bool
}
GateVerdict is the per-image decision produced by the manifest gate.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler implements the Docker Registry V2 pull-through flow.
type HandlerDeps ¶
type HandlerDeps struct {
Upstreams []string
Scanner ImageScanner
AV gate.AVScanner
Filter gate.SCFilter
Policy gate.PolicyDecider
Cache cache.Cache
MaxLayerBytes int64
Recorder gate.Recorder
Logger zerolog.Logger
// HTTPClient talks to the upstream registry. Optional; nil uses a private
// client with a 120s timeout. Pass a client whose transport caps per-host
// concurrency (shared with the other registries) to avoid 429 throttling.
HTTPClient *http.Client
}
HandlerDeps is the public assembly input for the Docker proxy handler.
type ImageScanResult ¶
type ImageScanResult struct {
Findings []gate.CVEFinding
}
ImageScanResult holds the vulnerability findings for a scanned image.
type ImageScanner ¶
type ImageScanner interface {
ScanImage(ctx context.Context, imageRef string) (*ImageScanResult, error)
Health() health.Sample
}
ImageScanner scans a container image for vulnerabilities/secrets. imageRef is "<host>/<repo>@<digest>". Implementations must be safe for concurrent use and expose a passive health sample for the console.
type ParsedPath ¶
type ParsedPath struct {
Kind RequestKind
Repo string
Reference string
}
ParsedPath is the result of classifying a V2 path (with the /v2 mux prefix already stripped). Repo may contain slashes; Reference is a tag or digest.
func ParsePath ¶
func ParsePath(p string) ParsedPath
ParsePath classifies a Docker Registry V2 path. The input is the path after the mux has stripped the "/v2" prefix (e.g. "/library/nginx/manifests/latest" or "/" for the ping endpoint).
type RequestKind ¶
type RequestKind int
RequestKind classifies a Docker Registry V2 request.
const ( KindUnknown RequestKind = iota KindPing // GET /v2/ KindManifest // GET|HEAD /v2/<repo>/manifests/<ref> KindBlob // GET /v2/<repo>/blobs/<digest> KindTagList // GET /v2/<repo>/tags/list )
type Revalidator ¶
type Revalidator struct {
// contains filtered or unexported fields
}
Revalidator re-validates cached Docker entries by re-running the manifest gate. It implements revalidate.Revalidator.
func NewRevalidator ¶
func NewRevalidator(d HandlerDeps) *Revalidator
NewRevalidator builds a Docker revalidator sharing the same upstreams, scanners, and cache as the live handler (HandlerDeps).
func (*Revalidator) Revalidate ¶
func (r *Revalidator) Revalidate(ctx context.Context, e cache.RevalEntry) (revalidate.Outcome, *revalidate.EvictReason)
Revalidate re-runs the gate for an image-verdict entry. Standalone blob entries are owned by their image and re-validated transitively, so they are a no-op.
type TrivyScanner ¶
type TrivyScanner struct {
// contains filtered or unexported fields
}
TrivyScanner runs the `trivy` CLI in client/server mode against a sidecar `trivy server` that holds the vulnerability DB. It implements ImageScanner.
func NewTrivyScanner ¶
func NewTrivyScanner(serverURL, scanners string, timeout time.Duration) *TrivyScanner
NewTrivyScanner creates a scanner that shells out to the real trivy binary.
func NewTrivyScannerWithRunner ¶
func NewTrivyScannerWithRunner(serverURL, scanners string, timeout time.Duration, run commandRunner) *TrivyScanner
NewTrivyScannerWithRunner is NewTrivyScanner with an injectable command runner.
func (*TrivyScanner) Health ¶
func (s *TrivyScanner) Health() health.Sample
Health reports the outcome of the last scan as a passive sample.
func (*TrivyScanner) Probe ¶
func (s *TrivyScanner) Probe(ctx context.Context) error
Probe checks Trivy server liveness via its /healthz endpoint (returns "ok" with HTTP 200). Unlike `trivy version`, this is a real round-trip to the server, so the reported status and latency reflect actual reachability.
func (*TrivyScanner) ScanImage ¶
func (s *TrivyScanner) ScanImage(ctx context.Context, imageRef string) (*ImageScanResult, error)
ScanImage runs trivy against imageRef and maps findings to gate.CVEFinding.