fix(FLEETMDM-001): CU-86akbhhtv 16 review findings across 13 files

frontend/utilities/auth_token/index.ts

@@ -6,6 +6,7 @@ import Cookie from "js-cookie";
 
 const DEFAULT_EXPIRATION_DAYS = 5;
 
+// >>> OPENFRAME(auth-token-http-fallback): allow non-secure cookie fallback for non-TLS deployments — openframe/docs/auth.md
 // The `__Host-` cookie name prefix and the `Secure` attribute both require the
 // cookie to be set from a secure (HTTPS) context. When Fleet is served over
 // plain HTTP (e.g. a Docker deployment without TLS), the browser silently
@@ -18,26 +19,33 @@ const isSecure = (): boolean => window.location.protocol === "https:";
 // `__Host-` prefixed names are only valid on secure cookies, so the cookie name
 // must match the context it was stored in for get/remove to find it.
 const getTokenName = (): string => (isSecure() ? "__Host-token" : "token");
+// <<< OPENFRAME(auth-token-http-fallback)
 
 const save = (token: string, expiresAt?: Date): void => {
+  // >>> OPENFRAME(auth-token-http-fallback): allow non-secure cookie fallback for non-TLS deployments — openframe/docs/auth.md
   Cookie.set(getTokenName(), token, {
     secure: isSecure(),
     sameSite: "lax",
     expires: expiresAt ?? DEFAULT_EXPIRATION_DAYS,
   });
+  // <<< OPENFRAME(auth-token-http-fallback)
 };
 
 const get = (): string | null => {
+  // >>> OPENFRAME(auth-token-http-fallback): allow non-secure cookie fallback for non-TLS deployments — openframe/docs/auth.md
   return Cookie.get(getTokenName()) || null;
+  // <<< OPENFRAME(auth-token-http-fallback)
 };
 
 const remove = (): void => {
   // NOTE: the secure and sameSite from the cookie must be provided
   // to correctly remove. That is why we include the options here as well.
+  // >>> OPENFRAME(auth-token-http-fallback): allow non-secure cookie fallback for non-TLS deployments — openframe/docs/auth.md
   Cookie.remove(getTokenName(), {
     secure: isSecure(),
     sameSite: "lax",
   });
+  // <<< OPENFRAME(auth-token-http-fallback)
 };
 
 export default {

server/contexts/viewer/viewer.go

@@ -105,6 +105,8 @@ func (v Viewer) CanPerformPasswordReset() bool {
 	return false
 }
 
+// >>> OPENFRAME(viewer-telemetry): add diagnostic/telemetry context and system viewer — openframe/docs/....md
+
 // GetDiagnosticContext implements ctxerr.ErrorContextProvider
 func (v *Viewer) GetDiagnosticContext() map[string]any {
 	vdata := map[string]any{
@@ -156,3 +158,5 @@ var systemUser = &fleet.User{
 func NewSystemContext(ctx context.Context) context.Context {
 	return NewContext(ctx, Viewer{User: systemUser})
 }
+
+// <<< OPENFRAME(viewer-telemetry)

server/datastore/mysqlredis/hosts.go

@@ -134,12 +134,14 @@ func (d *Datastore) NewHost(ctx context.Context, host *fleet.Host) (*fleet.Host,
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): invalidate node_key cache on host creation — openframe/docs/host-cache.md
 	// A newly inserted host has no positive cache entry, but a stale negative
 	// cache entry for the new node_key could linger (up to hostCacheNegativeTTL)
 	// if the node_key had been probed moments before enrollment. Clearing it
 	// here ensures the next LoadHostByNodeKey populates the positive cache
 	// instead of returning a false NotFound.
 	d.invalidateAfterHostEnroll(ctx, h, "enroll")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return h, nil
 }
 
@@ -153,9 +155,11 @@ func (d *Datastore) EnrollOsquery(ctx context.Context, opts ...fleet.DatastoreEn
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): invalidate stale cache on re-enrollment — openframe/docs/host-cache.md
 	// EnrollOsquery can update an existing row's node_key + team_id on
 	// re-enrollment, so the cached snapshot is stale after the call.
 	d.invalidateAfterHostEnroll(ctx, h, "enroll")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return h, nil
 }
 
@@ -169,9 +173,11 @@ func (d *Datastore) DeleteHost(ctx context.Context, hid uint) error {
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): purge cache entry on host deletion — openframe/docs/host-cache.md
 	// Deleted row must not serve from cache: a stale hit would let the host
 	// authenticate after its deletion.
 	d.hostCacheDeleteByID(ctx, hid, "delete")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return nil
 }
 
@@ -185,8 +191,10 @@ func (d *Datastore) DeleteHosts(ctx context.Context, ids []uint) error {
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): purge cache entries on batch host deletion — openframe/docs/host-cache.md
 	// Batched pipelined invalidation — see invalidateHostIDs for why.
 	d.invalidateHostIDs(ctx, ids, "delete")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return nil
 }
 
@@ -204,7 +212,9 @@ func (d *Datastore) CleanupExpiredHosts(ctx context.Context) ([]fleet.DeletedHos
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): purge cache entries for expired hosts — openframe/docs/host-cache.md
 	d.invalidateHostIDs(ctx, ids, "delete")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return details, nil
 }
 
@@ -218,7 +228,9 @@ func (d *Datastore) CleanupIncomingHosts(ctx context.Context, now time.Time) ([]
 			logging.WithErr(ctx, err)
 		}
 	}
+	// >>> OPENFRAME(host-cache-invalidation): purge cache entries for cleaned up incoming hosts — openframe/docs/host-cache.md
 	d.invalidateHostIDs(ctx, ids, "delete")
+	// <<< OPENFRAME(host-cache-invalidation)
 	return ids, nil
 }
 

server/mdm/nanomdm/storage/mysql/mysql.go

@@ -142,6 +142,7 @@ func (s *MySQLStorage) StoreAuthenticate(r *mdm.Request, msg *mdm.Authenticate)
 	if r.Certificate != nil {
 		pemCert = cryptoutil.PEMCertificate(r.Certificate.Raw)
 	}
+	// >>> OPENFRAME(nanomdm-bootstrap-token-renewal): preserve bootstrap token across SCEP renewal — openframe/docs/nanomdm.md
 	// When a device undergoes SCEP certificate renewal, it sends a new
 	// Authenticate message. We must preserve the existing bootstrap token
 	// during renewal; clearing it causes commands that depend on it (e.g.
@@ -170,6 +171,7 @@ UPDATE
     authenticate_at = CURRENT_TIMESTAMP;`,
 		r.ID, pemCert, nullEmptyString(msg.SerialNumber), msg.Raw, r.ID, r.ID,
 	)
+	// <<< OPENFRAME(nanomdm-bootstrap-token-renewal)
 
 	return err
 }
@@ -378,3 +380,4 @@ func (s *MySQLStorage) SetRecoveryLockFailed(ctx context.Context, hostUUID strin
 	s.logger.ErrorContext(ctx, "MySQLStorage.SetRecoveryLockFailed not implemented")
 	return nil
 }
+

server/mock/datastore.go

@@ -38,8 +38,13 @@ func (m *Store) GetCurrentTime(ctx context.Context) (time.Time, error) {
 func (m *Store) Drop() error                             { return nil }
 func (m *Store) MigrateTables(ctx context.Context) error { return nil }
 func (m *Store) MigrateData(ctx context.Context) error   { return nil }
+
+// >>> OPENFRAME(mock-migrate-openframe): add MigrateOpenframe mock stub for OpenFrame migration hook — openframe/docs/datastore.md
 func (m *Store) MigrateOpenframe(ctx context.Context) error { return nil }
+
+// <<< OPENFRAME(mock-migrate-openframe)
 func (m *Store) MigrationStatus(ctx context.Context) (*fleet.MigrationStatus, error) {
 	return &fleet.MigrationStatus{}, nil
 }
 func (m *Store) Name() string { return "mock" }
+

server/service/async/async_label.go

@@ -91,6 +91,7 @@ func (t *Task) RecordLabelQueryExecutions(ctx context.Context, host *fleet.Host,
 }
 
 func (t *Task) collectLabelQueryExecutions(ctx context.Context, ds fleet.Datastore, pool fleet.RedisPool, stats *collectorExecStats) error {
+	// >>> OPENFRAME(async-otel): add OTEL span for label collection task — openframe/docs/observability.md
 	// Create a root span for this async collection task if OTEL is enabled
 	if t.otelEnabled {
 		tracer := otel.Tracer("async")
@@ -102,6 +103,7 @@ func (t *Task) collectLabelQueryExecutions(ctx context.Context, ds fleet.Datasto
 		)
 		defer span.End()
 	}
+	// <<< OPENFRAME(async-otel)
 
 	cfg := t.taskConfigs[config.AsyncTaskLabelMembership]
 

server/service/async/async_policy.go

@@ -124,7 +124,7 @@ func (t *Task) RecordPolicyQueryExecutions(ctx context.Context, host *fleet.Host
 }
 
 func (t *Task) collectPolicyQueryExecutions(ctx context.Context, ds fleet.Datastore, pool fleet.RedisPool, stats *collectorExecStats) error {
-	// Create a root span for this async collection task if OTEL is enabled
+	// >>> OPENFRAME(async-otel): add OTEL span for policy collection task — openframe/docs/observability.md
 	if t.otelEnabled {
 		tracer := otel.Tracer("async")
 		var span trace.Span
@@ -135,6 +135,7 @@ func (t *Task) collectPolicyQueryExecutions(ctx context.Context, ds fleet.Datast
 		)
 		defer span.End()
 	}
+	// <<< OPENFRAME(async-otel)
 
 	cfg := t.taskConfigs[config.AsyncTaskPolicyMembership]
 
@@ -275,3 +276,4 @@ func (t *Task) GetHostPolicyReportedAt(ctx context.Context, host *fleet.Host) ti
 	}
 	return host.PolicyUpdatedAt
 }
+

server/service/endpoint_middleware.go

@@ -22,6 +22,7 @@ import (
 	"github.com/go-kit/kit/endpoint"
 )
 
+// >>> OPENFRAME(idevice-cert-auth): cert-serial extraction for iOS/iPadOS mTLS device auth — openframe/docs/idevice-cert-auth.md
 // extractCertSerialFromHeader extracts certificate serial from X-Client-Cert-Serial
 // header (set by load balancer during mTLS) for iOS/iPadOS device authentication.
 func extractCertSerialFromHeader(ctx context.Context, r *http.Request) context.Context {
@@ -39,6 +40,8 @@ func extractCertSerialFromHeader(ctx context.Context, r *http.Request) context.C
 	return certserial.NewContext(ctx, serial)
 }
 
+// <<< OPENFRAME(idevice-cert-auth)
+
 func logJSON(ctx context.Context, logger *slog.Logger, v any, key string) {
 	jsonV, err := json.Marshal(v)
 	if err != nil {
@@ -76,6 +79,7 @@ func authenticatedDevice(svc fleet.Service, logger *slog.Logger, next endpoint.E
 		var debug bool
 		var authnMethod authz_ctx.AuthenticationMethod
 
+		// >>> OPENFRAME(idevice-cert-auth): cert/token/URL authentication branching for iOS/iPadOS device auth — openframe/docs/idevice-cert-auth.md
 		if certSerial, ok := certserial.FromContext(ctx); ok {
 			// Header presence signals cert auth intent, even if serial is invalid.
 			host, debug, err = svc.AuthenticateDeviceByCertificate(ctx, certSerial, identifier)
@@ -92,6 +96,7 @@ func authenticatedDevice(svc fleet.Service, logger *slog.Logger, next endpoint.E
 				authnMethod = authz_ctx.AuthnDeviceURL
 			}
 		}
+		// <<< OPENFRAME(idevice-cert-auth)
 
 		if err != nil {
 			logging.WithErr(ctx, err)

server/service/maintained_apps.go

@@ -31,6 +31,10 @@ type addFleetMaintainedAppRequest struct {
 	Categories        []string `json:"categories"`
 }
 
+// >>> OPENFRAME(maintained-apps-decode-request): DecodeRequest adds fleet_id/team_id
+// aliasing and base64-encoded script field decoding to bypass WAF rules that may
+// block requests containing shell/PowerShell script patterns. — openframe/docs/FLEETMDM-001.md
+
 // DecodeRequest implements the RequestDecoder interface to support base64-encoded
 // script fields. This allows bypassing WAF rules that may block requests containing
 // shell/PowerShell script patterns. When the X-Fleet-Scripts-Encoded header is set
@@ -83,6 +87,8 @@ func (addFleetMaintainedAppRequest) DecodeRequest(ctx context.Context, r *http.R
 	return &req, nil
 }
 
+// <<< OPENFRAME(maintained-apps-decode-request)
+
 type addFleetMaintainedAppResponse struct {
 	SoftwareTitleID uint  `json:"software_title_id,omitempty"`
 	Err             error `json:"error,omitempty"`

server/service/software_installers.go

@@ -207,6 +207,7 @@ func (updateSoftwareInstallerRequest) DecodeRequest(ctx context.Context, r *http
 		}
 	}
 
+	// >>> OPENFRAME(waf-bypass-scripts): base64-encode scripts to avoid WAF pattern blocks — openframe/docs/waf-bypass.md
 	// Check if scripts are base64 encoded (to bypass WAF rules that block script patterns)
 	if isScriptsEncoded(r) {
 		if decoded.InstallScript != nil {
@@ -238,6 +239,7 @@ func (updateSoftwareInstallerRequest) DecodeRequest(ctx context.Context, r *http
 			decoded.PostInstallScript = &decodedScript
 		}
 	}
+	// <<< OPENFRAME(waf-bypass-scripts)
 
 	return &decoded, nil
 }
@@ -423,6 +425,7 @@ func (uploadSoftwareInstallerRequest) DecodeRequest(ctx context.Context, r *http
 		decoded.AutomaticInstall = parsed
 	}
 
+	// >>> OPENFRAME(waf-bypass-scripts): base64-encode scripts to avoid WAF pattern blocks — openframe/docs/waf-bypass.md
 	// Check if scripts are base64 encoded (to bypass WAF rules that block script patterns)
 	if isScriptsEncoded(r) {
 		var err error
@@ -439,6 +442,7 @@ func (uploadSoftwareInstallerRequest) DecodeRequest(ctx context.Context, r *http
 			return nil, &fleet.BadRequestError{Message: "invalid base64 encoding for post_install_script"}
 		}
 	}
+	// <<< OPENFRAME(waf-bypass-scripts)
 
 	return &decoded, nil
 }

server/vulnerabilities/msrc/parsed/product.go

@@ -11,8 +11,10 @@ import (
 	"github.com/fleetdm/fleet/v4/server/fleet"
 )
 
+// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 // displayVersionPattern matches Windows display version strings like "22H2", "23H2", "24H2".
 var displayVersionPattern = regexp.MustCompile(`\b\d{2}H[12]\b`)
+// <<< OPENFRAME(msrc-display-version)
 
 // Product abstracts a MS full product name.
 // A full product name includes the name of the product plus its arch
@@ -24,13 +26,15 @@ type Products map[string]Product
 var ErrNoMatch = errors.New("no product matches")
 
 func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (string, error) {
+	// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 	isServerCoreHost := strings.EqualFold(os.InstallationType, "Server Core")
 	installationTypeKnown := os.InstallationType != ""
 
 	// matchByDisplayVersion is set when we find a product whose display version
 	// (e.g. "22H2") matches the host's. matchByBuildNumber is the fallback for
 	// hosts that lack a display version (legacy builds 22000/10240 only).
 	var matchByDisplayVersion, matchByBuildNumber string
+	// <<< OPENFRAME(msrc-display-version)
 
 	for pID, product := range p {
 		normalizedOS := NewProductFromOS(os)
@@ -43,6 +47,7 @@ func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (
 			continue
 		}
 
+		// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 		// When the host's installation type is known, only match products
 		// that correspond to the correct installation type (Server Core vs full desktop).
 		if installationTypeKnown && product.IsServerCore() != isServerCoreHost {
@@ -53,8 +58,10 @@ func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (
 		// (superset of Server Core CVEs) for deterministic matching. Only use
 		// a Server Core product if no desktop alternative has been found.
 		isCore := product.IsServerCore()
+		// <<< OPENFRAME(msrc-display-version)
 
 		if product.HasDisplayVersion() {
+			// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 			// Use os.DisplayVersion if available, otherwise try to extract it from the OS name.
 			// The OS name may already contain the display version (e.g., "Microsoft Windows 10 Pro 22H2")
 			// even when the DisplayVersion field is empty, which can happen when osquery includes
@@ -72,6 +79,7 @@ func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (
 				}
 				continue
 			}
+			// <<< OPENFRAME(msrc-display-version)
 		}
 
 		// If os.DisplayVersion is empty, we need to confirm that the product
@@ -85,13 +93,16 @@ func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (
 				build = parts[2]
 			}
 			if build == "22000" || build == "10240" {
+				// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 				if matchByBuildNumber == "" || !isCore {
 					matchByBuildNumber = pID
 				}
+				// <<< OPENFRAME(msrc-display-version)
 			}
 		}
 	}
 
+	// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 	if matchByDisplayVersion == "" && matchByBuildNumber == "" {
 		return "", ctxerr.Wrap(ctx, ErrNoMatch)
 	}
@@ -101,6 +112,7 @@ func (p Products) GetMatchForOS(ctx context.Context, os fleet.OperatingSystem) (
 	}
 
 	return matchByBuildNumber, nil
+	// <<< OPENFRAME(msrc-display-version)
 }
 
 func NewProductFromFullName(fullName string) Product {
@@ -247,6 +259,7 @@ func (p Product) Name() string {
 	}
 }
 
+// >>> OPENFRAME(msrc-display-version): match hosts missing DisplayVersion via OS name fallback — openframe/docs/msrc-matching.md
 // IsServerCore returns true if the product name indicates a Server Core installation.
 func (p Product) IsServerCore() bool {
 	return strings.Contains(strings.ToLower(string(p)), "server core")
@@ -259,6 +272,7 @@ func extractDisplayVersionFromName(name string) string {
 	match := displayVersionPattern.FindString(name)
 	return match
 }
+// <<< OPENFRAME(msrc-display-version)
 
 // Matches checks whether product A matches product B by checking to see if both are for the same
 // product and if the architecture they target are compatible. This function is commutative.
@@ -269,3 +283,4 @@ func (p Product) Matches(o Product) bool {
 
 	return p.Arch() == "all" || o.Arch() == "all" || p.Arch() == o.Arch()
 }
+