dockerproxy

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 20, 2026 License: MIT Imports: 17 Imported by: 0

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

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

func NewAdapter(upstreams []string, client *http.Client) *Adapter

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

func (a *Adapter) FetchBlob(ctx context.Context, repo, digest string) (io.ReadCloser, int64, error)

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).

func (*Adapter) ResolveDigest

func (a *Adapter) ResolveDigest(ctx context.Context, repo, ref string) (string, error)

ResolveDigest HEADs the manifest and returns the canonical content digest.

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.

func NewHandler

func NewHandler(cfg Config) *Handler

NewHandler creates a Docker proxy handler.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

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
	// RecheckTTL: cached image verdicts older than this are re-evaluated by the
	// full gate on the next pull (0 = never expire). Wire min of the enabled
	// per-gate TTLs.
	RecheckTTL time.Duration
	// 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 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL