SPB Git

Repository Public

enroll.go 16.8 KB 497 lines go

1/**2 * =============================================================================3 *                  SP BOUCHER | INFRASTRUCTURE & AUTOMATION4 *             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project          : MacLustr Command Center (MCC)8 * File             : services/internal/ingest/enroll.go9 * Module           : services10 * Repository       : https://git.spboucher.ai/maclustr-command-center11 * Project Website  : https://clustr.spboucher.ai12 * Created          : 2026-11-1813 * Last Modified    : 2026-11-1814 *15 * Author           : Simon-Pierre Boucher16 * Position         : Professor of Finance17 * Institution      : Université du Québec en Outaouais (UQO)18 * Organization     : SP Boucher19 * Website          : https://spboucher.ai20 * Git              : https://git.spboucher.ai21 *22 * Preferred Contact: admin@spboucher.ai23 * Technical Contact: dev@spboucher.ai24 * Security/Admin   : admin@spboucher.ai25 *26 * Copyright (c) 202627 * Simon-Pierre Boucher28 * All rights reserved where applicable. This file is governed by the29 * applicable project license, copyright notices and relevant law.30 * Existing third-party rights and notices remain unaffected.31 *32 * License          : None specified (no license file in this repository)33 *34 * Do not embed credentials, private keys, access tokens,35 * certificates or confidential personal information.36 *37 * =============================================================================38 * END OF SP BOUCHER SOURCE HEADER39 * =============================================================================40 */4142package ingest4344import (45	"context"46	"crypto/sha256"47	"encoding/base64"48	"errors"49	"fmt"50	"net/http"51	"net/netip"52	"reflect"53	"strings"54	"time"5556	"github.com/google/uuid"57	"github.com/jackc/pgx/v5"5859	"clustr.spboucher.ai/mcc/internal/audit"60	"clustr.spboucher.ai/mcc/internal/events"61	"clustr.spboucher.ai/mcc/internal/httpx"62	"clustr.spboucher.ai/mcc/internal/ids"63	"clustr.spboucher.ai/mcc/internal/pki"64	"clustr.spboucher.ai/mcc/internal/protocol"65	"clustr.spboucher.ai/mcc/internal/secret"66)6768const enrollTokenHeader = "X-MCC-Enroll-Token"6970var (71	errEnrollToken  = httpx.Err(http.StatusUnauthorized, "invalid_enrollment_token", "The enrollment token is invalid, expired or already used.")72	errBadCSR       = httpx.Validation("The certificate request is invalid (an ECDSA P-256 CSR in PEM is required).")73	errBadInventory = httpx.Validation("The inventory is invalid.")74	errAliasInUse   = httpx.Conflict("alias_in_use", "A different machine is already registered under this alias.")75	errNodeRetired  = httpx.Conflict("node_retired", "This machine was retired; restore the node before enrolling it again.")76)7778// handleEnroll exchanges a one-time token and a CSR for an agent identity.79// It is the only route reachable without a client certificate.80func (s *Server) handleEnroll(w http.ResponseWriter, r *http.Request) {81	ip := clientIP(r)82	if ok, retry := s.enrollLimiter.Allow("enroll:" + ip.String()); !ok {83		e := *httpx.ErrRateLimited84		e.RetryAfter = retry85		httpx.WriteError(w, r, &e)86		return87	}88	// Cheap shape check before any parsing or database work.89	tokenHash, err := secret.Parse(r.Header.Get(enrollTokenHeader))90	if err != nil {91		httpx.WriteError(w, r, errEnrollToken)92		return93	}94	var req protocol.EnrollRequest95	if err := decodeBody(w, r, 256<<10, &req); err != nil {96		httpx.WriteError(w, r, err)97		return98	}99	csr, err := pki.ParseCSR([]byte(req.CSRPEM))100	if err != nil {101		httpx.WriteError(w, r, errBadCSR)102		return103	}104	inv := req.Inventory105	if err := sanitizeInventory(&inv); err != nil || inv.HardwareUUID == "" {106		httpx.WriteError(w, r, errBadInventory)107		return108	}109	version := clip(req.AgentVersion, 64)110111	ctx, cancel := context.WithTimeout(r.Context(), s.reqTimeout)112	defer cancel()113114	var resp protocol.EnrollResponse115	var denied *httpx.Error116	err = s.inTx(ctx, func(tx pgx.Tx) error {117		// Atomic single use: of N concurrent presentations exactly one gets the row.118		var tokenID uuid.UUID119		var alias, kind string120		err := tx.QueryRow(ctx, `update agent_enrollment_tokens set consumed_at = now()121			where token_hash = $1 and consumed_at is null and revoked_at is null and expires_at > now()122			returning id, node_alias::text, node_kind::text`, tokenHash).Scan(&tokenID, &alias, &kind)123		if errors.Is(err, pgx.ErrNoRows) {124			denied = errEnrollToken125			return denied126		}127		if err != nil {128			return err129		}130		// One enrollment at a time per machine.131		if _, err := tx.Exec(ctx, `select pg_advisory_xact_lock(hashtextextended($1, 7731))`, "enroll:"+inv.HardwareUUID); err != nil {132			return err133		}134135		var nodeID uuid.UUID136		var nodeAlias string137		var retired *time.Time138		detail := ""139		created := false140		err = tx.QueryRow(ctx, `select id, alias::text, retired_at from nodes where hardware_uuid = $1 for update`, inv.HardwareUUID).141			Scan(&nodeID, &nodeAlias, &retired)142		switch {143		case err == nil:144			if retired != nil {145				denied = errNodeRetired146				return denied147			}148			if !strings.EqualFold(nodeAlias, alias) {149				detail = fmt.Sprintf("token issued for alias %q; hardware already registered as %q, existing node and alias kept", alias, nodeAlias)150			}151		case errors.Is(err, pgx.ErrNoRows):152			var hw *string153			err = tx.QueryRow(ctx, `select id, alias::text, hardware_uuid, retired_at from nodes where alias = $1 for update`, alias).154				Scan(&nodeID, &nodeAlias, &hw, &retired)155			switch {156			case err == nil:157				if hw != nil && *hw != "" {158					denied = errAliasInUse159					return denied160				}161				if retired != nil {162					denied = errNodeRetired163					return denied164				}165				if _, err := tx.Exec(ctx, `update nodes set hardware_uuid = $2 where id = $1`, nodeID, inv.HardwareUUID); err != nil {166					return err167				}168				detail = "adopted the manually registered node " + nodeAlias169			case errors.Is(err, pgx.ErrNoRows):170				nodeID, nodeAlias, created = ids.New(), alias, true171				nk := kind172				if inv.Kind == "mac" || inv.Kind == "linux" {173					nk = inv.Kind174				}175				if _, err := tx.Exec(ctx, `insert into nodes(id, hardware_uuid, alias, kind, registered_via) values ($1,$2,$3,$4::node_kind,'agent')`,176					nodeID, inv.HardwareUUID, alias, nk); err != nil {177					return err178				}179				detail = "node created"180			default:181				return err182			}183		default:184			return err185		}186187		// Re-enrollment: the previous identity of this node stops working now.188		tag, err := tx.Exec(ctx, `update agents set revoked_at = now(), revoked_reason = 're-enrolled' where node_id = $1 and revoked_at is null`, nodeID)189		if err != nil {190			return err191		}192		if tag.RowsAffected() > 0 {193			detail = strings.TrimPrefix(detail+"; previous agent revoked (re-enrollment)", "; ")194		}195196		agentID := ids.New()197		now := time.Now().UTC()198		certPEM, cert, err := s.ca.SignAgent(csr, agentID, now)199		if err != nil {200			return err201		}202		fp := sha256.Sum256(cert.Raw)203		if _, err := tx.Exec(ctx, `insert into agents(id, node_id, cert_serial, cert_fingerprint, cert_not_after, version, os, last_seen_at)204			values ($1,$2,$3,$4,$5,$6,$7, now())`,205			agentID, nodeID, pki.SerialString(cert.SerialNumber), fp[:], cert.NotAfter, version, inv.Kind); err != nil {206			return err207		}208		if _, err := applyInventory(ctx, tx, nodeID, &inv); err != nil {209			return err210		}211		if _, err := tx.Exec(ctx, `update nodes set last_seen_at = now() where id = $1`, nodeID); err != nil {212			return err213		}214		keys, err := commandKeys(ctx, tx)215		if err != nil {216			return err217		}218		var ipp *netip.Addr219		if ip.IsValid() {220			ipp = &ip221		}222		if _, err := audit.Append(ctx, tx, audit.Entry{223			ActorKind: "agent", ActorID: &agentID, ActorLabel: nodeAlias, IP: ipp,224			Action: "agent.enrolled", TargetKind: "node", TargetID: nodeID.String(),225			Params: map[string]any{226				"alias": nodeAlias, "token_alias": alias, "enrollment_id": tokenID.String(), "node_created": created,227				"agent_version": version, "cert_serial": pki.SerialString(cert.SerialNumber),228				"cert_not_after": cert.NotAfter.UTC().Format(time.RFC3339), "model": inv.Model, "os_version": inv.OSVersion,229			},230			Outcome: audit.Success, Detail: detail, CorrelationID: httpx.Correlation(r.Context()),231		}); err != nil {232			return err233		}234		if err := events.Publish(ctx, tx, "node.updated", map[string]any{"node_id": nodeID, "reason": "agent_enrolled"}); err != nil {235			return err236		}237		resp = protocol.EnrollResponse{238			AgentID: agentID.String(), NodeID: nodeID.String(), CertPEM: string(certPEM), CAPEM: string(s.ca.PEM),239			CommandKeys: keys, Endpoints: s.cfg.IngestAdvertise, ServerName: s.cfg.IngestServerName, IntervalS: s.intervalS,240		}241		return nil242	})243	if err != nil {244		if denied != nil {245			// Refusals are audited outside the rolled-back transaction, best effort.246			s.auditEnrollDenied(r, ip, denied, inv.HardwareUUID)247		}248		s.writeErr(w, r, err)249		return250	}251	s.forgetAuth()252	s.log.Info("ingest: agent enrolled", "agent_id", resp.AgentID, "node_id", resp.NodeID, "ip", ip.String())253	writeJSON(w, http.StatusOK, resp)254}255256func (s *Server) auditEnrollDenied(r *http.Request, ip netip.Addr, reason *httpx.Error, hw string) {257	ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 5*time.Second)258	defer cancel()259	var ipp *netip.Addr260	if ip.IsValid() {261		ipp = &ip262	}263	if _, err := audit.Append(ctx, s.pool, audit.Entry{264		ActorKind: "agent", ActorLabel: "unenrolled", IP: ipp, Action: "agent.enroll_denied",265		Params:  map[string]any{"reason": reason.Code, "hardware_uuid": hw},266		Outcome: audit.Denied, Detail: reason.Message, CorrelationID: httpx.Correlation(r.Context()),267	}); err != nil {268		s.log.Warn("ingest: could not audit enrollment refusal", "err", err)269	}270}271272// commandKeys returns the active command verification keys (public material).273func commandKeys(ctx context.Context, q interface {274	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)275}) (map[string]string, error) {276	rows, err := q.Query(ctx, `select key_id, public_key from command_keys where retired_at is null`)277	if err != nil {278		return nil, err279	}280	defer rows.Close()281	out := map[string]string{}282	for rows.Next() {283		var id string284		var pub []byte285		if err := rows.Scan(&id, &pub); err != nil {286			return nil, err287		}288		out[id] = base64.StdEncoding.EncodeToString(pub)289	}290	return out, rows.Err()291}292293// handleRenew issues a new certificate for the same agent from a new CSR.294// The previous certificate stays valid for a short overlap so a lost response295// cannot lock the agent out.296func (s *Server) handleRenew(w http.ResponseWriter, r *http.Request) {297	a := agentFrom(r.Context())298	var req protocol.RenewRequest299	if err := decodeBody(w, r, 64<<10, &req); err != nil {300		httpx.WriteError(w, r, err)301		return302	}303	csr, err := pki.ParseCSR([]byte(req.CSRPEM))304	if err != nil {305		httpx.WriteError(w, r, errBadCSR)306		return307	}308	ctx, cancel := context.WithTimeout(r.Context(), s.reqTimeout)309	defer cancel()310	now := time.Now().UTC()311	certPEM, cert, err := s.ca.SignAgent(csr, a.ID, now)312	if err != nil {313		s.writeErr(w, r, err)314		return315	}316	leaf := leafFrom(r.Context())317	presented := pki.SerialString(leaf.SerialNumber)318	fp := sha256.Sum256(cert.Raw)319	var resp protocol.RenewResponse320	err = s.inTx(ctx, func(tx pgx.Tx) error {321		// The overlap is granted to the certificate that asked for the renewal.322		tag, err := tx.Exec(ctx, `update agents set323				prev_cert_serial = $2,324				prev_cert_valid_until = least(now() + interval '24 hours', $3::timestamptz),325				cert_serial = $4, cert_fingerprint = $5, cert_not_after = $6326			where id = $1 and revoked_at is null`,327			a.ID, presented, leaf.NotAfter, pki.SerialString(cert.SerialNumber), fp[:], cert.NotAfter)328		if err != nil {329			return err330		}331		if tag.RowsAffected() == 0 {332			return errAgentRevoked333		}334		keys, err := commandKeys(ctx, tx)335		if err != nil {336			return err337		}338		ip := clientIP(r)339		var ipp *netip.Addr340		if ip.IsValid() {341			ipp = &ip342		}343		if _, err := audit.Append(ctx, tx, audit.Entry{344			ActorKind: "agent", ActorID: &a.ID, IP: ipp, Action: "agent.cert_renewed",345			TargetKind: "node", TargetID: a.NodeID.String(),346			Params: map[string]any{"cert_serial": pki.SerialString(cert.SerialNumber), "previous_serial": presented,347				"cert_not_after": cert.NotAfter.UTC().Format(time.RFC3339)},348			Outcome: audit.Success, CorrelationID: httpx.Correlation(r.Context()),349		}); err != nil {350			return err351		}352		resp = protocol.RenewResponse{CertPEM: string(certPEM), CAPEM: string(s.ca.PEM), CommandKeys: keys}353		return nil354	})355	if err != nil {356		s.writeErr(w, r, err)357		return358	}359	s.forgetAuth()360	writeJSON(w, http.StatusOK, resp)361}362363// ─────────────────────────── inventory ───────────────────────────364365func clip(s string, n int) string {366	s = strings.ToValidUTF8(strings.TrimSpace(s), "")367	s = strings.Map(func(r rune) rune {368		if r < 0x20 || r == 0x7f {369			return -1370		}371		return r372	}, s)373	if len(s) > n {374		s = s[:n]375		s = strings.ToValidUTF8(s, "")376	}377	return s378}379380// sanitizeInventory bounds every field an agent controls.381func sanitizeInventory(inv *protocol.Inventory) error {382	inv.HardwareUUID = clip(inv.HardwareUUID, 64)383	if strings.ContainsAny(inv.HardwareUUID, " /\\") {384		return errors.New("hardware uuid")385	}386	inv.Hostname, inv.Model, inv.Chip, inv.Arch = clip(inv.Hostname, 128), clip(inv.Model, 64), clip(inv.Chip, 96), clip(inv.Arch, 16)387	inv.GPUModel, inv.OSName, inv.OSVersion = clip(inv.GPUModel, 96), clip(inv.OSName, 32), clip(inv.OSVersion, 32)388	inv.OSBuild, inv.Kernel = clip(inv.OSBuild, 32), clip(inv.Kernel, 96)389	if inv.Kind != "mac" && inv.Kind != "linux" {390		return errors.New("kind")391	}392	if inv.CPUCores < 0 || inv.CPUCores > 4096 || inv.GPUCores < 0 || inv.GPUCores > 4096 || inv.MemBytes < 0 || inv.StorageBytes < 0 {393		return errors.New("counts")394	}395	if len(inv.CPULevels) > 8 || len(inv.Interfaces) > 32 || len(inv.Managers) > 8 {396		return errors.New("too many items")397	}398	for i := range inv.CPULevels {399		inv.CPULevels[i].Name = clip(inv.CPULevels[i].Name, 32)400		if inv.CPULevels[i].Cores < 0 || inv.CPULevels[i].Cores > 4096 {401			return errors.New("cpu level")402		}403	}404	for i := range inv.Interfaces {405		it := &inv.Interfaces[i]406		it.Name, it.Kind, it.MAC, it.Media = clip(it.Name, 32), clip(it.Kind, 16), clip(it.MAC, 32), clip(it.Media, 96)407		if len(it.Addrs) > 16 {408			it.Addrs = it.Addrs[:16]409		}410		for j := range it.Addrs {411			it.Addrs[j] = clip(it.Addrs[j], 64)412		}413	}414	for i := range inv.Managers {415		inv.Managers[i] = clip(inv.Managers[i], 16)416	}417	return nil418}419420// primaryIP picks the address of the default-route interface (IPv4 first).421func primaryIP(inv *protocol.Inventory) *string {422	pick := func(onlyDefault bool) *string {423		for _, want4 := range []bool{true, false} {424			for _, it := range inv.Interfaces {425				if !it.Up || (onlyDefault && !it.Default) || it.Kind == "tunnel" && !it.Default {426					continue427				}428				for _, a := range it.Addrs {429					p, err := netip.ParsePrefix(a)430					var ad netip.Addr431					if err == nil {432						ad = p.Addr()433					} else if ad, err = netip.ParseAddr(a); err != nil {434						continue435					}436					if ad.IsLoopback() || ad.IsLinkLocalUnicast() || ad.Is4() != want4 {437						continue438					}439					s := ad.String()440					return &s441				}442			}443		}444		return nil445	}446	if p := pick(true); p != nil {447		return p448	}449	return pick(false)450}451452// applyInventory stores an inventory on the node and reports whether it453// differs from the stored one.454func applyInventory(ctx context.Context, tx pgx.Tx, nodeID uuid.UUID, inv *protocol.Inventory) (changed bool, err error) {455	var prev *protocol.Inventory456	var prevAt *time.Time457	if err := tx.QueryRow(ctx, `select case when inventory_at is null then null else inventory end, inventory_at from nodes where id = $1 for update`, nodeID).458		Scan(&prev, &prevAt); err != nil {459		return false, err460	}461	changed = prev == nil || !reflect.DeepEqual(normalizeInv(*prev), normalizeInv(*inv))462	levels := inv.CPULevels463	if levels == nil {464		levels = []protocol.CPULevel{}465	}466	_, err = tx.Exec(ctx, `update nodes set467			hostname = $2, model = nullif($3,''), chip = nullif($4,''), arch = nullif($5,''),468			cpu_cores = nullif($6,0), cpu_levels = $7, gpu_cores = nullif($8,0),469			mem_bytes = nullif($9::bigint,0), storage_bytes = nullif($10::bigint,0),470			os_name = nullif($11,''), os_version = nullif($12,''), os_build = nullif($13,''),471			primary_ip = coalesce($14::inet, primary_ip), kind = $15::node_kind,472			inventory = $16, inventory_at = now()473		where id = $1`,474		nodeID, inv.Hostname, inv.Model, inv.Chip, inv.Arch, inv.CPUCores, mustJSON(levels), inv.GPUCores,475		inv.MemBytes, inv.StorageBytes, inv.OSName, inv.OSVersion, inv.OSBuild, primaryIP(inv), inv.Kind, mustJSON(inv))476	return changed, err477}478479func normalizeInv(i protocol.Inventory) protocol.Inventory {480	i.BootTime = i.BootTime.UTC().Truncate(time.Minute)481	if len(i.CPULevels) == 0 {482		i.CPULevels = nil483	}484	if len(i.Interfaces) == 0 {485		i.Interfaces = nil486	}487	if len(i.Managers) == 0 {488		i.Managers = nil489	}490	for k := range i.Interfaces {491		if len(i.Interfaces[k].Addrs) == 0 {492			i.Interfaces[k].Addrs = nil493		}494	}495	return i496}497
Files main
Menu

Theme