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
- Variables
- type AVResult
- type AVScanner
- type ArtifactCache
- type ArtifactEntry
- type ArtifactPathMatcher
- type CVEFinding
- type CVEScanner
- type DownloadMetadataExtractor
- type Event
- type FilterResult
- type FilteredDocument
- type IndexRewrite
- type IndexRewriter
- type MetadataFilterer
- type MetadataRef
- type PackageMetadata
- type PackageRef
- type PolicyDecider
- type PolicyDecision
- type Recorder
- type RegistryAdapter
- type SCFilter
- type ScanResult
- type Severity
- type VersionDecider
Constants ¶
const ( VerdictPass = "PASS" VerdictCache = "CACHE" VerdictBlock = "BLOCK" VerdictError = "ERROR" )
Verdict values recorded for an intercepted request.
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.
const ReasonDenylisted = "denylisted"
ReasonDenylisted is the block reason produced by the policy engine for denylisted packages; telemetry counts it separately from CVE blocks.
const ReasonScanIncomplete = "scan_incomplete"
ReasonScanIncomplete is the block reason (and blocked_by value) when the malware engine could not scan an artifact in full: blocked, because it was not fully checked, but not reported as malware.
Variables ¶
var ErrNoServableVersions = errors.New("no version left with a rewritable download link")
ErrNoServableVersions means no version of a metadata document is left with a download link the proxy can route through its gates, so the document cannot be served at all.
Functions ¶
This section is empty.
Types ¶
type AVResult ¶
type AVResult struct {
Clean bool // true iff no malware signature matched and the scan was complete
Signature string // signature name when infected, "" otherwise
Engine string // engine that produced this verdict, e.g. "clamav" | "icap"
// Incomplete is set (with Clean false) when the engine could not scan the
// whole file — too many files, too deep, too large, too slow — rather
// than found malware. Callers that do not check it still block.
Incomplete bool
}
AVResult records the outcome of an antivirus scan of a single file.
type AVScanner ¶
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 ArtifactPathMatcher ¶ added in v1.0.0
ArtifactPathMatcher is an optional RegistryAdapter capability: recognising a request path as an artifact download even when NormalizeRequest cannot name the package and version in it. The handler refuses such a request instead of proxying it transparently, since an artifact it cannot name is an artifact no gate can check.
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, re-encoded with every download link
// pointing at the proxy.
Body []byte
// Removed lists the versions hidden from Body because policy rejects them,
// sorted.
Removed []string
// Unmappable lists the versions hidden from Body because their download
// link cannot be routed through the proxy, sorted.
Unmappable []string
// AllRejected reports that policy rejected every version in the document.
// Those versions then stay in Body: 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 IndexRewrite ¶ added in v1.0.0
type IndexRewrite struct {
Body []byte
// Rewritten counts links now pointing at the proxy.
Rewritten int
// Dropped lists absolute links that could not be pointed at the proxy and
// were removed instead.
Dropped []string
}
IndexRewrite is a rewritten index document.
type IndexRewriter ¶ added in v1.0.0
type IndexRewriter interface {
// IsIndexRequest reports whether r asks for an index document.
IsIndexRequest(r *http.Request) bool
// RewriteIndex points doc's download links at the proxy. requestPath is
// the registry-relative request path the links are resolved against, and
// contentType the upstream Content-Type. An error means the document
// cannot be made safe to serve.
RewriteIndex(doc []byte, contentType, requestPath string) (IndexRewrite, error)
}
IndexRewriter is an optional RegistryAdapter capability for registries whose index documents link downloads by absolute URL (PyPI links every file on files.pythonhosted.org). Served untouched, such an index sends the client straight to the file host and around every gate, so the proxy serves it only rewritten, and fails the request when it cannot rewrite it.
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 and
// pointing every download link under linkBase (the proxy's client-facing
// URL for this registry, without a trailing slash). A single-version
// manifest (ref.Version set) is rewritten but not filtered. An error means
// the document cannot be served.
FilterVersions(doc []byte, ref *MetadataRef, decide VersionDecider, linkBase string) (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, and so that every download link points at the proxy rather than around it. 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
// Version is empty for a document covering every version (an npm
// packument), and names the requested version or dist-tag for a
// single-version manifest.
Version string
}
MetadataRef names the package a metadata document describes.
type PackageMetadata ¶
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. Observation buffers may drop and count incoming events when full or closed; losing an observation must never change checks or authorize an artifact.
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.
func ParseSeverity ¶
ParseSeverity converts an OSV/NVD severity string to Severity. "MODERATE" (OSV) is mapped to SeverityMedium.
type VersionDecider ¶ added in v0.5.0
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.