SPB Git

Repository Public

client.go 18.6 KB 609 lines go

1// Package client is the agent's side of the wire protocol: enrollment with2// CA pinning, then mutually authenticated calls to the ingest service.3package client45import (6	"bytes"7	"compress/gzip"8	"context"9	"crypto/ecdsa"10	"crypto/elliptic"11	"crypto/rand"12	"crypto/sha256"13	"crypto/subtle"14	"crypto/tls"15	"crypto/x509"16	"crypto/x509/pkix"17	"encoding/base64"18	"encoding/json"19	"encoding/pem"20	"errors"21	"fmt"22	"io"23	mrand "math/rand/v2"24	"net"25	"net/http"26	"net/url"27	"os"28	"strconv"29	"strings"30	"sync"31	"time"3233	"clustr.spboucher.ai/mcc/internal/agent/state"34	"clustr.spboucher.ai/mcc/internal/protocol"35)3637// APIError is an HTTP-level refusal by the server.38type APIError struct {39	Status  int40	Code    string41	Message string42}4344func (e *APIError) Error() string {45	return fmt.Sprintf("server answered %d %s: %s", e.Status, e.Code, e.Message)46}4748// Permanent reports whether retrying the same request can never succeed.49func Permanent(err error) bool {50	var ae *APIError51	if !errors.As(err, &ae) {52		return false53	}54	switch ae.Status {55	case http.StatusBadRequest, http.StatusNotFound, http.StatusConflict, http.StatusRequestEntityTooLarge,56		http.StatusUnsupportedMediaType, http.StatusUnprocessableEntity:57		return true58	}59	return false60}6162// Revoked reports whether the server no longer recognises this agent.63func Revoked(err error) bool {64	var ae *APIError65	return errors.As(err, &ae) && ae.Status == http.StatusUnauthorized66}6768func decodeError(resp *http.Response) error {69	body, _ := io.ReadAll(io.LimitReader(resp.Body, 16<<10))70	var doc struct {71		Error struct {72			Code    string `json:"code"`73			Message string `json:"message"`74		} `json:"error"`75	}76	json.Unmarshal(body, &doc)77	if doc.Error.Code == "" {78		doc.Error.Code = http.StatusText(resp.StatusCode)79	}80	return &APIError{Status: resp.StatusCode, Code: doc.Error.Code, Message: doc.Error.Message}81}8283func newKeyAndCSR(cn string) (*ecdsa.PrivateKey, []byte, error) {84	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)85	if err != nil {86		return nil, nil, err87	}88	der, err := x509.CreateCertificateRequest(rand.Reader, &x509.CertificateRequest{Subject: pkix.Name{CommonName: cn}}, key)89	if err != nil {90		return nil, nil, err91	}92	return key, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE REQUEST", Bytes: der}), nil93}9495func transport(cfg *tls.Config) *http.Transport {96	return &http.Transport{97		Proxy:                 nil, // never through a proxy: the peer is authenticated end to end98		DialContext:           (&net.Dialer{Timeout: 5 * time.Second, KeepAlive: 30 * time.Second}).DialContext,99		TLSClientConfig:       cfg,100		TLSHandshakeTimeout:   8 * time.Second,101		ResponseHeaderTimeout: 0,102		MaxIdleConns:          4,103		MaxIdleConnsPerHost:   2,104		IdleConnTimeout:       90 * time.Second,105		ForceAttemptHTTP2:     false,106	}107}108109// IsURL reports whether an endpoint selects the signed-request transport110// (a URL) rather than direct mTLS (host:port).111func IsURL(endpoint string) bool { return strings.Contains(endpoint, "://") }112113// CheckEndpoint validates one endpoint. A URL must be https; plain http is114// accepted for loopback only (development, or a local front on the node).115func CheckEndpoint(endpoint string) error {116	if !IsURL(endpoint) {117		if _, _, err := net.SplitHostPort(endpoint); err != nil {118			return fmt.Errorf("endpoint %q must be host:port or an https URL", endpoint)119		}120		return nil121	}122	u, err := url.Parse(endpoint)123	if err != nil || u.Host == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" {124		return fmt.Errorf("endpoint %q is not a valid base URL", endpoint)125	}126	switch u.Scheme {127	case "https":128		return nil129	case "http":130		if h := u.Hostname(); h == "localhost" || net.ParseIP(h) != nil && net.ParseIP(h).IsLoopback() {131			return nil132		}133		return fmt.Errorf("endpoint %q: plain http is accepted for loopback only", endpoint)134	}135	return fmt.Errorf("endpoint %q: unsupported scheme", endpoint)136}137138// publicTransport verifies servers with the system roots (WebPKI), as any139// HTTPS client: used by the signed-request transport, where the agent is140// authenticated by a signature on each request instead of a client certificate.141func publicTransport() *http.Transport {142	return transport(&tls.Config{MinVersion: tls.VersionTLS12})143}144145// Jitter returns d ± 25 %.146func Jitter(d time.Duration) time.Duration {147	return time.Duration(float64(d) * (0.75 + 0.5*mrand.Float64()))148}149150// ErrPin is returned when the server does not present the pinned CA.151var ErrPin = errors.New("the server's certificate chain does not contain the pinned CA (wrong --ca-fingerprint, or not the Command Center)")152153// pinnedTLS trusts exactly one CA, identified by the SHA-256 of its DER154// certificate. Used once, for enrollment, when no CA is installed yet.155func pinnedTLS(want []byte) *tls.Config {156	return &tls.Config{157		MinVersion:         tls.VersionTLS13,158		InsecureSkipVerify: true, // replaced by the pin check below, which is stricter159		VerifyPeerCertificate: func(raw [][]byte, _ [][]*x509.Certificate) error {160			if len(raw) == 0 {161				return ErrPin162			}163			var ca *x509.Certificate164			for _, der := range raw[1:] {165				sum := sha256.Sum256(der)166				if subtle.ConstantTimeCompare(sum[:], want) == 1 {167					c, err := x509.ParseCertificate(der)168					if err != nil {169						return ErrPin170					}171					ca = c172				}173			}174			if ca == nil || !ca.IsCA {175				return ErrPin176			}177			leaf, err := x509.ParseCertificate(raw[0])178			if err != nil {179				return ErrPin180			}181			roots := x509.NewCertPool()182			roots.AddCert(ca)183			if _, err := leaf.Verify(x509.VerifyOptions{Roots: roots, KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}}); err != nil {184				return fmt.Errorf("%w: %v", ErrPin, err)185			}186			return nil187		},188	}189}190191// EnrollParams are the inputs of `mcc-agent enroll`.192type EnrollParams struct {193	Endpoints     []string // host:port, tried in order194	Token         string195	CAFingerprint []byte // SHA-256 of the CA certificate (DER)196	Inventory     protocol.Inventory197	Version       string198	Attempts      int // rounds over the endpoint list (default 3)199}200201// Enroll generates the agent key locally, proves possession with a CSR,202// and stores the identity. The private key never leaves this process203// except to the state directory (0600).204func Enroll(ctx context.Context, dir *state.Dir, p EnrollParams) (*state.Identity, error) {205	if len(p.Endpoints) == 0 {206		return nil, errors.New("no endpoint given")207	}208	if len(p.CAFingerprint) != sha256.Size {209		return nil, errors.New("a sha256 CA fingerprint is required")210	}211	if p.Attempts <= 0 {212		p.Attempts = 3213	}214	key, csrPEM, err := newKeyAndCSR("mcc-agent")215	if err != nil {216		return nil, err217	}218	body, err := json.Marshal(protocol.EnrollRequest{CSRPEM: string(csrPEM), Inventory: p.Inventory, AgentVersion: p.Version})219	if err != nil {220		return nil, err221	}222	for _, ep := range p.Endpoints {223		if err := CheckEndpoint(ep); err != nil {224			return nil, err225		}226	}227	// mTLS endpoints: the private CA is pinned during the handshake.228	// URL endpoints: ordinary WebPKI; the enrollment is bound to the expected229	// control plane by comparing the returned CA with the pinned fingerprint.230	trPinned, trPublic := transport(pinnedTLS(p.CAFingerprint)), publicTransport()231	defer trPinned.CloseIdleConnections()232	defer trPublic.CloseIdleConnections()233	hcPinned := &http.Client{Transport: trPinned, Timeout: 30 * time.Second}234	hcPublic := &http.Client{Transport: trPublic, Timeout: 30 * time.Second, CheckRedirect: noRedirect}235236	var lastErr error237	backoff := time.Second238	for round := 0; round < p.Attempts; round++ {239		for _, ep := range p.Endpoints {240			hc, base := hcPinned, "https://"+ep241			if IsURL(ep) {242				hc, base = hcPublic, strings.TrimRight(ep, "/")243			}244			req, _ := http.NewRequestWithContext(ctx, http.MethodPost, base+"/agent/v1/enroll", bytes.NewReader(body))245			req.Header.Set("Content-Type", "application/json")246			req.Header.Set("X-MCC-Enroll-Token", p.Token)247			resp, err := hc.Do(req)248			if err != nil {249				lastErr = fmt.Errorf("%s: %w", ep, err)250				if errors.Is(err, ErrPin) {251					return nil, lastErr // a wrong pin will not get better by retrying252				}253				continue254			}255			if resp.StatusCode != http.StatusOK {256				err := decodeError(resp)257				resp.Body.Close()258				var ae *APIError259				if errors.As(err, &ae) && ae.Status >= 500 || ae.Status == http.StatusTooManyRequests {260					lastErr = fmt.Errorf("%s: %w", ep, err)261					continue262				}263				return nil, err // token refused, bad request…: definitive264			}265			var er protocol.EnrollResponse266			derr := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&er)267			var leaf *x509.Certificate268			if !IsURL(ep) && resp.TLS != nil && len(resp.TLS.PeerCertificates) > 0 {269				leaf = resp.TLS.PeerCertificates[0]270			}271			resp.Body.Close()272			if derr != nil {273				return nil, fmt.Errorf("enrollment response: %w", derr)274			}275			return finishEnroll(dir, key, &er, p, leaf)276		}277		select {278		case <-ctx.Done():279			return nil, ctx.Err()280		case <-time.After(Jitter(backoff)):281		}282		backoff *= 2283	}284	return nil, fmt.Errorf("enrollment failed on every endpoint: %w", lastErr)285}286287func finishEnroll(dir *state.Dir, key *ecdsa.PrivateKey, er *protocol.EnrollResponse, p EnrollParams, leaf *x509.Certificate) (*state.Identity, error) {288	// The CA handed back must be the pinned one. Nothing has been written to289	// the state directory yet: a mismatch leaves no trace of this enrollment.290	blk, _ := pem.Decode([]byte(er.CAPEM))291	if blk == nil {292		return nil, errors.New("enrollment response carries no CA certificate")293	}294	sum := sha256.Sum256(blk.Bytes)295	if subtle.ConstantTimeCompare(sum[:], p.CAFingerprint) != 1 {296		return nil, errors.New("enrollment response CA does not match the pinned fingerprint")297	}298	if er.AgentID == "" || er.ServerName == "" || er.CertPEM == "" {299		return nil, errors.New("enrollment response is incomplete")300	}301	// From now on the server is verified by name against the CA.302	if leaf != nil {303		if err := leaf.VerifyHostname(er.ServerName); err != nil {304			return nil, fmt.Errorf("the server certificate is not valid for %q: %w", er.ServerName, err)305		}306	}307	endpoints := er.Endpoints308	if len(endpoints) == 0 {309		endpoints = p.Endpoints310	}311	for _, ep := range endpoints {312		if err := CheckEndpoint(ep); err != nil {313			return nil, fmt.Errorf("enrollment response: %w", err)314		}315	}316	interval := er.IntervalS317	if interval <= 0 {318		interval = 10319	}320	if err := dir.SaveCredentials(key, []byte(er.CertPEM), []byte(er.CAPEM)); err != nil {321		return nil, err322	}323	if err := dir.SaveCommandKeys(er.CommandKeys); err != nil {324		return nil, err325	}326	id := &state.Identity{AgentID: er.AgentID, NodeID: er.NodeID, ServerName: er.ServerName, Endpoints: endpoints,327		IntervalS: interval, EnrolledAt: time.Now().UTC()}328	if err := dir.SaveIdentity(id); err != nil {329		return nil, err330	}331	return id, nil332}333334func noRedirect(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }335336// Client talks to the ingest service with the agent's certificate.337type Client struct {338	dir *state.Dir339	ID  *state.Identity340341	mu    sync.RWMutex342	cert  *tls.Certificate343	cur   int    // index of the endpoint in use344	saved string // endpoint recorded on disk as the last one that worked345346	tr    *http.Transport // direct mTLS, private CA347	trPub *http.Transport // signed requests, system roots348	fast  *http.Client    // reports, acks (mTLS)349	slow  *http.Client    // long-poll (mTLS)350	fastP *http.Client    // signed-request equivalents351	slowP *http.Client352}353354const fileLastEndpoint = "last-endpoint"355356// New loads the stored identity and credentials.357func New(dir *state.Dir) (*Client, error) {358	id, err := dir.LoadIdentity()359	if err != nil {360		return nil, err361	}362	for _, ep := range id.Endpoints {363		if err := CheckEndpoint(ep); err != nil {364			return nil, err365		}366	}367	cert, pool, err := dir.LoadCredentials()368	if err != nil {369		return nil, err370	}371	if _, ok := cert.PrivateKey.(*ecdsa.PrivateKey); !ok {372		return nil, errors.New("agent key is not ECDSA")373	}374	c := &Client{dir: dir, ID: id, cert: cert}375	// Start with the endpoint that worked last.376	if b, err := os.ReadFile(dir.File(fileLastEndpoint)); err == nil {377		for i, ep := range id.Endpoints {378			if ep == strings.TrimSpace(string(b)) {379				c.cur, c.saved = i, ep380			}381		}382	}383	c.tr = transport(&tls.Config{384		MinVersion: tls.VersionTLS13,385		RootCAs:    pool,386		ServerName: id.ServerName, // fixed name: the address used to reach the server does not matter387		GetClientCertificate: func(*tls.CertificateRequestInfo) (*tls.Certificate, error) {388			c.mu.RLock()389			defer c.mu.RUnlock()390			return c.cert, nil391		},392	})393	c.trPub = publicTransport()394	c.fast = &http.Client{Transport: c.tr, Timeout: 12 * time.Second}395	c.slow = &http.Client{Transport: c.tr}396	c.fastP = &http.Client{Transport: c.trPub, Timeout: 12 * time.Second, CheckRedirect: noRedirect}397	c.slowP = &http.Client{Transport: c.trPub, CheckRedirect: noRedirect}398	return c, nil399}400401// Close releases idle connections.402func (c *Client) Close() { c.tr.CloseIdleConnections(); c.trPub.CloseIdleConnections() }403404// Endpoint returns the endpoint currently in use.405func (c *Client) Endpoint() string {406	c.mu.RLock()407	defer c.mu.RUnlock()408	return c.ID.Endpoints[c.cur%len(c.ID.Endpoints)]409}410411// Host returns the host part of the endpoint in use.412func (c *Client) Host() string {413	ep := c.Endpoint()414	if IsURL(ep) {415		if u, err := url.Parse(ep); err == nil {416			return u.Hostname()417		}418		return ""419	}420	h, _, err := net.SplitHostPort(ep)421	if err != nil {422		return ""423	}424	return h425}426427// CertNotAfter returns the expiry of the client certificate.428func (c *Client) CertNotAfter() (notBefore, notAfter time.Time) {429	c.mu.RLock()430	defer c.mu.RUnlock()431	return c.cert.Leaf.NotBefore, c.cert.Leaf.NotAfter432}433434func (c *Client) rotate(from string) {435	c.mu.Lock()436	if c.ID.Endpoints[c.cur%len(c.ID.Endpoints)] == from {437		c.cur = (c.cur + 1) % len(c.ID.Endpoints)438	}439	c.mu.Unlock()440}441442// worked remembers, on disk, the endpoint that just answered, so the next443// start begins with it.444func (c *Client) worked(ep string) {445	c.mu.Lock()446	changed := c.saved != ep447	c.saved = ep448	c.mu.Unlock()449	if changed {450		state.WriteAtomic(c.dir.File(fileLastEndpoint), []byte(ep+"\n"), 0o600, false)451	}452}453454// do sends one request to the endpoint in use. slow selects the long-poll455// client. A transport failure moves to the next endpoint for the following456// call (callers own retry and backoff).457func (c *Client) do(ctx context.Context, slow bool, method, path string, body []byte, gz bool, out any) error {458	ep := c.Endpoint()459	var rd io.Reader460	if body != nil {461		rd = bytes.NewReader(body)462	}463	signed := IsURL(ep)464	base := "https://" + ep465	hc := c.fast466	switch {467	case signed && slow:468		hc = c.slowP469	case signed:470		hc = c.fastP471	case slow:472		hc = c.slow473	}474	if signed {475		base = strings.TrimRight(ep, "/")476	}477	req, err := http.NewRequestWithContext(ctx, method, base+path, rd)478	if err != nil {479		return err480	}481	if body != nil {482		req.Header.Set("Content-Type", "application/json")483		if gz {484			req.Header.Set("Content-Encoding", "gzip")485		}486	}487	if signed {488		// Proof of possession of the enrolled key on every request: TLS ends489		// at the public front, so the connection itself proves nothing.490		c.mu.RLock()491		cert := c.cert492		c.mu.RUnlock()493		ts, nonce := time.Now().UnixMilli(), protocol.NewRequestNonce()494		sig, err := protocol.SignRequest(cert.PrivateKey.(*ecdsa.PrivateKey), method, req.URL.RequestURI(), ts, nonce, body)495		if err != nil {496			return err497		}498		req.Header.Set(protocol.HeaderAgentCert, base64.StdEncoding.EncodeToString(cert.Certificate[0]))499		req.Header.Set(protocol.HeaderAgentTS, strconv.FormatInt(ts, 10))500		req.Header.Set(protocol.HeaderAgentNonce, nonce)501		req.Header.Set(protocol.HeaderAgentSig, sig)502	}503	resp, err := hc.Do(req)504	if err != nil {505		c.rotate(ep)506		return err507	}508	defer resp.Body.Close()509	if resp.StatusCode >= 300 {510		err := decodeError(resp)511		if resp.StatusCode >= 500 || resp.StatusCode < 400 {512			c.rotate(ep) // this front is unhealthy or misrouted; another may not be513		}514		return err515	}516	c.worked(ep)517	if out == nil || resp.StatusCode == http.StatusNoContent {518		io.Copy(io.Discard, io.LimitReader(resp.Body, 64<<10))519		return nil520	}521	return json.NewDecoder(io.LimitReader(resp.Body, 8<<20)).Decode(out)522}523524// EncodeReport serialises and compresses a report for the wire and the spool.525func EncodeReport(rep *protocol.Report) ([]byte, error) {526	var buf bytes.Buffer527	zw, _ := gzip.NewWriterLevel(&buf, gzip.BestSpeed)528	if err := json.NewEncoder(zw).Encode(rep); err != nil {529		return nil, err530	}531	if err := zw.Close(); err != nil {532		return nil, err533	}534	return buf.Bytes(), nil535}536537// Report posts an encoded report (see EncodeReport).538func (c *Client) Report(ctx context.Context, encoded []byte) (*protocol.ReportAck, error) {539	var ack protocol.ReportAck540	if err := c.do(ctx, false, http.MethodPost, "/agent/v1/report", encoded, true, &ack); err != nil {541		return nil, err542	}543	return &ack, nil544}545546// Commands long-polls for signed commands.547func (c *Client) Commands(ctx context.Context, wait time.Duration) (*protocol.CommandsResponse, error) {548	ctx, cancel := context.WithTimeout(ctx, wait+20*time.Second)549	defer cancel()550	var out protocol.CommandsResponse551	err := c.do(ctx, true, http.MethodGet, "/agent/v1/commands?wait="+strconv.Itoa(int(wait.Seconds())), nil, false, &out)552	if err != nil {553		return nil, err554	}555	return &out, nil556}557558func (c *Client) postJSON(ctx context.Context, path string, v any) error {559	b, err := json.Marshal(v)560	if err != nil {561		return err562	}563	return c.do(ctx, false, http.MethodPost, path, b, false, nil)564}565566func (c *Client) Ack(ctx context.Context, id string, ack protocol.CommandAck) error {567	return c.postJSON(ctx, "/agent/v1/commands/"+id+"/ack", ack)568}569570func (c *Client) Events(ctx context.Context, id string, lines []protocol.CommandOutput) error {571	return c.postJSON(ctx, "/agent/v1/commands/"+id+"/events", lines)572}573574func (c *Client) Result(ctx context.Context, id string, res protocol.CommandResult) error {575	return c.postJSON(ctx, "/agent/v1/commands/"+id+"/result", res)576}577578// Renew obtains a new certificate for a freshly generated key and switches579// to it. It returns the command keys sent by the server.580func (c *Client) Renew(ctx context.Context) error {581	key, csrPEM, err := newKeyAndCSR(c.ID.AgentID)582	if err != nil {583		return err584	}585	var rr protocol.RenewResponse586	b, _ := json.Marshal(protocol.RenewRequest{CSRPEM: string(csrPEM)})587	if err := c.do(ctx, false, http.MethodPost, "/agent/v1/renew", b, false, &rr); err != nil {588		return err589	}590	// The CA is never replaced by a renewal: trust stays anchored at enrollment.591	if err := c.dir.SaveCredentials(key, []byte(rr.CertPEM), nil); err != nil {592		return fmt.Errorf("renewed certificate rejected: %w", err)593	}594	if len(rr.CommandKeys) > 0 {595		if err := c.dir.SaveCommandKeys(rr.CommandKeys); err != nil {596			return err597		}598	}599	cert, _, err := c.dir.LoadCredentials()600	if err != nil {601		return err602	}603	c.mu.Lock()604	c.cert = cert605	c.mu.Unlock()606	c.tr.CloseIdleConnections()607	return nil608}609
Files main
Menu

Theme