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
- type AVResult
- type AVScanner
- type ArtifactCache
- type ArtifactEntry
- type CVEFinding
- type CVEScanner
- type DownloadMetadataExtractor
- type Event
- type FilterResult
- type PackageMetadata
- type PackageRef
- type PolicyDecider
- type PolicyDecision
- type Recorder
- type RegistryAdapter
- type SCFilter
- type ScanResult
- type Severity
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.
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 ¶
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 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.
func ParseSeverity ¶
ParseSeverity converts an OSV/NVD severity string to Severity. "MODERATE" (OSV) is mapped to SeverityMedium.