gate

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package gate holds Jōei's domain vocabulary: the types that describe packages, scan results, verdicts, and telemetry events, and the ports (interfaces) implemented by registry adapters, scanners, the policy engine, the artifact cache, and telemetry. It imports nothing but the standard library; every other package depends inward on it.

Index

Constants

View Source
const (
	VerdictPass  = "PASS"
	VerdictCache = "CACHE"
	VerdictBlock = "BLOCK"
	VerdictError = "ERROR"
)

Verdict values recorded for an intercepted request.

View Source
const (
	GateCache     = "cache"
	GateSupply    = "supply"
	GateCVE       = "cve"
	GateMalware   = "malware"
	GateImageScan = "image_scan"
)

Gate identifiers. For BLOCK events: the gate that blocked. For ERROR events: the stage that failed. For PASS events: the deepest gate the artifact cleared.

View Source
const ReasonDenylisted = "denylisted"

ReasonDenylisted is the block reason produced by the policy engine for denylisted packages; telemetry counts it separately from CVE blocks.

Variables

This section is empty.

Functions

This section is empty.

Types

type AVResult

type AVResult struct {
	Clean     bool   // true iff no malware signature matched
	Signature string // signature name when infected, "" otherwise
	Engine    string // engine that produced this verdict, e.g. "clamav" | "icap"
}

AVResult records the outcome of an antivirus scan of a single file.

type AVScanner

type AVScanner interface {
	Scan(ctx context.Context, filePath string) (*AVResult, error)
}

AVScanner scans a file on disk for malware. Implementations must be safe for concurrent use.

type ArtifactCache

type ArtifactCache interface {
	Get(ref *PackageRef) (*ArtifactEntry, bool)
	Put(ref *PackageRef, tmpPath string, scanClean bool, scanJSON string) error
	Invalidate(ref *PackageRef) error
	// MarkCVEChecked / MarkMalwareChecked record a passed lazy re-check at ts.
	MarkCVEChecked(ref *PackageRef, ts time.Time) error
	MarkMalwareChecked(ref *PackageRef, ts time.Time) error
}

ArtifactCache is the storage interface used by the proxy handler. The real cache backends satisfy it via cache.AsArtifactCache.

type ArtifactEntry

type ArtifactEntry struct {
	// ArtifactPath is the absolute path to the cached file on disk.
	ArtifactPath string
	// ScanClean is true if all scanners passed.
	ScanClean bool
	// LastCVECheck / LastMalwareCheck record when each gate last confirmed the
	// entry clean; the handler re-runs a gate when its TTL has lapsed.
	LastCVECheck     time.Time
	LastMalwareCheck time.Time
}

ArtifactEntry is a minimal view of a cached artifact, avoiding an import cycle with the cache package (which itself imports gate for PackageRef).

type CVEFinding

type CVEFinding struct {
	ID       string   // canonical ID (CVE-YYYY-NNNNN or advisory ID if no CVE alias)
	Aliases  []string // other IDs (GHSA-…, PYSEC-…, etc.)
	Severity Severity
	Summary  string
	Score    float64 // CVSS score, 0 if unavailable
}

CVEFinding represents a single vulnerability found in a package.

type CVEScanner

type CVEScanner interface {
	Scan(ctx context.Context, ref *PackageRef) (*ScanResult, error)
}

CVEScanner scans a package for known vulnerabilities. Implementations must be safe for concurrent use.

type DownloadMetadataExtractor

type DownloadMetadataExtractor interface {
	MetadataFromHeader(h http.Header) *PackageMetadata
}

DownloadMetadataExtractor is an optional RegistryAdapter capability: deriving PackageMetadata (notably the publish date) from the artifact download response headers. When an adapter implements it, the handler obtains the supply-chain date from the download itself and runs the supply-chain check after fetching the artifact — avoiding a separate metadata request. Maven implements this (the artifact's Last-Modified is the publish-date proxy), so a pull is one GET instead of a HEAD + GET. Adapters whose publish date comes from a distinct metadata API (PyPI, npm) do not implement it and are checked before download via FetchMetadata as before.

type Event

type Event struct {
	RequestID  string
	Time       time.Time // outcome timestamp (request arrival = Time - LatencyMS)
	Ecosystem  string
	Package    string
	Version    string
	Verdict    string // PASS | CACHE | BLOCK | ERROR
	Gate       string // cache | supply | cve | malware
	LatencyMS  int64
	HTTPStatus int
	Reason     string
	BlockedBy  []string // "supply_chain" | "cve" | "malware" | "denylist"

	// CVE block details.
	CVEs []CVEFinding

	// Malware block details.
	MalwareEngine    string
	MalwareSignature string

	// Supply-chain details (also set on PASS when metadata was fetched).
	PublishedAt time.Time
	BlockUntil  time.Time // non-zero only for supply-chain blocks
}

Event is one telemetry record per intercepted request outcome. Field semantics mirror the console's request objects (web/console).

type FilterResult

type FilterResult struct {
	Allowed     bool
	Reason      string // "ok" | "allowlisted" | "dry_run" | "off" | "package_younger_than_min_age"
	PublishedAt time.Time
	BlockUntil  time.Time // non-zero when Allowed=false
}

FilterResult describes the outcome of a supply chain check.

type FilteredDocument added in v0.5.0

type FilteredDocument struct {
	// Body is the document to serve. It is the input document itself, byte for
	// byte, when nothing was removed — which lets the caller forward the
	// upstream validators along with it.
	Body []byte
	// Removed lists the versions hidden from Body, sorted.
	Removed []string
	// AllRejected reports that policy rejected every version in the document.
	// Body is then the original: an empty version list would turn every install
	// of that package into a resolution error instead of a gate verdict, so the
	// artifact gate is left to state the real reason at download time.
	AllRejected bool
}

FilteredDocument is the result of rewriting a metadata document.

type MetadataFilterer added in v0.5.0

type MetadataFilterer interface {
	// NormalizeMetadataRequest reports whether r asks for a filterable metadata
	// document, and names the package it describes.
	NormalizeMetadataRequest(r *http.Request) (*MetadataRef, bool)

	// FilterVersions rewrites doc, dropping every version decide rejects.
	FilterVersions(doc []byte, decide VersionDecider) (FilteredDocument, error)
}

MetadataFilterer is an optional RegistryAdapter capability: rewriting a metadata document so that versions policy will not serve are absent from it, letting the client's own resolver pick an allowed version instead of failing on a blocked download. npm implements it; adapters whose clients resolve server-side do not.

type MetadataRef added in v0.5.0

type MetadataRef struct {
	Ecosystem string
	Name      string
}

MetadataRef names the package a metadata document describes. It is a PackageRef without a version, because the document covers every version.

type PackageMetadata

type PackageMetadata struct {
	PublishedAt time.Time
	Maintainer  string
	License     string
	Checksum    string // SHA256 hex
}

PackageMetadata contains resolved metadata from the upstream registry.

type PackageRef

type PackageRef struct {
	Ecosystem string // "pypi", "npm", "maven", "go"
	Name      string
	Version   string
	// Classifier distinguishes secondary artifacts that share the same
	// coordinates (Maven "sources"/"javadoc" jars, etc.). Empty for the main
	// artifact and for ecosystems without classifiers. It participates in the
	// cache key but not in CVE/supply-chain lookups, which key on Name+Version.
	Classifier string
}

PackageRef uniquely identifies a versioned package in an ecosystem.

func (PackageRef) Key

func (r PackageRef) Key() string

Key returns a stable cache/log key for this package reference. The classifier is appended only when non-empty, so main artifacts and non-maven ecosystems keep their historical keys (and existing cache entries stay valid).

type PolicyDecider

type PolicyDecider interface {
	Evaluate(ref *PackageRef, result *ScanResult) PolicyDecision
}

PolicyDecider evaluates a package against policy rules.

type PolicyDecision

type PolicyDecision struct {
	Allowed  bool
	Reason   string       // "ok" | "cve_found" | "denylisted" | "allowlisted_bypass"
	Findings []CVEFinding // findings that caused a block (empty if Allowed)
}

PolicyDecision is the result of evaluating a package against policy rules.

type Recorder

type Recorder interface {
	Record(Event)
}

Recorder receives telemetry events. Implementations must be safe for concurrent use and must never block or fail the proxy data path: Record returns nothing. telemetry.Hub satisfies it structurally.

type RegistryAdapter

type RegistryAdapter interface {
	// Name returns the ecosystem identifier, e.g. "pypi".
	Name() string

	// NormalizeRequest extracts a PackageRef from an incoming HTTP request.
	// Returns (ref, true) for download requests that should be intercepted.
	// Returns (nil, false) for metadata/simple-API requests (proxied as-is).
	NormalizeRequest(r *http.Request) (*PackageRef, bool)

	// FetchMetadata fetches version metadata from the upstream registry.
	FetchMetadata(ctx context.Context, ref *PackageRef) (*PackageMetadata, error)

	// UpstreamURLs returns one candidate upstream URL per configured upstream,
	// in priority order, for the given proxy request path.
	UpstreamURLs(r *http.Request) []string
}

RegistryAdapter abstracts a specific package registry.

type SCFilter

type SCFilter interface {
	Check(ctx context.Context, ref *PackageRef, meta *PackageMetadata) FilterResult
}

SCFilter is the interface the handler uses for supply chain checks. supplychain.Filter satisfies this interface.

type ScanResult

type ScanResult struct {
	Clean    bool         // true iff Findings is empty
	Findings []CVEFinding // all findings regardless of threshold
	ScanJSON string       // raw JSON for storage in cache audit log
}

ScanResult records the outcome of a CVE scan for a package version.

type Severity

type Severity int

Severity represents a CVE severity level.

const (
	SeverityUnknown Severity = iota
	SeverityLow
	SeverityMedium
	SeverityHigh
	SeverityCritical
)

func ParseSeverity

func ParseSeverity(s string) Severity

ParseSeverity converts an OSV/NVD severity string to Severity. "MODERATE" (OSV) is mapped to SeverityMedium.

func (Severity) AtLeast

func (s Severity) AtLeast(threshold Severity) bool

AtLeast reports whether s is at least as severe as threshold. SeverityUnknown is never at least anything (returns false).

func (Severity) String

func (s Severity) String() string

String returns the canonical string form of a Severity.

type VersionDecider added in v0.5.0

type VersionDecider func(version string, publishedAt time.Time) bool

VersionDecider reports whether one version of a package may be served. publishedAt is the zero time when the document carries no publish date for that version, which leaves any age-based rule mute.

Jump to

Keyboard shortcuts

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