Documentation
¶
Index ¶
- func IsLoopbackHost(host string) bool
- type CargoMatcher
- type CompositeMatcher
- type GemMatcher
- type Match
- type Matcher
- type MavenMatcher
- type MavenMirrors
- type NPMMatcher
- type NuGetMatcher
- type Option
- func WithBlockNotice(notice policy.Logf) Option
- func WithUpstreamFailureWarning(warn policy.Logf) Option
- func WithUpstreamProxy(proxyFunc func(*http.Request) (*url.URL, error)) Option
- func WithUpstreamProxyCertificate(cert tls.Certificate) Option
- func WithUpstreamProxyFor(scheme string, proxyFunc func(*http.Request) (*url.URL, error)) Option
- func WithUpstreamRootCAs(pool *x509.CertPool) Option
- func WithVerdictHook(fn func(verdict.Entry)) Option
- type Proxy
- type PyPIMatcher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsLoopbackHost ¶ added in v1.129.0
IsLoopbackHost reports whether host is localhost or a loopback address, a superset of the hosts Maven treats as local (localhost and 127.0.0.1).
Types ¶
type CargoMatcher ¶ added in v1.119.0
type CargoMatcher struct {
// contains filtered or unexported fields
}
CargoMatcher recognizes crate downloads and publishes. Downloads take two shapes: the legacy registry API path ("/api/v1/crates/{crate}/{version}/download") and the sparse-index download of a "{crate}-{version}.crate" file (default since cargo 1.70). The sparse download URL is defined by the registry's config.json "dl" template and so varies by registry (crates.io serves "static.crates.io/crates/{crate}/{crate}-{version}.crate"; third parties such as Artifactory and Cloudsmith use their own path layouts), but the requested file is always named "{crate}-{version}.crate". Matching on that ".crate" filename keeps the matcher working behind third-party registries.
Publishes are PUT "/api/v1/crates/new". The publish body is a length-prefixed frame: [u32 LE json_len]json[u32 LE crate_len][.crate]; the JSON carries the name and vers.
type CompositeMatcher ¶ added in v1.131.0
type CompositeMatcher []Matcher
CompositeMatcher runs several ecosystem matchers against a request and returns the first that recognizes it as in-scope. It lets one long-lived proxy cover every supported ecosystem at once — as the job-level `glab dependency-firewall job-proxy` does — instead of the per-run model where each package-manager command installs a single ecosystem's matcher.
The first Matched result wins and short-circuits, so a matcher that reads an upload body is never run once an earlier matcher has already claimed the request. A request no matcher claims passes straight through (Matched false), exactly as a single matcher's non-match does.
func DefaultMatchers ¶ added in v1.131.0
func DefaultMatchers() CompositeMatcher
DefaultMatchers returns one matcher per supported ecosystem, for a job-level proxy that must recognize artifacts from any of them. The managers' own Matcher() methods return these same zero-value structs; listing them once here avoids running the npm (or PyPI) matcher several times for its family of managers (npm/pnpm/yarn; pip/poetry/uv/twine/pipenv).
type GemMatcher ¶ added in v1.117.0
type GemMatcher struct{}
GemMatcher recognizes RubyGems downloads ("/gems/<name>-<version>.gem") and pushes (POST "/api/v1/gems"). The push body carries the gem binary, so the upload coordinate has an empty Name/Version; the checker still receives an Upload request for a package-level decision.
type Match ¶ added in v1.116.0
type Match struct {
Matched bool
Coordinate policy.Coordinate
Operation policy.Operation
Pass bool
Reason string
// Alternates are other coordinates the same request could denote, since a
// mirror's path prefix can leave the real coordinate ambiguous.
Alternates []policy.Coordinate
}
Match is the result of running a Matcher against a request. When Matched is false the request is metadata/index/sidecar traffic that passes straight through. When Matched is true the request is an in-scope artifact download or upload.
Pass gates the policy check and is deliberately fail-closed: only a matched request whose Coordinate the matcher fully determined sets Pass true and is forwarded to the policy checker. A matched request that leaves Pass false — because the matcher recognized an in-scope upload but could not determine the coordinate (for example an upload body larger than the inspection limit), or simply forgot to set the field — is rejected outright by the proxy rather than letting an un-inspectable payload through. Reason carries the operator message for that synthesized block.
type Matcher ¶ added in v1.116.0
Matcher inspects an intercepted request and reports whether it carries an exact package coordinate (an artifact download or an upload). Each ecosystem implements one, keyed off the public-upstream URL/body shape. Implementations that read an upload body MUST restore req.Body so the upstream RoundTrip still sees the full payload.
type MavenMatcher ¶ added in v1.117.0
type MavenMatcher struct {
// Mirrors, when it knows them, are the mirror URLs Maven downloads
// through; without them every prefix a mirror could add is tried.
Mirrors *MavenMirrors
}
MavenMatcher recognizes Maven artifact downloads and uploads against a public Maven upstream (repo.maven.apache.org and mirrors). The path shape is ".../<group/path>/<artifact>/<version>/<artifact>-<version>.<ext>", where the group's dots are path segments. Enforcement targets the primary artifacts listed in mavenPrimaryExts (.jar, .pom, .aar, .war); checksum and signature sidecars pass through.
type MavenMirrors ¶ added in v1.129.0
type MavenMirrors struct {
// contains filtered or unexported fields
}
MavenMirrors holds the mirror URLs Maven sends every repository download through, once they are known, so MavenMatcher can read a download under one exactly instead of trying every prefix a mirror could have added. The zero value knows no mirrors. It is safe for concurrent use.
func (*MavenMirrors) Set ¶ added in v1.129.0
func (m *MavenMirrors) Set(urls []*url.URL, externalOnly bool)
Set makes downloads under urls match exactly. externalOnly reports that the catch-all mirror is external:*, so a request to a loopback host may come from a repository Maven didn't mirror and is left to enumeration.
type NPMMatcher ¶ added in v1.116.0
type NPMMatcher struct {
// contains filtered or unexported fields
}
NPMMatcher recognizes npm artifact tarball downloads and publish uploads against the public npm registry (registry.npmjs.org) or any npm-protocol upstream with the same URL shape.
type NuGetMatcher ¶ added in v1.124.0
type NuGetMatcher struct {
// contains filtered or unexported fields
}
NuGetMatcher recognizes NuGet v3 flatcontainer artifact downloads (".../{id}/{version}/{id}.{version}.nupkg") and pushes: a multipart PUT carrying a .nupkg or .snupkg. Each server advertises its own push URL in its service index, so pushes are recognized by body rather than by path. A .nupkg download outside the flatcontainer shape, such as a nuget.org v2 CDN URL, fails closed.
Download coordinates carry the id and version lowercased, as the flatcontainer path spells them; push coordinates keep the casing in the package's nuspec.
type Option ¶
type Option func(*Proxy)
Option configures a Proxy at construction time.
func WithBlockNotice ¶ added in v1.131.0
WithBlockNotice sets where the proxy reports each package it blocks, at the moment it blocks it, so the reason appears next to the package manager's own failure rather than only in the summary after it exits.
func WithUpstreamFailureWarning ¶ added in v1.128.0
WithUpstreamFailureWarning sets where the proxy reports a failed upstream registry request. It reports each registry authority at most once per proxy. When unset, failures are only debug-logged.
func WithUpstreamProxy ¶ added in v1.128.0
WithUpstreamProxy overrides how the proxy picks an outbound proxy for each upstream registry request. When unset, it uses upstreamProxyFromEnvironment.
func WithUpstreamProxyCertificate ¶ added in v1.131.0
func WithUpstreamProxyCertificate(cert tls.Certificate) Option
WithUpstreamProxyCertificate presents cert on the TLS handshake with an https:// outbound proxy that requires a client certificate. Registries never receive it, and the proxy is still verified against the upstream roots.
func WithUpstreamProxyFor ¶ added in v1.129.0
WithUpstreamProxyFor overrides the outbound proxy for upstream registry requests whose URL has the given scheme, such as a package manager's own proxy setting. Requests with any other scheme keep the proxy picked before.
func WithUpstreamRootCAs ¶
WithUpstreamRootCAs overrides the certificate pool the proxy uses to verify the upstream registry's TLS certificate, and the certificate of an https:// outbound proxy in front of it. When unset, the proxy verifies against the system trust store.
func WithVerdictHook ¶ added in v1.131.0
WithVerdictHook registers fn to be called once per newly recorded verdict, as it is recorded and before any blocked response is written to the client. The job-level proxy uses it to append each verdict to the CI log synchronously, so a `ci-summary` that runs immediately after a blocked install still sees the block. fn runs on a tunnel goroutine, must be safe for concurrent use, and must not call back into the proxy.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
func (*Proxy) CACertificate ¶
func (p *Proxy) CACertificate() *x509.Certificate
type PyPIMatcher ¶ added in v1.117.0
type PyPIMatcher struct {
// contains filtered or unexported fields
}
PyPIMatcher recognizes PyPI artifact downloads (wheels/sdists served from files.pythonhosted.org) and twine uploads (POST multipart to upload.pypi.org/legacy/).