// 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, forwards 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. package pm import ( "context" "crypto/x509" "encoding/pem" "errors" "fmt" "io" "os" "os/exec" "os/signal" "strings" "sync" "syscall" gitlab "gitlab.com/gitlab-org/api/client-go/v3" "gitlab.com/gitlab-org/cli/internal/api" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/cilog" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/fsx" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/policy" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/proxy" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/summary" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/verdict" "gitlab.com/gitlab-org/cli/internal/iostreams" ) // 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). 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 } // setupManager lets a manager prepare the run. Run fails the run without // starting the child when Setup errors, and calls stop exactly once, after // the child and the MITM proxy stop and before it reads verdicts. type setupManager interface { Setup(ctx context.Context, in setupInput) (setupResult, error) } // argsManager receives the arguments destined for the package manager binary. // Run calls SetArgs before it builds the child environment, for managers whose // environment depends on what the caller asked for (Maven, whose settings file // can be named on the command line). type argsManager interface { SetArgs(args []string) } // argsRewriter takes options out of the arguments before the package manager // binary runs with them. Run reads the upstream proxy from the arguments as // given, so an option there can still choose it. type argsRewriter interface { rewriteArgs(args []string) []string } type setupInput struct { parent []string // the environment the child would otherwise inherit caPath string bin string // the manager binary's path from LookPath exec Executor checker policy.Checker projectID string io *iostreams.IOStreams upstreamCAs []byte // PEM of the extra registry CAs from upstreamRootCAs; nil means none } type setupResult struct { env []string stop func() verdicts func() []verdict.Entry } // upstreamTrustManager lets a manager add the trust anchors its own runtime // would use on registry connections, such as a JVM truststore. env is the // environment glab was started with, before Run adds any variables for the // child; dir and args are the run's working directory and forwarded args. The // error is a warning, not a failure: a configured store that contributes // nothing, or an option that replaces glab's truststore in the child. It may // be an errors.Join of several; Run prints one line per joined error. type upstreamTrustManager interface { upstreamTrustAnchors(env []string, dir string, args []string) ([]*x509.Certificate, error) } // proxyEnviron returns parent with any caller-supplied proxy variables removed // and the inspection proxy set for HTTPS traffic only. managerKeys are the // env-var names the manager's own Environment sets (e.g. NPM_CONFIG_HTTPS_PROXY // for npm); they are stripped from the inherited env here so the engine stays // manager-agnostic — it does not hardcode any ecosystem's routing variables. func proxyEnviron(parent []string, proxyURL string, managerKeys ...string) []string { proxyKeys := map[string]struct{}{ "HTTP_PROXY": {}, "HTTPS_PROXY": {}, // NO_PROXY must be stripped too: managers (and the Go/Node/curl HTTP // stacks) honor it, so an inherited NO_PROXY= or NO_PROXY=* // (common in CI images) would route traffic straight past the MITM // proxy — no coordinates matched, no verdicts, a silent fail-open. The // firewall fails closed everywhere else, so it must here too. "NO_PROXY": {}, } for _, k := range managerKeys { proxyKeys[strings.ToUpper(k)] = struct{}{} } env := make([]string, 0, len(parent)+2) for _, e := range parent { key, _, _ := strings.Cut(e, "=") if _, skip := proxyKeys[strings.ToUpper(key)]; skip { continue } env = append(env, e) } // Point both HTTP_PROXY and HTTPS_PROXY at the inspection proxy. HTTPS is // the normal path (registries have served over HTTPS for years). HTTP_PROXY // is set — not merely stripped — because the registry URL is // repo-controlled: a committed ".npmrc registry=http://mirror/" (or the // equivalent for any ecosystem) would otherwise fetch over plain HTTP, // consult an absent HTTP_PROXY, and connect directly with zero inspection // on a green job. Through the proxy, a plaintext fetch is checked against // policy like any other. // Manager-specific routing variables are re-added by the manager's // Environment, appended by Run after this call. return append(env, "HTTP_PROXY="+proxyURL, "HTTPS_PROXY="+proxyURL) } // envKeys returns the KEY names from a "KEY=value" environment slice. func envKeys(env []string) []string { keys := make([]string, 0, len(env)) for _, e := range env { if k, _, ok := strings.Cut(e, "="); ok { keys = append(keys, k) } } return keys } // writeCABundle PEM-encodes the proxy CA into a temp file so managers can // trust the proxy via CATrustEnviron. For each CA-bundle variable the manager // names (ExistingBundleVars) that the parent env sets, those trust anchors are // prepended so the user's are preserved. The system roots follow the proxy CA, // because most of the variables CATrustEnviron sets replace a tool's default // trust instead of extending it. A file already merged (two variables pointing // at the same path) is not read twice. Returns the path; the caller removes it. func writeCABundle(ios *iostreams.IOStreams, parent []string, bundleVars []string, ca *x509.Certificate, roots []*x509.Certificate) (string, error) { pemBytes := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: ca.Raw}) var bundle []byte seen := make(map[string]struct{}, len(bundleVars)) for _, bundleVar := range bundleVars { existing := lookupEnv(parent, bundleVar) if bundleVar == "" || existing == "" { continue } if _, dup := seen[existing]; dup { continue } seen[existing] = struct{}{} userPEM, err := os.ReadFile(existing) if err != nil { ios.LogErrorf("warning: could not read existing %s %q: %v\n", bundleVar, existing, err) continue } bundle = append(bundle, userPEM...) if len(bundle) > 0 && bundle[len(bundle)-1] != '\n' { bundle = append(bundle, '\n') } } bundle = append(bundle, pemBytes...) for _, root := range roots { bundle = append(bundle, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: root.Raw})...) } f, err := os.CreateTemp("", "glab-df-ca-*.pem") if err != nil { return "", err } if _, err := f.Write(bundle); err != nil { return "", errors.Join(err, f.Close(), os.Remove(f.Name())) } if err := f.Close(); err != nil { return "", errors.Join(err, os.Remove(f.Name())) } return f.Name(), nil } // dedupEnv collapses an environment slice so each key appears once with its // last-assigned value, preserving first-seen ordering. This makes the child // process's view of each variable deterministic regardless of how its // runtime resolves duplicate envp entries. func dedupEnv(env []string) []string { index := make(map[string]int, len(env)) out := make([]string, 0, len(env)) for _, e := range env { key, _, ok := strings.Cut(e, "=") if !ok { out = append(out, e) continue } if i, seen := index[key]; seen { out[i] = e continue } index[key] = len(out) out = append(out, e) } return out } // lookupEnv returns the value of key in an environment slice ("KEY=value"), // or "" if absent. The last occurrence wins. func lookupEnv(env []string, key string) string { value := "" for _, e := range env { k, v, ok := strings.Cut(e, "=") if ok && k == key { value = v } } return value } // Executor runs the package-manager binary. Satisfied by cmdutils.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 } // interruptExitCode is 130 (the SIGINT convention) reported for any interrupt. // Run detects interruption from context cancellation and cannot recover the // specific signal (the received value is discarded), so it does not compute // 128+signal — SIGTERM's 143, for example, is never returned. The sibling df // package/ci-summary commands return verdict.BlockedExitCode (3); this code is // distinct from that and from the generic-failure 1. const interruptExitCode = 130 // 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 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 } func (e *ExitError) Error() string { return e.Err.Error() } func (e *ExitError) Unwrap() error { return e.Err } // RunOptions are the inputs to Run. Registry/token fields are gone: the model // no longer talks to a GitLab registry. 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) // notify is a test-only seam. When nil (the production path) Run installs // no signal handler at all — glab's root command owns signals via // fang.WithNotifySignal and cancels ctx on a signal. When non-nil it is // invoked in place of signal.Notify so tests can drive the same // cancellation deterministically without a real OS signal. notify func(c chan<- os.Signal, sig ...os.Signal) } // 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 UpstreamProxyCertificateOptions(certPath, keyPath string, password func() (string, error)) ([]proxy.Option, error) { if certPath == "" { return nil, nil } certs, err := api.LoadClientCertificates(certPath, keyPath, password) if err != nil { return nil, fmt.Errorf("failed to load client certificate: %w", err) } if len(certs) == 0 { return nil, nil } return []proxy.Option{proxy.WithUpstreamProxyCertificate(certs[0])}, nil } // Run executes manager.Binary() with args forwarded verbatim, except the // options an argsRewriter takes out, 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 Run(ctx context.Context, manager PackageManager, opts RunOptions) error { ctx, cancel := context.WithCancel(ctx) defer cancel() baseChecker, err := policy.New(opts.Client) if err != nil { return err } checker := policy.NewCachingChecker(baseChecker, opts.IO.LogErrorf) // Read the manager's own outbound proxy before its environment is pointed // at the inspection proxy below. proxyOpts, err := upstreamProxyOptions(manager, os.Environ(), opts.BaseDir, opts.Args) if err != nil { return err } proxyOpts = append(proxyOpts, proxy.WithUpstreamFailureWarning(opts.IO.LogErrorf), proxy.WithBlockNotice(opts.IO.LogErrorf)) var anchors []*x509.Certificate if m, ok := manager.(upstreamTrustManager); ok { anchors, err = m.upstreamTrustAnchors(os.Environ(), opts.BaseDir, opts.Args) warnings := []error{err} if joined, ok := err.(interface{ Unwrap() []error }); ok { warnings = joined.Unwrap() } for _, w := range warnings { if w != nil { opts.IO.LogErrorf("warning: %v\n", w) } } } roots, upstreamCAs, err := upstreamRootCAs(os.Environ(), opts.CACertPath, anchors) if err != nil { return fmt.Errorf("failed to load registry CA certificates: %w", err) } if roots != nil { proxyOpts = append(proxyOpts, proxy.WithUpstreamRootCAs(roots)) } certOpts, err := UpstreamProxyCertificateOptions(opts.ClientCertPath, opts.ClientKeyPath, opts.ClientCertPassword) if err != nil { return err } proxyOpts = append(proxyOpts, certOpts...) p, err := proxy.New(manager.Matcher(), checker, opts.ProjectID, proxyOpts...) if err != nil { return fmt.Errorf("failed to create inspection proxy: %w", err) } if err := p.Start(); err != nil { return fmt.Errorf("failed to start inspection proxy: %w", err) } defer p.Stop() //nolint:contextcheck // proxy shutdown manages its own context internally proxyURL := "http://" + p.Addr() caPath, err := writeCABundle(opts.IO, os.Environ(), manager.ExistingBundleVars(), p.CACertificate(), systemRoots()) if err != nil { return fmt.Errorf("failed to write proxy CA bundle: %w", err) } // The engine always removes the CA bundle; the manager removes any // ecosystem-specific sidecars it derived from it (e.g. a JVM truststore). defer func() { _ = os.Remove(caPath) manager.CleanupCAFiles(caPath) }() // Signal handling: glab's root command (main.go) already installs // fang.WithNotifySignal(os.Interrupt, SIGTERM), which cancels ctx on a // signal. We do not install a second signal.Notify; a cancelled context // surfaces as a context.Canceled execErr below, which we map to the // interrupt exit code. The notify hook is retained only so tests can drive // the same cancellation deterministically without a real OS signal. if opts.notify != nil { sigCh := make(chan os.Signal, 1) opts.notify(sigCh, os.Interrupt, syscall.SIGTERM) defer func() { signal.Stop(sigCh) close(sigCh) }() go func() { if _, ok := <-sigCh; !ok { return } cancel() }() } binPath, err := opts.Executor.LookPath(manager.Binary()) if err != nil { return fmt.Errorf("%s not found on PATH: %w", manager.Binary(), err) } args := opts.Args if r, ok := manager.(argsRewriter); ok { args = r.rewriteArgs(args) } if a, ok := manager.(argsManager); ok { a.SetArgs(args) } var setup setupResult stopSetup := func() {} if s, ok := manager.(setupManager); ok { setup, err = s.Setup(ctx, setupInput{ parent: os.Environ(), caPath: caPath, bin: binPath, exec: opts.Executor, checker: checker, projectID: opts.ProjectID, io: opts.IO, upstreamCAs: upstreamCAs, }) if err != nil { return fmt.Errorf("failed to set up %s for the Dependency Firewall: %w", manager.Name(), err) } stopSetup = sync.OnceFunc(setup.stop) defer stopSetup() } managerEnv := append(manager.Environment(proxyURL), setup.env...) // Strip the manager's own routing keys from the inherited env so they // can't leak an old value the manager's Environment doesn't overwrite; // the manager's values are re-appended immediately below. env := proxyEnviron(os.Environ(), proxyURL, envKeys(managerEnv)...) env = append(env, managerEnv...) env = append(env, manager.CATrustEnviron(caPath)...) // Collapse duplicate keys (last wins) so the proxy/CA-trust values we // append override any conflicting entry inherited from the parent // environment, regardless of how the child runtime parses envp. env = dedupEnv(env) execErr := opts.Executor.ExecWithIO(ctx, binPath, args, env, opts.IO.In, opts.IO.StdOut, opts.IO.StdErr) p.Stop() //nolint:contextcheck // proxy shutdown manages its own context internally stopSetup() verdicts := p.Verdicts() if setup.verdicts != nil { verdicts = append(verdicts, setup.verdicts()...) } writeLog(opts.IO, opts.BaseDir, manager.Name(), args, verdicts) if len(verdicts) > 0 { summary.Render(opts.IO, verdicts) } // A cancelled context (from a signal, via fang or the injected notify // hook) means the run was interrupted, regardless of which path fired // first. Report the conventional interrupt code rather than the generic // failure exitError would derive from context.Canceled. if errors.Is(execErr, context.Canceled) || errors.Is(ctx.Err(), context.Canceled) { return &ExitError{Code: interruptExitCode, Err: errors.New("interrupted")} } return exitError(manager.Binary(), execErr) } // writeLog merges this run's verdicts into the CI log at // baseDir/.gitlab/df/ci-log.json. It loads any existing log first and appends // (cilog dedupes by Entry.Key) so a job that runs the firewall more than once // — npm then pip, or install then publish — accumulates every run's verdicts. // Overwriting instead would drop earlier runs, and df ci-summary would then // exit 0 even though a package was blocked, silently defeating the job gate. // // A Load error means a present-but-corrupt log (cilog.Load returns a fresh log // with a nil error for a missing file). We must NOT start fresh in that case: // overwriting a log we cannot parse would discard an earlier run's Blocked // entries and flip ci-summary's fail-closed "unreadable log" exit into a pass. // So on a Load error we leave the file untouched and skip the write, keeping // the corrupt log in place for ci-summary to fail on. // // The log is written into the working tree on every run, including local // ones, so it will appear as an untracked .gitlab/df/ci-log.json for // developers; that is intentional (ci-summary reads it back to gate the job). func writeLog(ios *iostreams.IOStreams, baseDir, name string, args []string, entries []verdict.Entry) { command := strings.Join(append([]string{name}, args...), " ") // Hold the sidecar lock across Load -> Append -> Save so two concurrent // "glab df run" invocations in one job serialize instead of racing // last-writer-wins (which would drop the losing run's Blocked entries and // let ci-summary exit 0). err := fsx.WithLock(cilog.LockPath(baseDir), func() error { log, err := cilog.Load(baseDir) if err != nil { // A Load error means a present-but-corrupt log (Load returns a // fresh log with nil error for a missing file). Leave it in place // rather than overwriting: starting fresh would discard an earlier // run's Blocked entries and flip ci-summary's fail-closed // unreadable-log exit into a pass. return fmt.Errorf("existing Dependency Firewall CI log is unreadable; leaving it in place for ci-summary to fail on: %w", err) } // On the normal path Load returns a zero-value log for a missing file, // so its Session (Command/StartedAt) is empty — only cilog.New sets // it. Populate it here for the first run so ci-log.json always records // the session that created it; a later run leaves an already-set // Session alone so the log keeps the originating command. if log.Session.Command == "" { log.Session = cilog.New(command).Session } for _, e := range entries { log.Append(e) } if err := cilog.Save(baseDir, log); err != nil { return fmt.Errorf("failed to write Dependency Firewall CI log: %w", err) } return nil }) if err != nil { ios.LogErrorf("warning: %v\n", err) } } // exitError wraps a package-manager execution error as an *ExitError carrying // the child's exit Code. The calling command translates it into the // *cmdutils.ExitError that main.go's handler unwraps to set glab's exit // status; see dfcmd.run. func exitError(binary string, err error) error { if err == nil { return nil } if ee, ok := errors.AsType[*exec.ExitError](err); ok { return &ExitError{Code: ee.ExitCode(), Err: fmt.Errorf("%s exited with a non-zero status: %w", binary, err), ChildExited: true} } return &ExitError{Code: 1, Err: fmt.Errorf("failed to run %s: %w", binary, err)} }