96df19702e
DEPLOY-WINDOWS-IIS was a second copy of the manual IIS procedure that had diverged from the first: a different MySQL version (8.0, which reached end of life in April), a different port, a different plugin list, and a profile file that does not exist. Two runbooks for one procedure means a reader follows whichever they found, and one of them was wrong. INSTALL-WINDOWS-IIS covers everything it did plus a preflight step and the subpath method, so the one section it uniquely had - redeploying a hand-built server - is folded in there, with the plugin-chain step it was missing and a note to back up first, and the duplicate is gone. Everything that pointed at it now points at the survivor. Three ADR statuses said something untrue. ADR-013 said PROPOSED while half of it had shipped and ADR-014 had been accepted on top of it. A decision that has been implemented and depended upon is not proposed, and leaving one that way devalues every other status in the index. The catalog half is still unbuilt, which is the ordinary state of an accepted decision: accepted means settled, not delivered. ADR-016 said ACCEPTED for a design where nothing is built - the endpoint and permissions it describes do not exist, so a reader goes looking for them. The status stands, because the decision does; the header now says so plainly and points at where today's credentials actually live. ADR-003 and ADR-004 were ACCEPTED with their own Decision lines still opening "**PROPOSED:**", which reads as though the decision was never taken. And the dashboard proposal carried Status: ACCEPTED, which belongs to a decision record. A proposal is a proposal; the contract it produced is the ADR.
183 lines
8.1 KiB
Markdown
183 lines
8.1 KiB
Markdown
# ADR-016: Credential delivery to the fleet
|
|
|
|
- Status: ACCEPTED (decided; NOT yet implemented - see Implementation status)
|
|
- Date: 2026-08-11
|
|
- Deciders: ShopDB maintainers
|
|
- Relates to: ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership), ADR-015 (site-specific configuration)
|
|
|
|
## 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, 2026-08-14
|
|
|
|
Nothing in this ADR is built yet. The fetch endpoint and the `credentials.*`
|
|
permissions it describes do not exist in the code, and a reader searching for
|
|
them will not find them.
|
|
|
|
Recorded here rather than by changing the status, because the decision itself
|
|
stands: this is how credential delivery WILL work, and a plugin author designing
|
|
against it is designing correctly. What credentials the fleet uses today, and
|
|
where they live, is in [FLEET-ARCHITECTURE](../FLEET-ARCHITECTURE.md).
|