guru-connect/docs/specs/SPEC-007-managed-agent-installer-builder.md

SPEC-007: Managed-Agent Installer Builder ("Build Installer")

Status: Proposed Priority: P2 Requested By: Mike (2026-05-30) Estimated Effort: Medium

Overview

Add a dashboard "Build Installer" wizard that produces a pre-labeled managed/persistent (unattended) agent installer — the ScreenConnect "Build Installer" flow. The operator picks a naming strategy and fills Company, Site, Department, Device Type, and Tag, chooses the platform/type, and gets the installer via Download, Copy URL, or Send Link. Once installed, the agent enrolls and appears in the machines list already carrying those labels (so SPEC-003 inventory / SPEC-005 rows / SPEC-006 search are populated at install time, not only agent-detected). Success = a tech can build and hand off a labeled permanent-agent installer entirely from the console, no CLI or manual query-string crafting.

Reference (screenshot 2026-05-30): modal "Build Installer" with fields Name (Use Machine Name / custom), Company, Site, Department, Device Type, Tag, Type (Windows .exe), and share actions Send Link · Copy URL · Download.

What already exists (and what's missing)

The embed-config build path is already implemented: server/src/api/downloads.rs appends an EmbeddedConfig (magic marker GURUCONFIG + length + JSON) to the base static/downloads/guruconnect.exe; AgentDownloadParams already accepts company, site, tags, api_key; the agent reads it back at agent/src/config.rs:223 (read_embedded_config). The downloads routes are public links (main.rs:425).

Missing for the ScreenConnect-parity builder:

• No dashboard UI to drive it (endpoints exist, no wizard).
• Department + Device Type are not in EmbeddedConfig (downloads.rs:21 / config.rs:20), not in AgentStatus, not persisted on connect_machines.
• Name strategy ("Use Machine Name" vs. custom) isn't modeled.
• Share actions beyond Download: Copy URL and Send Link don't exist.
• Key selection — which agent key the installer embeds (shared AGENT_API_KEY vs. a per-machine/site key) isn't surfaced.

Scope

Included in v1

• Dashboard "Build Installer" modal (triggered from the Machines page, e.g. a Build + action): fields Name (Use Machine Name | custom), Company, Site, Department, Device Type, Tag(s), Type (platform); validates and calls the build endpoint.
• Extend EmbeddedConfig (downloads.rs + agent/src/config.rs) and AgentDownloadParams with department and device_type; agent maps them through to AgentStatus (proto) so they persist on connect_machines (SPEC-003 columns) the same way organization/site/tags do today.
• Name strategy: Use Machine Name (agent uses live hostname — current default) or a custom override embedded in the config (hostname_override already exists, config.rs:63).
• Share actions: Download (exists), Copy URL (returns the parameterized public download URL for clipboard), Send Link (email the download URL — see deps).
• Type/platform selector: Windows (.exe) in v1, with the dropdown structured to add macOS/Linux later (those agents are roadmap P3 — show only available types).
• Key selection: embed the correct agent key for enrollment — default the shared/site key; ready to use a per-machine key when that lands (SPEC-004/roadmap).

Explicitly out of scope

• Attended support-code session creation — that's a different flow (support codes already exist); this builder is for managed/persistent agents only.
• macOS/Linux installer artifacts — UI is forward-compatible but only Windows .exe ships.
• MSI/MSP packaging, GPO/Intune deployment bundles — .exe only in v1.
• Code-signing changes — the base binary signing is SPEC-001/ADR-002; the builder just appends config to the already-signed base (note: appending after signing invalidates the Authenticode signature — see Open Questions).

Architecture

• Dashboard (dashboard/src/features/machines/): new BuildInstallerModal.tsx + dashboard/src/api/installer.ts; opens from the Machines page. Builds the request, shows Download/Copy URL/Send Link. Admin-only.
• Relay-server (server/src/api/downloads.rs): extend EmbeddedConfig + AgentDownloadParams with department, device_type, and a name/hostname_override field; the existing append-config build path is reused. Add a small endpoint to return the built URL (for Copy URL) and a Send Link action (POST that emails the URL).
• Agent (agent/src/config.rs): add department, device_type to EmbeddedConfig and Config; thread into send_status (agent/src/session/mod.rs:236) on AgentStatus.
• Protobuf (proto/guruconnect.proto): add department and device_type to AgentStatus (or to SPEC-003's DeviceInventory) so the relay can persist them. Pick one home and keep it consistent with SPEC-003.
• DB: connect_machines.department / device_type columns come from SPEC-003; no new migration here if SPEC-003 lands first (else add them).

Implementation details

• Files to touch: server/src/api/downloads.rs:21,40 (EmbeddedConfig + AgentDownloadParams: department, device_type, name/override); server/src/main.rs (Copy-URL / Send-Link routes if added; existing download routes reused); agent/src/config.rs:20,59 (Config + EmbeddedConfig fields); agent/src/session/mod.rs:236 (AgentStatus population); proto/guruconnect.proto (AgentStatus/DeviceInventory fields); dashboard/src/features/machines/BuildInstallerModal.tsx (new), dashboard/src/api/installer.ts (new).
• The build URL is the existing public download endpoint with query params (company, site, tags, department, device_type, name, key) — Copy URL just returns that string; Download streams the appended binary; Send Link emails it.

Security considerations

• Embedded key exposure. The installer embeds an agent enrollment key in a public, user-shareable artifact/URL. Prefer a per-machine or per-site key over the shared AGENT_API_KEY so a leaked installer can be revoked without re-keying the fleet; at minimum make the embedded key revocable. This is the strongest reason to pair with per-machine agent keys (SPEC-004 Security / roadmap).
• Build endpoint auth. Building/Copy-URL/Send-Link must be admin-authenticated (AuthenticatedUser) even though the resulting download link is public; do not let an unauthenticated caller mint installers with arbitrary embedded keys.
• Input validation. Company/Site/Department/Device Type/Tag/Name are embedded as JSON and later shown in the console and reported on AgentStatus — length-cap and sanitize (no injection into the embedded JSON, no oversized config blob; the agent already length-checks the embedded blob, config.rs:230).
• Send Link. Validate the recipient; rate-limit; the email contains a key-bearing URL, so treat it as a credential delivery (audit who built/sent what).
• Signature note. Appending config after Authenticode signing breaks the signature (Open Questions) — a security/UX consideration for SmartScreen, not just cosmetic.

Testing strategy

• Unit: EmbeddedConfig round-trips department/device_type (write → append → read_embedded_config → equal); URL builder encodes all fields + key correctly.
• Integration: build an installer with all fields set → download → embedded config parses → (simulated) agent registers and connect_machines shows the embedded company/ site/department/device_type/tags. Copy URL returns a URL that downloads the same. Build endpoints reject unauthenticated callers.
• Manual: from the console, build a labeled installer, install on a test box, confirm it appears in Access pre-labeled; verify Copy URL and (if shipped) Send Link.

Effort estimate & dependencies

• Size: Medium. The build/append path exists; bulk of the work is the dashboard wizard, the department/device_type plumbing (agent + proto + config), and Send-Link email.
• Depends on: SPEC-003 for the department/device_type persistence columns (and it feeds SPEC-003/005/006 by populating those fields at install time). Pairs with per-machine agent keys (SPEC-004/roadmap) for a revocable embedded key. Send Link needs an outbound email/SMTP capability the server may not have yet — gate that sub-feature on it (Copy URL + Download have no such dep).
• Unblocks: self-service managed-agent onboarding from the console; pre-labeled fleet data feeding inventory, list view, and search.

Open questions

1. Authenticode signature vs. appended config. Appending the config blob after the base .exe is signed invalidates the signature (SmartScreen warnings). Options: sign after config injection per-build (needs signing in the build path — heavier, ties to ADR-002/SPEC-001), embed config in a signature-preserving way (e.g. a signed wrapper / resource section), or accept unsigned per-build installers. Decide in planning — this is the biggest design question.
2. Embedded key model — shared AGENT_API_KEY, per-site key, or per-machine key minted at build time? Strongly prefer revocable per-site/per-machine.
3. Send Link transport — does the server have/want SMTP? If not, ship Download + Copy URL in v1 and defer Send Link (or use a mailto: prefilled link as a stopgap).
4. Name strategy storage — custom name via existing hostname_override (config.rs:63) vs. a separate display-name field that doesn't change the reported hostname. Which does the console treat as authoritative?
5. Platform dropdown — hide unavailable platforms, or show disabled "coming soon" entries for macOS/Linux?