Documentation
¶
Overview ¶
Package pm runs a supported package manager (npm, pip, gem, ...) behind the Dependency Firewall's local MITM proxy. The shared Run flow starts the proxy, routes the manager's HTTPS traffic through it, makes the manager trust the proxy CA, passes through the command's args, records the firewall's per-coordinate verdicts to the CI log, renders a summary, and propagates the child's exit code. Each supported manager is a small implementation of PackageManager describing only what varies by ecosystem.
Index ¶
- func JVMTrustOpts(caPath string) string
- func MavenJobArgsEnv(path, proxyURL string, warnf func(format string, args ...any)) (string, error)
- func OwnProxyConfigFiles(manager PackageManager) []string
- func OwnProxyHelpNote(manager PackageManager) string
- func OwnProxyVariables(manager PackageManager) []string
- func PlainHTTPUsesHTTPSProxy(manager PackageManager) bool
- func Run(ctx context.Context, manager PackageManager, opts RunOptions) error
- func UpstreamProxyCertificateOptions(certPath, keyPath string, password func() (string, error)) ([]proxy.Option, error)
- func UpstreamRootCAs(env []string, caCertPath string) (*x509.CertPool, error)
- type Executor
- type ExitError
- type PackageManager
- func Bundle() PackageManager
- func Cargo() PackageManager
- func Gem() PackageManager
- func Golang() PackageManager
- func Gradle() PackageManager
- func Maven() PackageManager
- func NPM() PackageManager
- func Pip() PackageManager
- func Pipenv() PackageManager
- func Pnpm() PackageManager
- func Poetry() PackageManager
- func Twine() PackageManager
- func Uv() PackageManager
- func Yarn() PackageManager
- type RunOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JVMTrustOpts ¶ added in v1.131.0
JVMTrustOpts reads the PEM CA bundle at caPath, writes a PKCS#12 truststore at caPath+".p12" (which Run cleans up), and returns the JVM truststore flags as a single space-joined string, prepending any value already in MAVEN_OPTS. It returns "" when the CA bundle has no parsable certificates.
func MavenJobArgsEnv ¶ added in v1.131.0
MavenJobArgsEnv returns the MAVEN_ARGS entry that routes every mvn in a job through the proxy at proxyURL. It writes, at path, the install's global settings with the proxy entries merged in and passes them as -gs, so the image's global mirrors still apply and a job's own -s still layers on top. When the global settings can't be resolved or merged, the file holds only the proxy entries and warnf says why, because the install's mirrors, proxies and credentials then stop applying. No mvn on PATH is not reported: it is the normal case for a job that doesn't use Maven.
func OwnProxyConfigFiles ¶ added in v1.131.0
func OwnProxyConfigFiles(manager PackageManager) []string
OwnProxyConfigFiles lists the user and global config files of manager's own that glab reads proxy settings from, or nil when it reads none. glab skips any of them that is inside the project being installed.
func OwnProxyHelpNote ¶ added in v1.131.0
func OwnProxyHelpNote(manager PackageManager) string
OwnProxyHelpNote returns what the help for manager's proxy settings must add, such as settings that only some of its versions use, or "".
func OwnProxyVariables ¶ added in v1.129.0
func OwnProxyVariables(manager PackageManager) []string
OwnProxyVariables lists the proxy variables of manager's own that glab reads ahead of HTTPS_PROXY and HTTP_PROXY, or nil when it reads none.
func PlainHTTPUsesHTTPSProxy ¶ added in v1.129.0
func PlainHTTPUsesHTTPSProxy(manager PackageManager) bool
PlainHTTPUsesHTTPSProxy reports whether manager sends plain-HTTP requests through HTTPS_PROXY ahead of HTTP_PROXY, as npm and pnpm do.
func Run ¶
func Run(ctx context.Context, manager PackageManager, opts RunOptions) error
Run executes manager.Binary() with args forwarded verbatim, routing HTTPS traffic through a local MITM proxy that policy-checks each artifact/upload coordinate. Blocked packages are recorded and the summary is rendered on exit.
func UpstreamProxyCertificateOptions ¶ added in v1.131.0
func UpstreamProxyCertificateOptions(certPath, keyPath string, password func() (string, error)) ([]proxy.Option, error)
UpstreamProxyCertificateOptions returns the option that presents glab's client_cert to an https:// outbound proxy that requires one, loading it the way the API client does. It returns no option when certPath is empty or names no certificate. Run and the job-level proxy both use it, so the two load the certificate the same way.
func UpstreamRootCAs ¶ added in v1.131.0
UpstreamRootCAs is upstreamRootCAs for the job-level proxy, which has no single manager but must trust the same registry CAs as a per-command run. The job-level proxy needs only the pool, so the PEM return is dropped here.
Types ¶
type Executor ¶
type Executor interface {
LookPath(file string) (string, error)
ExecWithIO(ctx context.Context, name string, args []string, env []string, stdin io.Reader, stdout, stderr io.Writer) error
}
Executor runs the package-manager binary. Satisfied by cmdutils.Executor.
type ExitError ¶
type ExitError struct {
Code int
Err error
// ChildExited is true only when the package-manager child process
// actually ran and exited non-zero (an *exec.ExitError). It is false
// when the child never ran (e.g. not found on PATH, fork/exec failure)
// or when the run was interrupted. Callers use this to decide whether a
// rendered summary already explains the failure: only a real child exit
// may be silenced.
ChildExited bool
}
ExitError reports that the package-manager binary exited non-zero, was interrupted, or could not be run, carrying the exit Code the process should return. pm is a library package and must not import internal/cmdutils (command-layer only, enforced by depguard), so the calling command translates this into a *cmdutils.ExitError; see dfcmd.run.
type PackageManager ¶
type PackageManager interface {
// Name is the CLI noun and log key: "npm", "pip", "maven".
Name() string
// Binary is the executable looked up on PATH.
Binary() string
// Environment returns child-process env vars that route the manager's
// HTTPS traffic through proxyURL. The parent env (with proxy vars
// sanitized) is supplied by Run via proxyEnviron.
Environment(proxyURL string) []string
// CATrustEnviron returns the env vars that make the manager trust the
// proxy's MITM CA at caPath (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE,
// PIP_CERT/REQUESTS_CA_BUNDLE, MAVEN_OPTS truststore, etc.).
CATrustEnviron(caPath string) []string
// ExistingBundleVars names every environment variable this manager's
// CATrustEnviron overwrites that could hold a user's pre-existing CA
// bundle (e.g. NODE_EXTRA_CA_CERTS, PIP_CERT and REQUESTS_CA_BUNDLE,
// SSL_CERT_FILE and BUNDLE_SSL_CA_CERT), so the engine can prepend those
// trust anchors to the proxy CA rather than replacing them. Every variable
// CATrustEnviron sets must appear here, or a user who set only the
// undeclared one loses their anchors and can no longer verify an internal
// index/mirror. An empty slice means the manager has no such variable to
// preserve (e.g. Maven, which trusts the proxy through a generated
// truststore rather than an env-named bundle).
ExistingBundleVars() []string
// CleanupCAFiles removes any files this manager derived from the CA
// bundle at caPath (for example a JVM truststore or a generated
// settings.xml). The engine always removes caPath itself; this covers
// ecosystem-specific sidecars the engine would otherwise not know about.
CleanupCAFiles(caPath string)
// Matcher returns the proxy coordinate matcher for this ecosystem's
// upstream URL shape.
Matcher() proxy.Matcher
}
PackageManager captures what varies between supported package managers so the shared run flow (proxy + exec + log + summary) is written once. In the upstream-MITM model managers no longer rewrite their own config: they route traffic through the proxy (Environment), trust the proxy CA (CATrustEnviron), and supply the coordinate matcher for their ecosystem (Matcher).
func Golang ¶ added in v1.126.0
func Golang() PackageManager
Golang returns the go package manager. Module zips are checked by a loopback Go module proxy rather than the MITM proxy: go and git on macOS trust only the system store, so they reject the MITM CA.
func Gradle ¶ added in v1.118.0
func Gradle() PackageManager
Gradle returns a fresh gradle package manager.
func Maven ¶ added in v1.118.0
func Maven() PackageManager
Maven returns a fresh maven package manager (it stashes the proxy URL from Environment for CATrustEnviron to build the settings.xml and truststore).
func Pnpm ¶
func Pnpm() PackageManager
Pnpm returns the pnpm package manager. pnpm honors HTTPS_PROXY and NODE_EXTRA_CA_CERTS the same as npm, so it differs only in name/binary.
func Yarn ¶
func Yarn() PackageManager
Yarn returns the Yarn (Berry) package manager. It routes through the proxy via YARN_HTTP(S)_PROXY and trusts the proxy CA via NODE_EXTRA_CA_CERTS.
Berry's per-host networkSettings override the global proxy and cannot be pinned from the environment, so Setup also injects a plugin (yarnplugin.cjs) through YARN_PLUGINS that empties them before each request.
type RunOptions ¶
type RunOptions struct {
IO *iostreams.IOStreams
Executor Executor
BaseDir string
Client *gitlab.Client // authenticated API client, for the policy checker
ProjectID string // project id or full-path slug, for policy scoping
Args []string
// CACertPath is glab's ca_cert for the GitLab host. Registry connections
// trust it in addition to the system roots.
CACertPath string
// ClientCertPath, ClientKeyPath and ClientCertPassword are glab's client_cert,
// client_key and client_cert_password for the GitLab host. The certificate is
// presented to an https:// outbound proxy that requires one, never to a registry.
ClientCertPath string
ClientKeyPath string
ClientCertPassword func() (string, error)
// contains filtered or unexported fields
}
RunOptions are the inputs to Run. Registry/token fields are gone: the model no longer talks to a GitLab registry.