75627d4398
Applied on top ofaf13337so nothing already on wilm is rewritten. AUTHORIZATION. The six new policy GETs were @jwt_required(optional=True) with no permission at all, so an anonymous caller could list configuration and business policies - gated only by a feature flag that 404s while off. They now require computers.view. The six policy write routes stacked @jwt_required() above @require_permission, the same pattern removed from nine endpoints routes in this very push: the outer decorator answers an anonymous request 401 before require_permission can consult the guest role, so a grant to guests silently does nothing. Removed, and the now-unused import with them. tests/test_core/test_public_read_surface.py failed ataf13337with seven ungated GETs. It passes now. The seventh, endpoints.claim_next_command, is genuinely agent-facing - authenticated in the handler by the endpoints collector key, because a bay has no user session - so it joins PUBLIC_ENDPOINTS with its reason written down, exactly as report_command_result already does in test_authz.py. Note which half is public: claiming a queued command is the agent's business, while ENQUEUEING one is the real authority and stays gated on endpoints.command. INSTALLER. -BaseUrl and -CollectorKey are now mandatory with no defaults, and https is enforced unless -AllowInsecureHttp is passed for a local test box. The defaults were a real hostname (ADR-015) and a live collector key: a key in source is a key in git history, and that key is also the command channel's kill switch. Removing it here does not undo the disclosure - it must be rotated on the server, and purged fromaf13337- but it stops the next clone carrying it. IMPORT. A committed import wrote thousands of rows and left no audit trail; it now writes one AuditLog row inside the same transaction, so it cannot survive a rollback or go missing from a commit. The computer-type dropdown asked for per_page: 200, which the API ignores in favour of perpage and clamps to 100 anyway - it uses a new computersApi.types.listAll(), the pattern already applied to the other selectors. And the comment claiming the template example rows are "emitted as commented rows the engine skips" was the opposite of the truth: they import as live data, the emitted instructions say so, and a test depends on it. Not fixed here, deliberately: rotating the leaked key, purging it from history, and the endpoint agent's own hardening (per-host credentials, a protected process denylist so stop cannot kill security tooling, signing before the PowerShell runner is enabled, registry ACLs, and the 25-second long poll that will pin a worker thread per bay).
ShopDB Endpoint Agent
A Windows telemetry agent that reports endpoint state to a ShopDB server's
endpoints plugin. It runs as a Windows service in production and as a console
app for development and testing.
Projects
ShopDbEndpointAgent.Core- contracts, config, logging, collection, and the resilient collector HTTP client. No host concerns; unit-testable.ShopDbEndpointAgent- the service host (generic host + Windows service lifetime). Composes Core through DI. This is the telemetry runtime.ShopDbEndpointAgent.Tray- interactive user-session tray app: a system-tray icon with "Send Status now" (on-demand report) and the 5-click issue reporter (ServiceNow flow is still a scaffold). Separate process from the service, because a SYSTEM service cannot draw a tray icon in a user session.
Configuration
Runtime config is layered. Non-secret defaults live in appsettings.json
(shipped with the build). The collector key and base URL are provisioned out of
band in the registry and win over appsettings.json, so a distributed build
never carries the secret and the site can rotate the key without a rebuild.
Registry (production)
Create these values under HKLM\SOFTWARE\GE\ShopDB (64-bit view):
| Value | Type | Meaning |
|---|---|---|
BaseUrl |
String | https://shopdb.example.net (server root) |
CollectorKey |
String | The endpoint agent key from Settings -> Endpoints -> Key management |
Example (elevated PowerShell):
New-Item -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'BaseUrl' -Value 'https://shopdb.example.net'
Set-ItemProperty -Path 'HKLM:\SOFTWARE\GE\ShopDB' -Name 'CollectorKey' -Value '<paste the generated key>'
appsettings.json (all environments)
| Key | Default | Meaning |
|---|---|---|
baseurl |
"" | Dev fallback for the server root (registry wins). |
apikey |
placeholder | Dev fallback for the collector key (registry wins). |
cadenceseconds |
900 | Report interval (15 min). |
jitterseconds |
60 | Random +/- spread on the interval (anti-herd). |
adoptonfirstrun |
true | Send adopt=true on first contact only. |
utilitiespath |
"" | Directory of site PowerShell "agent utilities". |
logpath |
"" | Override the rolling log directory. |
For a dev box, set baseurl and apikey here and skip the registry.
Running
Console (dev), one report then exit:
dotnet run --project ShopDbEndpointAgent -- --once
Console (dev), continuous cadence loop:
dotnet run --project ShopDbEndpointAgent -- --console
Install as a Windows service
Publish self-contained, then register with sc.exe (elevated):
dotnet publish ShopDbEndpointAgent -c Release -r win-x64 --self-contained -o C:\ProgramData\ShopDB\EndpointAgent\bin
sc.exe create "ShopDBEndpointAgent" binPath= "C:\ProgramData\ShopDB\EndpointAgent\bin\shopdb-endpoint-agent.exe" start= auto DisplayName= "ShopDB Endpoint Agent"
sc.exe description "ShopDBEndpointAgent" "Reports endpoint telemetry to ShopDB."
sc.exe start "ShopDBEndpointAgent"
The service runs as LocalSystem by default, which it needs to read the Security event channel and system WMI.
Tray app (system-tray icon)
The tray is a per-user process, not a service, so it starts at sign-in rather
than under sc.exe. install-shopdbagent.ps1 handles it: it copies
shopdb-endpoint-tray.exe next to the agent, registers an HKCU logon autostart
(Software\Microsoft\Windows\CurrentVersion\Run\ShopDbEndpointTray), and
launches it for the current user. Run the installer from the operator's own
session so the autostart lands in the right user hive. Pass -NoTray for a
headless, service-only install.
Right-click the tray icon for:
Send Status now- reports this PC to ShopDB immediately so the monitor page refreshes without waiting for the next cadence tick. It shells out toshopdbagent.exe --once, reusing the exact production collection path; the tray holds no collector key. A balloon tip reflects success or failure (on failure, see the rolling agent log).Report an issue...- the ServiceNow ticket flow (scaffold; submission path is an open decision).
A desktop shortcut to shopdb-endpoint-tray.exe can be added later for an
explicitly launchable ServiceNow surface.
WebUI command execution model (security context)
The WebUI can send an endpoint an allowlisted command (server source of truth:
plugins/endpoints/commands.py; agent handler: CommandExecutor). The agent
service runs as LocalSystem, but not every command runs in that context. The
launch context is chosen per action so processes surface to the operator while
privileged operations keep the token they need:
- Generic
process_start(for example DncMain, UDC) launches into the ACTIVE CONSOLE USER's session at medium integrity, so the app is visible on the operator's desktop. CyberArk/EPM brokers any elevation afterward. - Generic
process_stop/process_statusrun as SYSTEM (kill and probe). service_start/service_stop/service_statusrun as SYSTEM, because service control requires the admin/SYSTEM token.mtconnect_start/mtconnect_stop/mtconnect_statusall run as SYSTEM, because MTConnect is the "UDC MTConnect Agent" Windows service and service control requires the admin/SYSTEM token.mtconnect_startrunsinstall.bat(Agent.exe install) to install or repair the service, then ensures it is running;mtconnect_stopstops the service;mtconnect_statusqueries it.run.bat(agent.exe run agent.cfg) is a foreground TESTING launcher and is deliberately NOT used by the agent.system_restartruns as SYSTEM and reboots the machine immediately viashutdown.exe /r /t 0(no grace timer). It is a fixed action with no target, gated server-side by the dedicatedendpoints.restartpermission on top ofendpoints.command, and fronted by a WebUI confirmation gate.
Do not route MTConnect through the generic process_start user-session path or
service control breaks. MTConnect is intentionally absent from the
process_start launch map for the same reason; the fixed mtconnect_* handler
owns it.
Behavior note for redeploys: the MTConnect service-control model is a runtime change, so the agent must be rebuilt and redeployed for it to take effect. Server-side command/allowlist/RBAC changes are picked up by the container rebuild; rebuild and redeploy the agent whenever the runtime launch/control logic itself changes.
Diagnostics
- Rolling file log:
%ProgramData%\ShopDB\EndpointAgent\logs\agent-YYYYMMDD.log(14-day retention). - Windows Event Log: agent runtime failures and unhandled exceptions are written
to the
Applicationlog under sourceShopDB Endpoint Agent. The source is created on first elevated run (or by the installer). Filter Event Viewer by that source to see agent/system interop failures.
Agent utilities (PowerShell seam)
If utilitiespath points at a directory, the runtime runs each *.ps1 there
per report, parses its JSON stdout, and merges the result into the report. This
is the seam the future server-side "Agent configuration" settings page uses to
push site-authored collectors down. Scripts must be code-signed and
allow-listed before this is enabled in the field (rollout concern).
Logging extensibility
All runtime code logs through Microsoft.Extensions.Logging (ILogger). Adding
a sink later (a ShopDB HTTP sink, Seq, syslog) is a host-builder change in
Program.cs::ConfigureLogging with no changes to the worker, collector, or
client.