6e36df841e
Ports 37 of Benjamin Baker's commits from the wilm branch, mirrored from the
corporate GitHub at 7905917c. wilm rides the publication lineage and shares no
ancestor with wj, so this is a filtered tree patch rather than a merge:
94 files, and every path the publication export strips (docs/, tools/, mcp/,
CLAUDE.md, start-*.sh, .gitea/, the three excluded tests) is held back, because
a raw diff would delete each of them from this tree.
What comes across:
* Endpoint telemetry, phase 2. Physical disk health from two sources, NIC link
state, boot type, Defender health, processor/memory/chassis inventory, the
listening TCP set, mapped network drives and Windows Update history. Five
additive migrations, 0012 through 0016, off the 0011 head.
* Mapped drives are collected by a probe running in the interactive user's
session, because they do not exist in the agent's session 0. Two Windows
sources can disagree about one drive and the worse status wins, so a
half-broken share is never rendered as healthy.
* Windows events are reported once each, keyed on the channel's own record id,
instead of being re-sent whenever a report overlapped the last one.
* PC Detail rework: Details cards flow, the hand-written Network card gives way
to a full address history, Storage and disk health merge into one card with
two sections, Operator Reports and Corporate Tools get their own tabs.
* An opt-in restic backup overlay with a third container, restore gated on the
dump's own data revision rather than the code head, and backup/restore history.
* The agent's version is read from the binary's PE version rather than trusted
from the csproj, and the Fleet view gains an Agent Version column.
* The enqueue route now asks caller_holds instead of the owner's permissions,
which closes the scoped-token elevation on run_script, update_app and
system_restart.
Held back deliberately:
* agent/installer/install-shopdbagent.ps1 stays deleted, as upstream deleted it.
The installer that reaches a bay is generated by _install_script() in
plugins/endpoints/api/siteagent.py; the standalone script had stopped being
shipped and was collecting fixes no endpoint ever ran.
* The .gitignore hunk adding docs/*.md. Correct on the publication lineage,
where docs/ becomes the wiki and its absence is how the gates detect a
published checkout. Here it would silently ignore every new doc.
* Their deletions of docs/DEV-BUILD-TEST.md and docs/PLUGIN-HOOKS.md. Upstream
those were stubs; here PLUGIN-HOOKS.md is the 31KB document CLAUDE.md points
readers at.
* Five zero-byte files committed by an accidental `git add -A`, a run log from
the author's own machine, and docs/notes/, which is working scratch that says
so in its own header and belongs in devnotes/ on this side.
Carried with the import so it lands green: the 17 new routes are described in
docs/api-inventory.json with the spec and project map regenerated, and two new
frontend specs read fixtures through fileURLToPath(URL) which node rejects under
jsdom's own URL global.
Suite 2591 passed / 9 skipped; frontend 391 passed; naming, style and doc gates
clean.
Scope: product
178 lines
8.6 KiB
Markdown
178 lines
8.6 KiB
Markdown
# 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`. The generated `install.ps1` handles it: it copies
|
|
`shopdb-endpoint-tray.exe` next to the agent and registers a machine-wide logon
|
|
autostart (`HKLM\Software\Microsoft\Windows\CurrentVersion\Run\ShopDbEndpointTray`,
|
|
64-bit view). The installer deliberately does NOT start the tray itself: it runs
|
|
elevated, so any process it starts inherits an admin token, and mapped drives are
|
|
per logon token - an elevated tray probes the wrong drive table. The Run key only
|
|
fires at logon, which would leave the tray dead until sign-out on a machine
|
|
someone is already using, so the installer also registers a transient
|
|
`ShopDB tray first launch` scheduled task under `S-1-5-32-545` at `RunLevel
|
|
Limited`, runs it once, and unregisters it. That task is the only mechanism that
|
|
can reach into an existing interactive session without carrying the installer's
|
|
token. Pass `-NoTray` for a headless, service-only install.
|
|
|
|
User-context collection does not depend on the tray. The installer registers a
|
|
`ShopDB user-context probe` scheduled task against the Users group at
|
|
`RunLevel Limited`, which runs `shopdbagent.exe --collect-usercontext` in the
|
|
operator's own session at logon and every 30 minutes.
|
|
|
|
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 to
|
|
`shopdbagent.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_status` run as SYSTEM (kill and probe).
|
|
- `service_start` / `service_stop` / `service_status` run as SYSTEM, because
|
|
service control requires the admin/SYSTEM token.
|
|
- `mtconnect_start` / `mtconnect_stop` / `mtconnect_status` all run as SYSTEM,
|
|
because MTConnect is the "UDC MTConnect Agent" Windows service and service
|
|
control requires the admin/SYSTEM token. `mtconnect_start` runs `install.bat`
|
|
(`Agent.exe install`) to install or repair the service, then ensures it is
|
|
running; `mtconnect_stop` stops the service; `mtconnect_status` queries it.
|
|
`run.bat` (`agent.exe run agent.cfg`) is a foreground TESTING launcher and is
|
|
deliberately NOT used by the agent.
|
|
- `system_restart` runs as SYSTEM and reboots the machine immediately via
|
|
`shutdown.exe /r /t 0` (no grace timer). It is a fixed action with no target,
|
|
gated server-side by the dedicated `endpoints.restart` permission on top of
|
|
`endpoints.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\YYYYMMDD-agent.log`
|
|
(14-day retention).
|
|
- Windows Event Log: agent runtime failures and unhandled exceptions are written
|
|
to the `Application` log under source `ShopDB 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.
|