fix: deliver execution-watchdog limit via config.json

Author: shubham-stepsecurity

cmd/stepsecurity-dev-machine-guard/main.go

@@ -232,7 +232,7 @@ func main() {
 			log.Error("Enterprise configuration not found. Run '%s configure' or download the script from your StepSecurity dashboard.", os.Args[0])
 			os.Exit(1)
 		}
-		armExecutionWatchdog(telemetry.ExecutionDeadlineFromEnv(), log)
+		armExecutionWatchdog(telemetry.ExecutionDeadline(config.MaxExecutionDuration), log)
 		if err := telemetry.Run(exec, log, cfg); err != nil {
 			log.Error("%v", err)
 			os.Exit(1)
@@ -265,9 +265,19 @@ func main() {
 			log.Error("Scheduled installation is not supported on %s", runtime.GOOS)
 			os.Exit(1)
 		}
+
+		// Persist the loader-exported max-execution duration into config.json so
+		// scheduler-fired runs (launchd/systemd/schtasks) — which invoke the
+		// binary directly and never inherit the loader's exported env var — arm
+		// the watchdog with the same value. Best-effort: a write failure just
+		// means scheduled runs fall back to the binary's built-in default.
+		if err := config.PersistMaxExecutionDuration(os.Getenv(telemetry.EnvMaxExecutionDuration)); err != nil {
+			log.Warn("failed to persist max execution duration to config (%v) — scheduled runs will use the built-in default", err)
+		}
+
 		log.Progress("Sending initial telemetry...")
 		fmt.Println()
-		armExecutionWatchdog(telemetry.ExecutionDeadlineFromEnv(), log)
+		armExecutionWatchdog(telemetry.ExecutionDeadline(config.MaxExecutionDuration), log)
 		telemetryErr := telemetry.Run(exec, log, cfg)
 
 		// On Linux, systemd.Install enabled the timer but did not start it.
@@ -371,7 +381,7 @@ func main() {
 			}
 		case config.IsEnterpriseMode():
 			log.Debug("dispatch: enterprise telemetry (auto-detected)")
-			armExecutionWatchdog(telemetry.ExecutionDeadlineFromEnv(), log)
+			armExecutionWatchdog(telemetry.ExecutionDeadline(config.MaxExecutionDuration), log)
 			if err := telemetry.Run(exec, log, cfg); err != nil {
 				log.Error("%v", err)
 				os.Exit(1)

internal/config/config.go

@@ -27,22 +27,33 @@ var (
 	InstallDir          string // "" means default (~/.stepsecurity); non-empty makes the agent put all its files (logs, hook errors, future state) under this directory. Bootstrap config.json itself stays at the legacy location. Per-run opt-out is the CLI flag --install-dir=. Resolution: --install-dir flag > STEPSECURITY_HOME env > this field > default — see internal/paths.
 )
 
+// MaxExecutionDuration is the whole-process execution-watchdog limit
+// (STEPSEC_MAX_EXECUTION_DURATION). Persisted into config.json at install time
+// so scheduler-fired runs (launchd/systemd/schtasks) — which invoke the binary
+// directly and never inherit the loader-exported env var — resolve the same
+// value the loader configured. "" means fall back to the binary's built-in
+// default (4h). Declared in its own var block (not the placeholder group
+// above) because it carries no build-time {{...}} placeholder. See
+// telemetry.ExecutionDeadline.
+var MaxExecutionDuration string
+
 // ConfigFile is the JSON structure persisted to ~/.stepsecurity/config.json.
 type ConfigFile struct {
-	CustomerID          string   `json:"customer_id,omitempty"`
-	APIEndpoint         string   `json:"api_endpoint,omitempty"`
-	APIKey              string   `json:"api_key,omitempty"`
-	ScanFrequencyHours  string   `json:"scan_frequency_hours,omitempty"`
-	SearchDirs          []string `json:"search_dirs,omitempty"`
-	EnableNPMScan       *bool    `json:"enable_npm_scan,omitempty"`
-	EnableBrewScan      *bool    `json:"enable_brew_scan,omitempty"`
-	EnablePythonScan    *bool    `json:"enable_python_scan,omitempty"`
-	IncludeTCCProtected *bool    `json:"include_tcc_protected,omitempty"`
-	ColorMode           string   `json:"color_mode,omitempty"`
-	OutputFormat        string   `json:"output_format,omitempty"`
-	HTMLOutputFile      string   `json:"html_output_file,omitempty"`
-	LogLevel            string   `json:"log_level,omitempty"`
-	InstallDir          string   `json:"install_dir,omitempty"`
+	CustomerID           string   `json:"customer_id,omitempty"`
+	APIEndpoint          string   `json:"api_endpoint,omitempty"`
+	APIKey               string   `json:"api_key,omitempty"`
+	ScanFrequencyHours   string   `json:"scan_frequency_hours,omitempty"`
+	SearchDirs           []string `json:"search_dirs,omitempty"`
+	EnableNPMScan        *bool    `json:"enable_npm_scan,omitempty"`
+	EnableBrewScan       *bool    `json:"enable_brew_scan,omitempty"`
+	EnablePythonScan     *bool    `json:"enable_python_scan,omitempty"`
+	IncludeTCCProtected  *bool    `json:"include_tcc_protected,omitempty"`
+	ColorMode            string   `json:"color_mode,omitempty"`
+	OutputFormat         string   `json:"output_format,omitempty"`
+	HTMLOutputFile       string   `json:"html_output_file,omitempty"`
+	LogLevel             string   `json:"log_level,omitempty"`
+	InstallDir           string   `json:"install_dir,omitempty"`
+	MaxExecutionDuration string   `json:"max_execution_duration,omitempty"`
 }
 
 // userConfigDir returns ~/.stepsecurity — the per-user config location.
@@ -172,6 +183,9 @@ func Load() {
 	if cfg.InstallDir != "" && InstallDir == "" {
 		InstallDir = cfg.InstallDir
 	}
+	if cfg.MaxExecutionDuration != "" && MaxExecutionDuration == "" {
+		MaxExecutionDuration = cfg.MaxExecutionDuration
+	}
 }
 
 // IsEnterpriseMode returns true if valid enterprise credentials are configured.
@@ -631,3 +645,24 @@ func RunConfigureNonInteractive(opts NonInteractiveOptions) error {
 	fmt.Printf("Configuration saved to %s\n", WriteConfigFilePath())
 	return nil
 }
+
+// PersistMaxExecutionDuration records the STEPSEC_MAX_EXECUTION_DURATION value
+// the loader exported into config.json at install time. Scheduler-fired runs
+// (launchd/systemd/schtasks) invoke the binary directly and never inherit the
+// loader's exported env var, so without this they fall back to the built-in 4h
+// default regardless of the loader's MAX_EXECUTION_DURATION_HOURS. Persisting
+// it lets telemetry.ExecutionDeadline pick it up on every scheduled run.
+// Read-modify-write so the loader-written customer_id/api_key/etc. survive.
+// No-op when value is empty (a direct binary install with no loader-configured
+// value keeps the built-in default).
+func PersistMaxExecutionDuration(value string) error {
+	if value == "" {
+		return nil
+	}
+	existing := loadExisting()
+	if existing.MaxExecutionDuration == value {
+		return nil
+	}
+	existing.MaxExecutionDuration = value
+	return save(existing)
+}

internal/config/max_execution_duration_test.go

@@ -0,0 +1,72 @@
+package config
+
+import "testing"
+
+// PersistMaxExecutionDuration is a read-modify-write: it records the loader's
+// max-execution value into config.json without disturbing the customer_id /
+// api_key / etc. the loader already wrote.
+func TestPersistMaxExecutionDuration_RoundTrip(t *testing.T) {
+	withHome(t)
+
+	// Seed config.json the way the loader's write_config would (no max-exec
+	// field), so we prove Persist preserves the existing fields.
+	seed := &ConfigFile{CustomerID: "acme", APIKey: "k", APIEndpoint: "https://api"}
+	if err := save(seed); err != nil {
+		t.Fatalf("seed save: %v", err)
+	}
+
+	if err := PersistMaxExecutionDuration("2h"); err != nil {
+		t.Fatalf("PersistMaxExecutionDuration: %v", err)
+	}
+
+	got := loadExisting()
+	if got.MaxExecutionDuration != "2h" {
+		t.Errorf("MaxExecutionDuration = %q, want %q", got.MaxExecutionDuration, "2h")
+	}
+	if got.CustomerID != "acme" || got.APIKey != "k" || got.APIEndpoint != "https://api" {
+		t.Errorf("read-modify-write clobbered existing fields: %+v", got)
+	}
+}
+
+// An empty value is a no-op (a direct binary install with no loader-exported
+// value must not write an empty field that would later parse to the default).
+func TestPersistMaxExecutionDuration_EmptyIsNoOp(t *testing.T) {
+	withHome(t)
+	if err := save(&ConfigFile{CustomerID: "acme"}); err != nil {
+		t.Fatalf("seed save: %v", err)
+	}
+
+	if err := PersistMaxExecutionDuration(""); err != nil {
+		t.Fatalf("empty should be a no-op, got: %v", err)
+	}
+
+	if got := loadExisting(); got.MaxExecutionDuration != "" {
+		t.Errorf("empty value should not be persisted, got %q", got.MaxExecutionDuration)
+	}
+}
+
+// Load() must surface a persisted max-execution value into the package var the
+// resolver reads on scheduler-fired runs.
+func TestLoad_PopulatesMaxExecutionDuration(t *testing.T) {
+	withHome(t)
+	seed := &ConfigFile{
+		CustomerID:           "acme",
+		APIKey:               "k",
+		APIEndpoint:          "https://api",
+		MaxExecutionDuration: "90m",
+	}
+	if err := save(seed); err != nil {
+		t.Fatalf("seed save: %v", err)
+	}
+
+	// Load only fills package vars still at their zero value; reset so this
+	// test is independent of execution order within the package.
+	MaxExecutionDuration = ""
+	t.Cleanup(func() { MaxExecutionDuration = "" })
+
+	Load()
+
+	if MaxExecutionDuration != "90m" {
+		t.Errorf("Load did not populate MaxExecutionDuration: got %q, want %q", MaxExecutionDuration, "90m")
+	}
+}

internal/telemetry/execution_deadline.go

@@ -16,26 +16,60 @@ import (
 // bounding pathological cases to a single daily launchd/schtasks tick.
 const defaultExecutionDeadline = 4 * time.Hour
 
-// ExecutionDeadlineFromEnv resolves STEPSEC_MAX_EXECUTION_DURATION using
-// the same contract as scanDeadlineFromEnv (scan_deadline.go):
-//   - unset / empty: returns defaultExecutionDeadline (4h)
-//   - "0" / "off": returns 0 (watchdog disabled; main.go skips arming)
-//   - any Go time.ParseDuration string ("2h", "30m", "45m30s"): that
-//     duration when positive
-//   - anything else: returns defaultExecutionDeadline (silent fallback —
-//     telemetry runs from unattended launchd/schtasks/systemd contexts
-//     where a typo in the env var should not be fatal to the scan)
+// EnvMaxExecutionDuration is an optional environment-variable override for the
+// execution watchdog, honored ahead of config.json for ad-hoc/manual runs
+// (e.g. `STEPSEC_MAX_EXECUTION_DURATION=3s ./binary send-telemetry`). The
+// loader no longer exports it: the configured value is delivered through
+// config.json (config.MaxExecutionDuration), which the binary reads on every
+// invocation — including scheduler-fired runs (launchd/systemd/schtasks) that
+// bypass the loader.
+const EnvMaxExecutionDuration = "STEPSEC_MAX_EXECUTION_DURATION"
+
+// ExecutionDeadlineFromEnv resolves the execution deadline from the environment
+// only. Equivalent to ExecutionDeadline(""); kept for callers (and tests) that
+// have no config fallback to supply.
 func ExecutionDeadlineFromEnv() time.Duration {
-	v := os.Getenv("STEPSEC_MAX_EXECUTION_DURATION")
+	return ExecutionDeadline("")
+}
+
+// ExecutionDeadline resolves the whole-process execution deadline with
+// env > config > default precedence. The env var (EnvMaxExecutionDuration) is
+// an optional ad-hoc override; configValue is the value the loader/installer
+// persists into config.json (config.MaxExecutionDuration), the primary channel
+// — it covers every invocation, including scheduler-fired runs
+// (launchd/systemd/schtasks) that invoke the binary directly. Each source uses
+// the same contract as scanDeadlineFromEnv (scan_deadline.go):
+//   - "0" / "off": 0 (watchdog disabled; main.go skips arming)
+//   - any positive Go time.ParseDuration string ("2h", "30m", "45m30s"): that
+//     duration
+//   - empty or unparseable: fall through to the next source, then to
+//     defaultExecutionDeadline (a typo in an unattended launchd/schtasks/systemd
+//     context must not be fatal to the scan)
+func ExecutionDeadline(configValue string) time.Duration {
+	if d, ok := parseExecutionDeadline(os.Getenv(EnvMaxExecutionDuration)); ok {
+		return d
+	}
+	if d, ok := parseExecutionDeadline(configValue); ok {
+		return d
+	}
+	return defaultExecutionDeadline
+}
+
+// parseExecutionDeadline applies the shared parse contract to a single raw
+// value. ok is false when the value is absent or unparseable — signalling the
+// caller to fall through to the next source; true (with a possibly-zero
+// duration) when the value explicitly resolved, including the "0"/"off" disable
+// case.
+func parseExecutionDeadline(v string) (time.Duration, bool) {
 	if v == "" {
-		return defaultExecutionDeadline
+		return 0, false
 	}
 	if v == "0" || v == "off" {
-		return 0
+		return 0, true
 	}
 	d, err := time.ParseDuration(v)
 	if err != nil || d <= 0 {
-		return defaultExecutionDeadline
+		return 0, false
 	}
-	return d
+	return d, true
 }

internal/telemetry/execution_deadline_test.go

@@ -38,3 +38,39 @@ func TestExecutionDeadlineFromEnv(t *testing.T) {
 		})
 	}
 }
+
+// ExecutionDeadline adds a config-file fallback for scheduler-fired runs that
+// never see the loader-exported env var: env > config > default.
+func TestExecutionDeadline_EnvThenConfigThenDefault(t *testing.T) {
+	cases := []struct {
+		name      string
+		env       string
+		setEnv    bool
+		configVal string
+		want      time.Duration
+	}{
+		// Env present and valid always wins over config.
+		{"env wins over config", "2h", true, "8h", 2 * time.Hour},
+		{"env off disables despite config", "off", true, "8h", 0},
+		// Env absent/unparseable falls through to the config value.
+		{"config used when env unset", "", false, "8h", 8 * time.Hour},
+		{"config used when env empty", "", true, "8h", 8 * time.Hour},
+		{"config off disables when env unset", "", false, "off", 0},
+		{"env junk falls through to config", "junk", true, "30m", 30 * time.Minute},
+		// Neither source usable → built-in default.
+		{"config junk falls back to default", "", false, "junk", 4 * time.Hour},
+		{"both empty falls back to default", "", false, "", 4 * time.Hour},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.setEnv {
+				t.Setenv("STEPSEC_MAX_EXECUTION_DURATION", tc.env)
+			}
+			got := ExecutionDeadline(tc.configVal)
+			if got != tc.want {
+				t.Errorf("ExecutionDeadline(%q) env=%q set=%v = %v, want %v",
+					tc.configVal, tc.env, tc.setEnv, got, tc.want)
+			}
+		})
+	}
+}

internal/telemetry/run_status.go

@@ -33,8 +33,11 @@ const (
 	// runStatusHeartbeatInterval is how often the telemetry run posts a
 	// status_info snapshot while a scan is in flight. Phase-boundary posts
 	// fire on top of this so a fast run still surfaces phase completions
-	// without waiting for the next tick.
-	runStatusHeartbeatInterval = 5 * time.Minute
+	// without waiting for the next tick. 2 minutes (matching the log-tail
+	// emitter's throttle, log_tail_emitter.go) gives tighter visibility into
+	// a stuck device — the last heartbeat is at most ~2 min stale — without
+	// meaningfully adding to backend write volume for healthy short scans.
+	runStatusHeartbeatInterval = 2 * time.Minute
 )
 
 // runStatusBody is the JSON shape posted to /telemetry/run-status. Fields