Repository Public
1// Command mcc-agent is the node agent of MacLustr Command Center.2//3// mcc-agent enroll --endpoints host:port[,…] --token … --ca-fingerprint sha256:<hex> [--state-dir …]4// mcc-agent run [--state-dir …]5// mcc-agent status [--state-dir …] [--json]6// mcc-agent policy check [--state-dir …]7// mcc-agent catalog --markdown8// mcc-agent version9//10// The agent never listens on a port and never runs as root. Exit status 7511// after `run` means "restart me" (an accepted agent.restart command): the12// supervisor (launchd KeepAlive, systemd Restart=always) starts it again.13package main1415import (16 "context"17 "encoding/json"18 "errors"19 "flag"20 "fmt"21 "log/slog"22 "os"23 "os/signal"24 "runtime"25 "runtime/debug"26 "strings"27 "syscall"28 "time"2930 "clustr.spboucher.ai/mcc/internal/agent"31 "clustr.spboucher.ai/mcc/internal/agent/client"32 "clustr.spboucher.ai/mcc/internal/agent/collect"33 "clustr.spboucher.ai/mcc/internal/agent/policy"34 "clustr.spboucher.ai/mcc/internal/agent/spool"35 "clustr.spboucher.ai/mcc/internal/agent/state"36 "clustr.spboucher.ai/mcc/internal/buildinfo"37 "clustr.spboucher.ai/mcc/internal/pki"38 "clustr.spboucher.ai/mcc/internal/protocol"39)4041func main() {42 if len(os.Args) < 2 {43 usage()44 os.Exit(2)45 }46 var err error47 code := 048 switch os.Args[1] {49 case "enroll":50 err = cmdEnroll(os.Args[2:])51 case "run":52 code, err = cmdRun(os.Args[2:])53 case "status":54 err = cmdStatus(os.Args[2:])55 case "policy":56 if len(os.Args) < 3 || os.Args[2] != "check" {57 err = errors.New("usage: mcc-agent policy check [--state-dir …]")58 } else {59 err = cmdPolicyCheck(os.Args[3:])60 }61 case "catalog":62 err = cmdCatalog(os.Args[2:])63 case "version", "--version", "-v":64 fmt.Printf("mcc-agent %s %s/%s protocol v%d\n", buildinfo.String(), runtime.GOOS, runtime.GOARCH, protocol.Version)65 case "help", "--help", "-h":66 usage()67 default:68 usage()69 os.Exit(2)70 }71 if err != nil {72 fmt.Fprintln(os.Stderr, "mcc-agent:", err)73 os.Exit(1)74 }75 os.Exit(code)76}7778func usage() {79 fmt.Fprint(os.Stderr, `mcc-agent — MacLustr Command Center node agent8081 enroll --endpoints host:port[,…] --token T --ca-fingerprint sha256:<hex> [--state-dir DIR]82 run [--state-dir DIR] [--label NAME]83 status [--state-dir DIR] [--json]84 policy check [--state-dir DIR]85 catalog --markdown86 version87`)88}8990func openDir(path string) (*state.Dir, error) {91 if path == "" {92 path = state.DefaultPath()93 }94 return state.Open(path)95}9697func cmdEnroll(args []string) error {98 fs := flag.NewFlagSet("enroll", flag.ContinueOnError)99 endpoints := fs.String("endpoints", "", "comma-separated host:port list of the ingest service, tried in order")100 token := fs.String("token", os.Getenv("MCC_ENROLL_TOKEN"), "one-time enrollment token (or MCC_ENROLL_TOKEN)")101 fpr := fs.String("ca-fingerprint", "", "sha256:<hex> fingerprint of the agent CA, shown by the Command Center")102 dirFlag := fs.String("state-dir", "", "state directory (default ~/.mcc-agent)")103 force := fs.Bool("force", false, "replace an existing identity")104 if err := fs.Parse(args); err != nil {105 return err106 }107 var eps []string108 for _, e := range strings.Split(*endpoints, ",") {109 if e = strings.TrimSpace(e); e != "" {110 eps = append(eps, e)111 }112 }113 if len(eps) == 0 || *token == "" || *fpr == "" {114 return errors.New("--endpoints, --token and --ca-fingerprint are required")115 }116 want, err := pki.ParseFingerprint(*fpr)117 if err != nil {118 return err119 }120 if os.Geteuid() == 0 {121 return errors.New("refusing to enroll as root: the agent runs as an ordinary user")122 }123 dir, err := openDir(*dirFlag)124 if err != nil {125 return err126 }127 if _, err := dir.LoadIdentity(); err == nil && !*force {128 return fmt.Errorf("%s already holds an identity; use --force to replace it", dir.Path)129 }130 if err := dir.Lock(); err != nil {131 return fmt.Errorf("%w (stop it before enrolling again)", err)132 }133 defer dir.Unlock()134 ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)135 defer stop()136 inv := collect.New().Inventory(ctx)137 if inv.HardwareUUID == "" {138 return errors.New("cannot read the hardware identity of this machine")139 }140 id, err := client.Enroll(ctx, dir, client.EnrollParams{Endpoints: eps, Token: *token, CAFingerprint: want, Inventory: inv, Version: buildinfo.Version})141 if err != nil {142 return err143 }144 fmt.Printf("enrolled: agent %s, node %s\nserver name %s, endpoints %s\nstate in %s\n",145 id.AgentID, id.NodeID, id.ServerName, strings.Join(id.Endpoints, ","), dir.Path)146 return nil147}148149func cmdRun(args []string) (int, error) {150 fs := flag.NewFlagSet("run", flag.ContinueOnError)151 dirFlag := fs.String("state-dir", "", "state directory (default ~/.mcc-agent)")152 label := fs.String("label", os.Getenv("MCC_AGENT_LABEL"), "launchd label / systemd unit running this agent")153 debugLog := fs.Bool("debug", false, "verbose logging")154 if err := fs.Parse(args); err != nil {155 return 2, err156 }157 if os.Geteuid() == 0 {158 return 1, errors.New("refusing to run as root: the agent runs as an ordinary user")159 }160 // Stay light: a soft memory ceiling and two OS threads of Go code are161 // plenty for a collector. Both can be overridden by the environment.162 if os.Getenv("GOMEMLIMIT") == "" {163 debug.SetMemoryLimit(64 << 20)164 }165 if os.Getenv("GOMAXPROCS") == "" {166 runtime.GOMAXPROCS(2)167 }168 level := slog.LevelInfo169 if *debugLog {170 level = slog.LevelDebug171 }172 log := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: level}))173 dir, err := openDir(*dirFlag)174 if err != nil {175 return 1, err176 }177 if err := dir.Lock(); err != nil {178 return 1, err179 }180 defer dir.Unlock()181 a, err := agent.New(agent.Options{Dir: dir, Version: buildinfo.Version, Log: log, OwnLabel: *label})182 if err != nil {183 return 1, err184 }185 ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)186 defer stop()187 log.Info("mcc-agent starting", "version", buildinfo.String(), "state_dir", dir.Path, "pid", os.Getpid())188 code := a.Run(ctx)189 log.Info("mcc-agent stopped", "exit_code", code)190 return code, nil191}192193func cmdStatus(args []string) error {194 fs := flag.NewFlagSet("status", flag.ContinueOnError)195 dirFlag := fs.String("state-dir", "", "state directory (default ~/.mcc-agent)")196 asJSON := fs.Bool("json", false, "machine-readable output")197 if err := fs.Parse(args); err != nil {198 return err199 }200 dir, err := openDir(*dirFlag)201 if err != nil {202 return err203 }204 id, err := dir.LoadIdentity()205 if err != nil {206 return err207 }208 cert, _, err := dir.LoadCredentials()209 if err != nil {210 return err211 }212 sp, err := spool.Open(agent.SpoolDir(dir), 0, 0)213 if err != nil {214 return err215 }216 n, bytes, _ := sp.Stats()217 st, _ := dir.LoadStatus()218 pol, perr := policy.Load(dir.File(state.PolicyFile))219 out := map[string]any{220 "agent_id": id.AgentID, "node_id": id.NodeID, "server_name": id.ServerName, "endpoints": id.Endpoints,221 "enrolled_at": id.EnrolledAt, "state_dir": dir.Path,222 "cert_serial": pki.SerialString(cert.Leaf.SerialNumber), "cert_not_after": cert.Leaf.NotAfter.UTC(),223 "cert_days_left": int(time.Until(cert.Leaf.NotAfter).Hours() / 24),224 "buffer_reports": n, "buffer_bytes": bytes, "frozen": dir.Frozen(), "capabilities": pol.Capabilities(),225 }226 if perr != nil {227 out["policy_error"] = perr.Error()228 }229 if st != nil {230 out["runtime"] = st231 }232 if *asJSON {233 enc := json.NewEncoder(os.Stdout)234 enc.SetIndent("", " ")235 return enc.Encode(out)236 }237 fmt.Printf("agent %s\nnode %s\nserver %s via %s\nenrolled %s\n", id.AgentID, id.NodeID, id.ServerName,238 strings.Join(id.Endpoints, ","), id.EnrolledAt.Format(time.RFC3339))239 fmt.Printf("certificate serial %s, expires %s (%d days)\n", out["cert_serial"], cert.Leaf.NotAfter.UTC().Format(time.RFC3339), out["cert_days_left"])240 fmt.Printf("buffer %d reports, %d bytes\n", n, bytes)241 fmt.Printf("kill switch %v (file %s)\n", dir.Frozen(), dir.File(state.FreezeFile))242 fmt.Printf("policy allows %s\n", strings.Join(pol.Capabilities(), ", "))243 if perr != nil {244 fmt.Printf("policy ERROR %v\n", perr)245 }246 if st == nil {247 fmt.Println("runtime never run (no status file)")248 return nil249 }250 age := time.Since(st.UpdatedAt).Round(time.Second)251 running := "not running"252 if st.PID > 0 && syscall.Kill(st.PID, 0) == nil && age < 2*time.Minute {253 running = fmt.Sprintf("running, pid %d", st.PID)254 }255 fmt.Printf("runtime %s, version %s, status written %s ago\n", running, st.Version, age)256 last := "never"257 if !st.LastReportOK.IsZero() {258 last = fmt.Sprintf("%s (%s ago), seq %d", st.LastReportOK.Format(time.RFC3339), time.Since(st.LastReportOK).Round(time.Second), st.LastSeq)259 }260 fmt.Printf("connection %s via %s\nlast report %s\n", st.Connection, st.Endpoint, last)261 if st.LastError != "" {262 fmt.Printf("last error %s\n", st.LastError)263 }264 if st.SelfCPUPercent != nil && st.SelfRSSBytes != nil {265 fmt.Printf("overhead cpu %.2f %% of one core, rss %.1f MiB\n", *st.SelfCPUPercent, float64(*st.SelfRSSBytes)/(1<<20))266 }267 if st.Dropped > 0 {268 fmt.Printf("dropped %d buffered reports exceeded the bounds\n", st.Dropped)269 }270 return nil271}272273func cmdPolicyCheck(args []string) error {274 fs := flag.NewFlagSet("policy check", flag.ContinueOnError)275 dirFlag := fs.String("state-dir", "", "state directory (default ~/.mcc-agent)")276 if err := fs.Parse(args); err != nil {277 return err278 }279 dir, err := openDir(*dirFlag)280 if err != nil {281 return err282 }283 file := dir.File(state.PolicyFile)284 pol, err := policy.Load(file)285 if err != nil {286 return fmt.Errorf("%s is INVALID — every command is refused until it is fixed: %w", file, err)287 }288 if _, serr := os.Stat(file); errors.Is(serr, os.ErrNotExist) {289 fmt.Printf("%s does not exist: default policy (read-only commands)\n", file)290 } else {291 fmt.Printf("%s is valid\n", file)292 }293 fmt.Printf("allowed command types: %s\n", strings.Join(pol.Capabilities(), ", "))294 for mgr, pats := range pol.Services {295 fmt.Printf("services (%s): %s\n", mgr, strings.Join(pats, ", "))296 }297 for name := range pol.Caches {298 if p, err := pol.CachePath(name); err != nil {299 fmt.Printf("cache %s: NOT USABLE: %v\n", name, err)300 } else {301 fmt.Printf("cache %s: %s\n", name, p)302 }303 }304 for name, j := range pol.Jobs {305 fmt.Printf("job %s: %s (%d parameters)\n", name, strings.Join(j.Argv, " "), len(j.Params))306 }307 fmt.Printf("reboot allowed: %v, shutdown allowed: %v\n", pol.AllowReboot, pol.AllowShutdown)308 if dir.Frozen() {309 fmt.Println("FREEZE file present: every command is refused regardless of the policy")310 }311 return nil312}313314func cmdCatalog(args []string) error {315 fs := flag.NewFlagSet("catalog", flag.ContinueOnError)316 md := fs.Bool("markdown", false, "print docs/METRICS-CATALOG.md")317 observed := fs.String("observed", "", "JSON file of per-OS availability observed in a pilot run")318 if err := fs.Parse(args); err != nil {319 return err320 }321 if !*md {322 enc := json.NewEncoder(os.Stdout)323 enc.SetIndent("", " ")324 return enc.Encode(protocol.Catalog)325 }326 var obs *observedDoc327 if *observed != "" {328 b, err := os.ReadFile(*observed)329 if err != nil {330 return err331 }332 obs = &observedDoc{}333 if err := json.Unmarshal(b, obs); err != nil {334 return fmt.Errorf("%s: %w", *observed, err)335 }336 }337 fmt.Print(catalogMarkdown(obs))338 return nil339}340