ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add agentless adoption tool for endpoints

Browse Source 
Standalone one-shot enrollment tool that creates a ShopDB PC + Endpoint entry using only the endpoints collector key, reusing the existing collector adopt path. Collects identity, WMI hardware, and installed-software SBOM; requires admin. Server-side packaging route attaches to the existing endpoints blueprint; no core contract change.
This commit is contained in:
benjamin.baker
2026-08-30 08:31:31 -04:00
committed by cproudlock
parent cfb0b9ca4e
commit 7040832565
8 changed files with 685 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
plugins/endpoints/ADOPTION-TOOL-SPIKE.md Normal file
View File

@@ -0,0 +1,77 @@
# Adoption tool spike
Status: spike. Built on the `origin/main` baseline so it can be cherry-picked as
a single unit once endpoint agent development is complete.
## What it is
A one-shot, agentless enrollment tool. An admin generates a small download from
the Endpoints key settings page; running the tool once on a PC creates a ShopDB
PC (Computer) and Endpoint entry using only the endpoints collector key. It is
NOT the endpoint agent: it installs nothing, runs no service, and sends no
ongoing telemetry. It targets sites that want an inventory entry without running
the full agent.
## How it works
1. Admin generates or reuses an endpoint agent key (existing `/agentkey` flow).
2. Admin opens the "Adoption tool" section, confirms the base URL (prefilled
from the browser origin) and pastes the collector key (prefilled when a key
was just generated, since the secret is only shown once).
3. `POST /api/endpoints/adoptiontool/package` (admin-gated) returns a ZIP with
`adopt.config.json`, `README.txt`, and `shopdb-adopt.exe` when a prebuilt
binary is staged on the server.
4. On the target PC, `shopdb-adopt.exe` reads the config beside it (or CLI args),
then POSTs to `/api/collector/endpoints` with `X-API-Key` and `adopt=true`.
The existing `_adopt_computer` path creates the Computer + EndpointState.
## Collection
The tool gathers the same identity, hardware, and SBOM subset the endpoint
agent collects, using identical WMI queries and wire keys so the server stores
it without translation:
- Identity: `hostname`, `loggedinuser`, `ipaddress`.
- Hardware: `serialnumber` (Win32_BIOS), `vendorname` / `pctype` / `modelnumber`
(Win32_ComputerSystem), `osname` and `lastboottime` (Win32_OperatingSystem).
- SBOM: `applications` = both Uninstall registry hives (64-bit + WOW6432Node),
de-duped `{displayname, displayversion, publisher}`. The server logs this as
an unpersisted key today (same as the agent) until the SBOM store lands.
The tool requires administrator rights (enforced by its app manifest
`requireAdministrator`, with a runtime elevation guard) because the machine
Uninstall hives and full WMI need elevation, or collection would be silently
partial.
## Cherry-pick boundary
The spike is deliberately isolated. Cherry-pick exactly:
- `agent/ShopDbAdoptionTool/` (new standalone tool project, incl. `app.manifest`)
- `agent/ShopDbEndpointAgent.slnx` (one line adding the project)
- `plugins/endpoints/api/adoption.py` (new module; attaches to `endpoints_bp`)
- `plugins/endpoints/api/__init__.py` (one-line import to register the route)
- `plugins/endpoints/frontend/views/AgentKeySettings.vue` (new UI section only)
- `plugins/endpoints/ADOPTION-TOOL-SPIKE.md` (this file)
`plugins/endpoints/api/routes.py` is intentionally untouched so the delivery
spike changes there do not tangle with this feature.
## Prebuilt exe distribution
The api container has no .NET SDK, so the package embeds the exe only when a
prebuilt copy is staged at `instance/adoptiontool/shopdb-adopt.exe`. Otherwise
the ZIP ships the config plus README (build the exe out of band, same model as
the endpoint agent installer bundle). Follow-up: a CI job that publishes
`shopdb-adopt.exe` and stages it into the image or instance path.
## Known follow-ups
- Agentless health signal: an adopted PC never reports again, so
`EndpointState.lastreportedat` reflects only the adoption moment. The fleet
health/dashboard logic should distinguish "agentless, adopted" from
"agent expected but silent" so these PCs do not read as permanently failed.
Left out of this spike to keep the server create-path unchanged for a clean
cherry-pick; the tool does not send an `agentless` marker yet because the
server does not persist one (`KNOWN_PAYLOAD_KEYS`).
- CI packaging of the prebuilt exe (see above).