Repository Public
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