f9d6b57f0f
The docs lived on one lineage and the fleet code on another. That is why six pages described a shared fleet key as how an agent authenticates, why COLLECTOR-AUTH had to warn that the per-PC credential code was not in the repository it sat in, and why ADR-019 recorded a decision whose implementation was somewhere else. Documentation that cannot see the code it documents goes stale by construction, and no amount of editing fixes that. So the corpus moves here: 84 files, 56 pages, 20 ADRs, the proposals, INDEX.md, llms.txt and both gates. Filenames are unchanged, because a wiki page name is derived from the filename and a rename breaks every link anybody saved. THE POINT OF THE MOVE IS THE CORRECTION IT ENABLES. Every caveat that said "not in this tree" was false the moment the files landed beside the code, so each was rewritten from what is actually here: - COLLECTOR-AUTH gained the real enroll request body, the two bounds on the unauthenticated route (per-IP rate limit, pending cap with stale rows dropped before a real PC is refused), and the rejected pending reason that binds to the endpoint identity rather than the nonce. - ADR-019 now describes an implementation that is present, including its tests, and says plainly that what remains is the FLEET migration, not the code. - proposals/device-identity claimed phase 1 was unbuilt. plugins/computers declares deviceid on the collector schema and prefers it over the older fallbacks. Corrected in the page, its summary and the index. WINDOWS/IIS IS NOW DOCUMENTED AS THE LEGACY PATH, per the product decision, and carefully: it is what production runs today. Every Windows page opens by saying it is supported, not for a new site, and where a new site should go instead. No procedure was cut - an operator on an IIS box at 2am needs these pages to work exactly as well tomorrow. MIGRATE-TOPOLOGY stops being a footnote and becomes the off-ramp, which is why it nearly doubled: what was there did not match how the Docker stack really works here. The Docker material that already lived on this line was kept and given ownership rather than buried under the ported Windows-centric prose: DEPLOY now describes the four services, the migrate service that runs the upgrade chain before api starts, TLS terminated by nginx, and the plugin count corrected from thirteen to seventeen - a number both lineages had wrong. ROADMAP is rewritten from evidence rather than memory: what has shipped, read out of the changelog, the ADRs and the manifests, and ahead of it exactly two items - finalize a distributed release and polish the setup wizard. PROJECT-MAP is generated and was stale; the GENERATOR was what was wrong. --check passes now. API-REFERENCE is retired to a pointer. /api/docs serves 573 operations with derived auth, query parameters and harvested examples, and a hand-written page competing with that is a liability. The file stays so its wiki page and its inbound links survive. AND THE MOVE TURNED ON A SCRUB THAT HAD NEVER RUN HERE. test_docs_publishable keys on docs/*.md, which this line did not have, so it skipped - its own comment predicted what would surface. Porting the corpus activated it and it found 48 lines that must not reach a published wiki: branch names abbreviating the site, assistant-tooling paths, the site name in two deployment pages, and an employee ID in a Windows path that the scrub does not even look for.
205 lines
9.0 KiB
Markdown
205 lines
9.0 KiB
Markdown
<!-- docmeta
|
|
purpose: explanation
|
|
audience: developer
|
|
status: historical
|
|
summary: The 2026-08 plan for ShopDB-resolved credential targeting. Never built; superseded by ADR-019.
|
|
loadwith: none
|
|
-->
|
|
|
|
# ADR-016: Credential delivery to the fleet
|
|
|
|
- Status: SUPERSEDED by [ADR-019](ADR-019-per-pc-endpoint-credentials.md)
|
|
- Date: 2026-08-11
|
|
- Deciders: ShopDB maintainers
|
|
- Relates to: ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership), ADR-015 (site-specific configuration)
|
|
|
|
> **Do not build against this. Nothing in it was built.** The model below has a
|
|
> PC ask ShopDB for credentials chosen by server-side targeting rules. The
|
|
> `GET /api/collector/credentials` endpoint, the `credentials.fetch` and
|
|
> `credentials.manage` permissions and the rule store do not exist in the code,
|
|
> and a reader searching for them will not find them.
|
|
>
|
|
> What shipped instead is the opposite shape: the endpoint holds ONE secret of
|
|
> its own, obtained by enrolling, and there are no targeting rules to resolve.
|
|
> [ADR-019](ADR-019-per-pc-endpoint-credentials.md) records that decision.
|
|
>
|
|
> The PROBLEM stated below is still the real problem, and ADR-019 cites it.
|
|
> Kept as the record of a design that was decided and then not taken.
|
|
|
|
## Context
|
|
|
|
Shopfloor bays need credentials they cannot prompt for. A collections bay loses
|
|
the Windows Credential Manager entry for its controller subnet periodically -
|
|
suspected Defender or Intune scrub - and without it, controller-side
|
|
connections need an interactive prompt, so an unattended bay simply stops
|
|
working. A machine whose NTLARS config points at a program share needs a
|
|
credential to reach that share for the same reason.
|
|
|
|
Today this is solved by `Set-ControllerCredential.ps1` on the SFLD share:
|
|
|
|
```powershell
|
|
$Target = '192.168.1.1'
|
|
$Username = 'CHANGEME'
|
|
$Password = 'CHANGEME'
|
|
```
|
|
|
|
A person edits the values into the file, GE-Enforce runs it every cycle, and
|
|
`cmdkey /add` re-applies it. It works, and it has three problems.
|
|
|
|
The password is **cleartext in a file on a share**, readable by anything that
|
|
can read the share - a wider exposure than the machine-local secret it becomes.
|
|
Rotating it means editing that file and hoping: there is no way to ask which
|
|
bays have picked up the new value. And it is **one value for everything**,
|
|
while the requirement is per-bay variation: sites will have machines needing
|
|
different credentials from their neighbours.
|
|
|
|
Per-bay variation is what rules out the obvious alternative. GE-Enforce scopes
|
|
are per PC TYPE, so expressing per-machine credentials as manifest scopes means
|
|
a scope per bay, which is not a model. The manifest can deliver a value
|
|
(`Registry` entries with inline payloads already do this for the display
|
|
scope), but it cannot decide WHICH value a given PC should get.
|
|
|
|
## Decision
|
|
|
|
ShopDB owns credential definitions and their targeting. A PC asks for its own
|
|
credentials and receives a decided answer; it never receives rules to evaluate.
|
|
|
|
### Targeting
|
|
|
|
A credential rule carries a targeting expression using the SAME axes
|
|
GE-Enforce already filters on, plus those the asset model knows:
|
|
|
|
| Axis | Source | Notes |
|
|
|---|---|---|
|
|
| hostname | reported | exact or `-like` glob (`WJRP*`) |
|
|
| machine | PC -> machine link | the machine the PC drives |
|
|
| model | asset model | e.g. every Okuma of one model |
|
|
| controller OS | asset / reported | version-valued, like the existing CmmVersion gate |
|
|
| PC type | ComputerType | with GE-Enforce ALIAS EXPANSION |
|
|
| GE-Enforce profile | manifest scope | the imaging profile |
|
|
| DNC/NTLARS setting | stored backup projection | e.g. any machine whose `DataHost` is a given UNC |
|
|
| site default | setting | the fallback |
|
|
|
|
The DNC axis is not a special case bolted on: the NTLARS projection ShopDB
|
|
already stores contains `DataHost`, `DataPath` and `MarkMasterPath`, so "every
|
|
machine that talks to \\ntshare" is a selector over data already held. It is
|
|
also the axis that answers "which machines even need a credential", which
|
|
nothing answers today.
|
|
|
|
### Precedence
|
|
|
|
Overlapping matches are guaranteed, not exceptional - a hostname glob and a
|
|
per-model rule will both hit the same bay. Precedence is therefore EXPLICIT,
|
|
never emergent:
|
|
|
|
1. Each rule carries an integer `priority`. Higher wins. This is the only
|
|
thing an operator needs to reason about.
|
|
2. Ties break on scope specificity, in the order of the table above (hostname
|
|
most specific, site default least).
|
|
3. Remaining ties break on the lowest rule id, so the result is stable rather
|
|
than dependent on row order.
|
|
|
|
A resolve endpoint must be able to EXPLAIN itself - "this PC got rule 12,
|
|
matched on model, beating rule 4 on priority" - or nobody will trust it. The
|
|
GE-Enforce simulator (`applicable_entry_names`) already set this precedent.
|
|
|
|
### Reuse the existing matcher
|
|
|
|
`plugins/geenforce/filters.py` already mirrors the engine's targeting: alias
|
|
groups, hostname globs, the rule that a machine-number filter with no machine
|
|
number EXCLUDES rather than defaults. The resolver reuses it. It must not
|
|
become a third implementation of the same matching logic - there are already
|
|
two (the PowerShell engine and its Python mirror), kept honest by a parity
|
|
harness, and a third would drift silently.
|
|
|
|
Alias expansion in particular is not optional: if a rule says `PCTypes:
|
|
Standard`, it must mean what it means in GE-Enforce, or the two systems will
|
|
disagree about who a rule covers.
|
|
|
|
### Targeting is not detection
|
|
|
|
Who gets a credential and whether it is already applied are separate
|
|
questions, exactly as `PCTypes` and `DetectionMethod` are separate in the
|
|
manifest. The client decides the second locally - is this `cmdkey` entry
|
|
already present and correct - and rewrites only on drift. Conflating them
|
|
rewrites the credential every cycle instead of healing it, and turns the audit
|
|
trail into noise.
|
|
|
|
### Storage
|
|
|
|
- Encrypted at rest with Fernet. `cryptography` is already a dependency.
|
|
- The key lives OUTSIDE the database - instance file or environment, like
|
|
`SECRET_KEY`. A key in the database it protects is not encryption.
|
|
- Write-only through the API. Masked on read, as `smtp_password` already is. A
|
|
fleet PC receives a value; a human never reads one back.
|
|
- A dedicated `credentials.manage` permission for authoring.
|
|
|
|
### Delivery
|
|
|
|
```
|
|
GET /api/collector/credentials X-API-Key: <credentials.fetch token>
|
|
```
|
|
|
|
- A DEDICATED `credentials.fetch` scope, not `collector.ingest`. A leaked
|
|
collector key must not yield controller passwords.
|
|
- The caller is resolved by hostname; it receives only what it is entitled to,
|
|
and never the rule set.
|
|
- Every fetch is audited: which PC, which credential, when. The audit log
|
|
exists; this belongs in it.
|
|
- The client half is a shared helper alongside `ShopdbBackupClient.psm1`:
|
|
fetch, compare, `cmdkey /add` on drift, log once per state.
|
|
|
|
## Consequences
|
|
|
|
Positive:
|
|
|
|
- The cleartext credential leaves the share.
|
|
- Rotation becomes a settings change plus a report of who has picked it up,
|
|
instead of a file edit and a hope.
|
|
- Per-bay, per-model and per-share credentials become expressible, which is the
|
|
actual requirement.
|
|
- "Which machines need a credential" becomes answerable from the DNC data
|
|
already stored.
|
|
|
|
Negative, and these are real:
|
|
|
|
- **ShopDB becomes a credential store.** That is a different security posture
|
|
from an asset database, and it earns the obligations above rather than
|
|
choosing them.
|
|
- **The key is a new single point of loss.** Restore the database without it
|
|
and every stored credential is unrecoverable. `docs/BACKUP-RESTORE.md` must
|
|
say so IN THE SAME CHANGE, not later.
|
|
- A PC that cannot reach ShopDB gets no credential. The client must keep the
|
|
last known good value rather than clearing a working entry on a failed fetch.
|
|
- Targeting complexity is real complexity. Eight axes with priorities will
|
|
produce a rule set someone has to debug, which is why the explain endpoint is
|
|
a requirement and not a nicety.
|
|
|
|
## Alternatives rejected
|
|
|
|
**Keep editing the script on the share.** Cannot express per-bay values, keeps
|
|
the cleartext, no rotation story.
|
|
|
|
**A manifest scope per bay.** Per-machine credentials as GE-Enforce scopes is a
|
|
spreadsheet, not a model, and the manifest cannot resolve WHICH value applies.
|
|
|
|
**Encrypted payload in the manifest.** DPAPI is per-machine, and one manifest
|
|
serves many machines, so the payload cannot be encrypted to its readers.
|
|
|
|
**Registry-only provisioning (no ShopDB).** A worthwhile FIRST STEP - it moves
|
|
the secret off the share immediately and needs no new endpoint - but it leaves
|
|
provisioning per-bay by hand and offers no rotation. Recommended as tier one
|
|
regardless, since the client helper is the same either way.
|
|
|
|
## Implementation status
|
|
|
|
Never implemented, and now superseded. The fetch endpoint and the
|
|
`credentials.*` permissions described above do not exist in the code.
|
|
|
|
The note that stood here until 2026-09-18 said the decision still stood and a
|
|
plugin author designing against it was designing correctly. That is no longer
|
|
true: design against
|
|
[ADR-019](ADR-019-per-pc-endpoint-credentials.md). What credentials the fleet
|
|
uses today, and where they live, is in
|
|
[FLEET-ARCHITECTURE](../FLEET-ARCHITECTURE.md).
|