Redflag/docs/D1_MachineID_Audit.md

D-1 Machine ID Duplication Audit

Date: 2026-03-29 Branch: culurien Scope: Machine ID implementation consistency across agent codebase

---

1. ALL MACHINE ID IMPLEMENTATIONS

1a. Canonical: system/machine_id.go

GetMachineID() (line 15):

1. machineid.ID() — cross-platform library (Windows: Registry MachineGuid, Linux: /etc/machine-id)
2. If success: hashMachineID(id) → SHA256 → 64 hex chars
3. If fail: OS-specific fallback

Linux fallback chain (line 43):

1. /etc/machine-id → hash
2. /var/lib/dbus/machine-id → hash
3. /sys/class/dmi/id/product_uuid → hash
4. /etc/hostname + "-linux-fallback" → hash

Windows fallback (line 80):

1. machineid.ID() again (same as primary — redundant)
2. generateGenericMachineID() → hostname-os-arch → hash

Generic fallback (line 102): hostname-goos-goarch → hashMachineID() → 64 hex chars

Output format: ALWAYS 64 hex characters (SHA256). Every path goes through hashMachineID().

1b. Client: client/client.go

Line 36: machineID, err := system.GetMachineID() — calls canonical function. Cached in Client.machineID string field. Sent as X-Machine-ID header on every authenticated request (line 108).

If GetMachineID() fails: machineID = "" (empty string). Server will reject with 403 "missing machine ID header".

Consistent with canonical: YES.

1c. Registration: cmd/agent/main.go

Line 425: machineID, err := system.GetMachineID() — calls canonical function. Line 428: ERROR FALLBACK: machineID = "unknown-" + sysInfo.Hostname

This fallback is NOT HASHED and NOT 64 HEX CHARS. It produces a string like "unknown-my-server" (14-30 chars, alphanumeric with dashes).

Line 443: MachineID: machineID — sent in RegisterRequest.MachineID and stored in agents.machine_id column.

1d. Example: logging/example_integration.go

Line 71: machineid.ID() — calls library DIRECTLY, bypasses GetMachineID() and hashMachineID(). Returns raw, unhashed machine ID.

Not imported anywhere. File is package logging but none of its functions are called from production code. It's dead example code.

---

2. ALL CALL SITES

Location	Method	Hashed?	Consistent?
system/machine_id.go:17	machineid.ID() → hashMachineID()	YES	Canonical
system/machine_id.go:82	machineid.ID() → hashMachineID()	YES	Canonical
system/machine_id.go:93	machineid.ID() → hashMachineID()	YES	Canonical
system/machine_id.go:102	hostname+os+arch → hashMachineID()	YES	Canonical
client/client.go:36	system.GetMachineID()	YES	Consistent
cmd/agent/main.go:425	system.GetMachineID()	YES	Consistent
cmd/agent/main.go:428	"unknown-" + hostname	NO	DIVERGENT
logging/example_integration.go:71	machineid.ID() direct	NO	DEAD CODE

---

3. DIVERGENCE ANALYSIS

3a. Can the three production call sites return different values?

Normal case (GetMachineID succeeds): YES, all three return the same SHA256-hashed value. client.go and main.go both call system.GetMachineID().

Failure case (main.go line 428):

• Registration (main.go): "unknown-my-server" — 14-30 chars, alphanumeric, NOT hashed
• Runtime (client.go): If GetMachineID() fails at client construction, machineID = "" — empty string → server rejects with 403

F-D1-1 HIGH: Registration and runtime machine IDs can diverge. If GetMachineID() fails during registration, the agent registers with "unknown-hostname" (unhashed). On subsequent restarts, if GetMachineID() succeeds, the client sends a SHA256 hash. The server compares: "unknown-hostname" != "a7f3...64hexchars..." → 403 FORBIDDEN. The agent is permanently locked out until re-registered.

3b. Server-Side Validation

machine_binding.go:149: *agent.MachineID != reportedMachineID — simple string equality comparison. No format validation. Would accept BOTH "unknown-hostname" (if that's what was registered) AND "a7f3...64hex...". But they must match exactly.

3c. Registration vs Runtime Mismatch

If the agent registered with "unknown-hostname" (fallback) but restarts and GetMachineID() now succeeds (transient error resolved), the client sends a SHA256 hash that doesn't match the stored "unknown-hostname" → permanent lockout.

F-D1-2 MEDIUM: No recovery path from machine ID mismatch. The only fix is manual: delete the agent from the DB and re-register. There's no "update machine ID" API.

---

4. EXAMPLE_INTEGRATION.GO

• Imported: NO (zero results from grep)
• Package: logging — it IS part of the package and its functions are exported
• Called: NO — none of its functions are called anywhere
• Risk: ExampleMachineIDMonitoring() calls machineid.ID() directly (unhashed)
• Candidate for deletion: YES — dead example code that bypasses the canonical path

F-D1-3 LOW: example_integration.go is dead code. Its ExampleMachineIDMonitoring() function calls machineid.ID() directly, bypassing the canonical GetMachineID(). If anyone copies this example, they'll get unhashed machine IDs.

---

5. WINDOWS-SPECIFIC PATH

5a. Fallback Chains

Linux: machineid.ID() → /etc/machine-id → /var/lib/dbus/machine-id → /sys/class/dmi/id/product_uuid → hostname-linux-fallback → hostname-os-arch

Windows: machineid.ID() → machineid.ID() (redundant retry) → hostname-os-arch

F-D1-4 LOW: Windows getWindowsMachineID() calls machineid.ID() again after the primary already tried it and failed. This is a no-op retry — the same function will fail again.

5b. Dual-Boot Collision

Windows MachineGuid (registry) and Linux /etc/machine-id are independent. A dual-boot system produces different machine IDs for each OS. No collision risk.

5c. Windows Reinstall

Windows MachineGuid changes on reinstall. This is NOT documented in the codebase. After reinstalling Windows, the agent will produce a different machine ID → 403 from MachineBindingMiddleware → must re-register.

---

6. REGISTRATION vs RUNTIME CONSISTENCY

6a. Registration Path (main.go:425-443)

system.GetMachineID() → if error: "unknown-" + hostname (UNHASHED) → stored in DB

6b. Runtime Path (client/client.go:36-41)

system.GetMachineID() → if error: "" (empty) → sent as X-Machine-ID header → server rejects with 403

6c. Are They Guaranteed Identical?

NO. Three scenarios cause divergence:

1. Registration succeeds, runtime fails: Registration stores SHA256 hash. Runtime sends empty string → 403.
2. Registration fails, runtime succeeds: Registration stores "unknown-hostname". Runtime sends SHA256 hash → 403.
3. Both fail but produce different fallbacks: Registration uses "unknown-hostname" (unhashed, from main.go:428). Runtime uses empty string (from client.go:40). These don't match → 403.

F-D1-1 is the root cause. The main.go fallback at line 428 produces a fundamentally different format than the canonical function.

---

7. ETHOS CROSS-CHECK

Principle	Status	Finding
ETHOS #1	PARTIAL	GetMachineID failure logged in main.go (line 427) and client.go (line 39). But client.go uses fmt.Printf instead of log.Printf.
ETHOS #4	VIOLATION	Machine ID is NOT idempotent when the error fallback activates. Registration path and runtime path produce different values for the same failure condition.

---

FINDINGS SUMMARY

ID	Severity	Finding	Location
F-D1-1	HIGH	Registration fallback "unknown-"+hostname is unhashed and mismatches runtime path, causing permanent agent lockout on recovery	cmd/agent/main.go:428
F-D1-2	MEDIUM	No recovery path from machine ID mismatch — must delete and re-register agent	machine_binding.go:149
F-D1-3	LOW	example_integration.go is dead code that calls machineid.ID() directly (unhashed), bypassing canonical path	logging/example_integration.go:71
F-D1-4	LOW	Windows getWindowsMachineID() redundantly retries machineid.ID() after primary already failed	system/machine_id.go:82
F-D1-5	LOW	client.go:39 uses fmt.Printf instead of log.Printf for machine ID error (ETHOS #1)	client/client.go:39
F-D1-6	INFO	Windows reinstall changes MachineGuid, causing agent lockout — not documented	system/machine_id.go