GitLabgitlab-org

cli

main
ply7 git calls267 ms98 KiB5 cachedprotocol v2
178 lines6.4 KiBRaw
1// Package policy decides whether a package coordinate is allowed by the
2// GitLab Dependency Firewall. It is the seam between the inspection proxy
3// (which identifies a coordinate) and the verdict source. Two Checker
4// implementations exist: a fake, environment-driven one for testing and a
5// REST-backed one that calls the real policy API. Callers wrap the chosen
6// Checker in a CachingChecker.
7package policy
9import (
10 "context"
11 "errors"
12 "fmt"
13 "os"
14 "slices"
15 "strings"
16 "time"
18 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
20 "gitlab.com/gitlab-org/cli/internal/dependencyfirewall/verdict"
21 "gitlab.com/gitlab-org/cli/internal/text"
24// CheckTimeout is the deadline every Checker.Check caller must set, shared
25// across a request's candidates, since the API client has no timeout of its own.
26const CheckTimeout = 60 * time.Second
28// Operation is the package-manager action that triggered a check.
29type Operation int
31const (
32 // Download is an artifact fetch (tarball, wheel, jar, gem).
33 Download Operation = iota
34 // Upload is a publish/push of a package.
35 Upload
38// String returns a stable, human-readable name for the operation. It keeps
39// log lines legible and independent of the numeric ordering of the constants.
40func (o Operation) String() string {
41 switch o {
42 case Download:
43 return "download"
44 case Upload:
45 return "upload"
46 default:
47 return fmt.Sprintf("operation(%d)", int(o))
48 }
51// Coordinate is the exact package identity a check is performed against.
52type Coordinate struct {
53 Ecosystem string
54 Name string
55 Version string
58// Key is the cache and dedupe key for a coordinate.
59func (c Coordinate) Key() string {
60 return fmt.Sprintf("%s:%s@%s", c.Ecosystem, c.Name, c.Version)
63// Request is a single policy question. ProjectID selects the project whose
64// firewall answers it; the REST checker evaluates against this field.
65// Operation records the package-manager action for cache-key isolation and
66// diagnostics; the evaluate API is scoped to project and coordinate only and
67// does not accept an operation, so it is not transmitted.
68type Request struct {
69 Coordinate Coordinate
70 ProjectID string // project id or full-path slug, from git repo context
71 Operation Operation
74// Key is the cache and dedupe key for a request. It includes the project and
75// operation, not just the coordinate: the same package can get a different
76// verdict per project (policies are project-scoped), and download and upload
77// are tracked separately, so keying on the coordinate alone would let one
78// project's or operation's cached verdict answer for another.
79func (r Request) Key() string {
80 return fmt.Sprintf("%s|%s|%s", r.Coordinate.Key(), r.ProjectID, r.Operation)
83// Result is the outcome of a policy check. A zero Verdict (verdict.Allowed)
84// means allow.
85type Result struct {
86 Verdict verdict.Verdict // verdict.Allowed, verdict.Blocked, or verdict.Warning
87 Reason string // human-readable; used in the 403 body and summary
88 // CheckFailed marks a block standing in for a decision the policy could
89 // not give, as opposed to one a rule made.
90 CheckFailed bool
91 // Internal marks a CheckFailed block caused by a glab panic.
92 Internal bool
95// ErrCheckPanicked is the error a recovered panic in a policy check becomes.
96var ErrCheckPanicked = errors.New("policy check panicked")
98// InternalErrorResult is the block for a check that glab itself broke on:
99// failing closed means a glab bug can't let a package skip the policy check.
100func InternalErrorResult(c Coordinate) Result {
101 return Result{
102 Verdict: verdict.Blocked,
103 Reason: fmt.Sprintf("glab hit an internal error while checking %s and blocked it. %s", internalErrorSubject(c), internalErrorAdvice),
104 CheckFailed: true,
105 Internal: true,
106 }
109const internalErrorAdvice = "Rerun to retry, and report this with the output of GLAB_DEBUG=1."
111// InternalErrorPhrasePrefix starts InternalErrorPhrase.
112const InternalErrorPhrasePrefix = "Blocked: glab internal error while checking "
114// InternalErrorPhrase is the short form of InternalErrorResult's reason, for
115// a response status line or body.
116func InternalErrorPhrase(c Coordinate) string {
117 return InternalErrorPhrasePrefix + internalErrorSubject(c)
120// internalErrorSubject names the package for a terminal or a status line. Its
121// name can come from a request path, so control characters are dropped.
122func internalErrorSubject(c Coordinate) string {
123 return text.SanitizeInline(c.Name + "@" + c.Version)
126// Allowed reports whether the result permits the coordinate.
127func (r Result) Allowed() bool { return r.Verdict == verdict.Allowed }
129// Blocked reports whether the result denies the coordinate.
130func (r Result) Blocked() bool { return r.Verdict == verdict.Blocked }
132// Warned reports whether the result permits the coordinate but flags it.
133func (r Result) Warned() bool { return r.Verdict == verdict.Warning }
135// Checker answers policy questions.
136type Checker interface {
137 Check(ctx context.Context, req Request) (Result, error)
140// fakeEnvPrefix is the environment-variable prefix that both selects and
141// configures the fake checker.
142const fakeEnvPrefix = "GLAB_DF_FAKE_"
144// New returns the fake checker when any GLAB_DF_FAKE_* variable is set,
145// otherwise the REST checker backed by client. The REST checker evaluates
146// against each Request's ProjectID, so no project is bound here. Callers wrap
147// the result in a CachingChecker.
148//
149// Fake mode is refused in CI. The fake checker is a test seam that can allow
150// everything (GLAB_DF_FAKE_DEFAULT=allow); honoring it under GITLAB_CI=true
151// would let a single pipeline variable silently disable the firewall on a
152// real job. In CI the only valid checker is the REST one, so New returns an
153// error instead of quietly serving verdicts from the environment.
154func New(client *gitlab.Client) (Checker, error) {
155 environ := os.Environ()
156 if fakeConfigured(environ) {
157 if isCI(environ) {
158 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)
159 }
160 return newFakeChecker(environ), nil
161 }
162 return newRESTChecker(client), nil
165// isCI reports whether the process is running inside GitLab CI, which sets
166// GITLAB_CI=true for every job.
167func isCI(environ []string) bool {
168 return slices.Contains(environ, "GITLAB_CI=true")
171func fakeConfigured(environ []string) bool {
172 for _, e := range environ {
173 if strings.HasPrefix(e, fakeEnvPrefix) {
174 return true
175 }
176 }
177 return false
Diagnostics7 git calls · 267 ms
CallStatusSizeTime0267 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit8 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=8
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit5 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=5
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:0200361 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=361
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=506cba622ceda1473ee3cde63969809c144b7247
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=361
git.pkt.payload.max=334
git.sideband.band1.bytes=334
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=334
git.pack.trailer=26d32585a3a474717e00a318584ccd16918c9d32
Open pack map
fetchtree:0200332 B · hit1 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
git.response.bytes=332
git.response.cache=HIT
git.response.duration_ms=1
git.fetch.filter=tree:0
git.fetch.wants=cb813f0d675e9dca14f167e8c7788d61eb19627f
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=332
git.pkt.payload.max=305
git.sideband.band1.bytes=305
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=305
git.pack.trailer=5e210c1831ecf78390a6fe6e1784efd898336da0
Open pack map
fetch2002.6 KiB253 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=253
git.response.bytes=2663
git.response.cache=MISS
git.response.duration_ms=253
git.fetch.wants=7bcac8e991951694cd838fab7778330992848748
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2663
git.pkt.payload.max=2636
git.sideband.band1.bytes=2636
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e298a69f842407
Request
2656b6ac…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format