// Package policy decides whether a package coordinate is allowed by the // GitLab Dependency Firewall. It is the seam between the inspection proxy // (which identifies a coordinate) and the verdict source. Two Checker // implementations exist: a fake, environment-driven one for testing and a // REST-backed one that calls the real policy API. Callers wrap the chosen // Checker in a CachingChecker. package policy import ( "context" "errors" "fmt" "os" "slices" "strings" "time" gitlab "gitlab.com/gitlab-org/api/client-go/v3" "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/verdict" "gitlab.com/gitlab-org/cli/internal/text" ) // CheckTimeout is the deadline every Checker.Check caller must set, shared // across a request's candidates, since the API client has no timeout of its own. const CheckTimeout = 60 * time.Second // Operation is the package-manager action that triggered a check. type Operation int const ( // Download is an artifact fetch (tarball, wheel, jar, gem). Download Operation = iota // Upload is a publish/push of a package. Upload ) // String returns a stable, human-readable name for the operation. It keeps // log lines legible and independent of the numeric ordering of the constants. func (o Operation) String() string { switch o { case Download: return "download" case Upload: return "upload" default: return fmt.Sprintf("operation(%d)", int(o)) } } // Coordinate is the exact package identity a check is performed against. type Coordinate struct { Ecosystem string Name string Version string } // Key is the cache and dedupe key for a coordinate. func (c Coordinate) Key() string { return fmt.Sprintf("%s:%s@%s", c.Ecosystem, c.Name, c.Version) } // Request is a single policy question. ProjectID selects the project whose // firewall answers it; the REST checker evaluates against this field. // Operation records the package-manager action for cache-key isolation and // diagnostics; the evaluate API is scoped to project and coordinate only and // does not accept an operation, so it is not transmitted. type Request struct { Coordinate Coordinate ProjectID string // project id or full-path slug, from git repo context Operation Operation } // Key is the cache and dedupe key for a request. It includes the project and // operation, not just the coordinate: the same package can get a different // verdict per project (policies are project-scoped), and download and upload // are tracked separately, so keying on the coordinate alone would let one // project's or operation's cached verdict answer for another. func (r Request) Key() string { return fmt.Sprintf("%s|%s|%s", r.Coordinate.Key(), r.ProjectID, r.Operation) } // Result is the outcome of a policy check. A zero Verdict (verdict.Allowed) // means allow. type Result struct { Verdict verdict.Verdict // verdict.Allowed, verdict.Blocked, or verdict.Warning Reason string // human-readable; used in the 403 body and summary // CheckFailed marks a block standing in for a decision the policy could // not give, as opposed to one a rule made. CheckFailed bool // Internal marks a CheckFailed block caused by a glab panic. Internal bool } // ErrCheckPanicked is the error a recovered panic in a policy check becomes. var ErrCheckPanicked = errors.New("policy check panicked") // InternalErrorResult is the block for a check that glab itself broke on: // failing closed means a glab bug can't let a package skip the policy check. func InternalErrorResult(c Coordinate) Result { return Result{ Verdict: verdict.Blocked, Reason: fmt.Sprintf("glab hit an internal error while checking %s and blocked it. %s", internalErrorSubject(c), internalErrorAdvice), CheckFailed: true, Internal: true, } } const internalErrorAdvice = "Rerun to retry, and report this with the output of GLAB_DEBUG=1." // InternalErrorPhrasePrefix starts InternalErrorPhrase. const InternalErrorPhrasePrefix = "Blocked: glab internal error while checking " // InternalErrorPhrase is the short form of InternalErrorResult's reason, for // a response status line or body. func InternalErrorPhrase(c Coordinate) string { return InternalErrorPhrasePrefix + internalErrorSubject(c) } // internalErrorSubject names the package for a terminal or a status line. Its // name can come from a request path, so control characters are dropped. func internalErrorSubject(c Coordinate) string { return text.SanitizeInline(c.Name + "@" + c.Version) } // Allowed reports whether the result permits the coordinate. func (r Result) Allowed() bool { return r.Verdict == verdict.Allowed } // Blocked reports whether the result denies the coordinate. func (r Result) Blocked() bool { return r.Verdict == verdict.Blocked } // Warned reports whether the result permits the coordinate but flags it. func (r Result) Warned() bool { return r.Verdict == verdict.Warning } // Checker answers policy questions. type Checker interface { Check(ctx context.Context, req Request) (Result, error) } // fakeEnvPrefix is the environment-variable prefix that both selects and // configures the fake checker. const fakeEnvPrefix = "GLAB_DF_FAKE_" // New returns the fake checker when any GLAB_DF_FAKE_* variable is set, // otherwise the REST checker backed by client. The REST checker evaluates // against each Request's ProjectID, so no project is bound here. Callers wrap // the result in a CachingChecker. // // Fake mode is refused in CI. The fake checker is a test seam that can allow // everything (GLAB_DF_FAKE_DEFAULT=allow); honoring it under GITLAB_CI=true // would let a single pipeline variable silently disable the firewall on a // real job. In CI the only valid checker is the REST one, so New returns an // error instead of quietly serving verdicts from the environment. func New(client *gitlab.Client) (Checker, error) { environ := os.Environ() if fakeConfigured(environ) { if isCI(environ) { return nil, fmt.Errorf("refusing to use the Dependency Firewall fake policy checker in CI: unset all %s* variables so real policy is enforced", fakeEnvPrefix) } return newFakeChecker(environ), nil } return newRESTChecker(client), nil } // isCI reports whether the process is running inside GitLab CI, which sets // GITLAB_CI=true for every job. func isCI(environ []string) bool { return slices.Contains(environ, "GITLAB_CI=true") } func fakeConfigured(environ []string) bool { for _, e := range environ { if strings.HasPrefix(e, fakeEnvPrefix) { return true } } return false }