randomparity / randomparity/kdive

Define the read scope for the Host Interface posture in byo_adopt_facts

Open
#1,896 0 comments 0 reactions 0 assignees View on GitHub
area:mcp-api area:security effort:S priority:P2 provider:baremetal-bmc risk:daytime-only status:blocked type:spec
Dominant language
Python
Stars
0
Forks
0
Avg merge
1h 26m
Merged PRs (30d)
311

Description

Follow-up from #1847 / PR #1890. Raised in adversarial review of ADR-0547.

## Problem

ADR-0547 decides that adopt records the host's Redfish **Host Interface** posture into
`systems.byo_adopt_facts` — whether the host OS can reach its own BMC, and with what
authentication. It does not say **who may read that back**, and neither does ADR-0540, which
claims the column.

The posture is not an ordinary inventory fact. `unauthenticated` is a statement that this physical
machine has an unauthenticated in-band path to its service processor, which is directly useful to
anyone who can get code onto it — and KDIVE's whole purpose is putting operator-supplied kernels
onto it. Whatever surface reflects `byo_adopt_facts` to an agent would be publishing that.

The redaction obligation ADR-0073 covers is the **credential**, and ADR-0547 already handles it
(the recorded fact carries authentication *modes* only; nothing from a `CredentialBootstrapping`
object is read). Read scope on the resulting non-secret fact is a separate question and is
currently unstated.

## Evidence

- `docs/adr/0547-host-interface-in-band-bmc-path.md` — Decision, question 3 (what is recorded);
the ADR-0073 note bounds what is read, not who may read it back.
- `docs/adr/0540-adopt-only-provisioning.md` — claims `systems.byo_adopt_facts jsonb` as "where
adopt records what it established"; no read-scope statement.
- The neighbouring surface division is already non-obvious and documented in
`docs/design/m4-byo-host.md`: neither `resources.list` nor `resources.describe` emits the
`cordoned` flag; only `resources.availability` does. So "which tool would surface an adopt fact,
if any" needs answering rather than assuming.
- `src/kdive/mcp/tools/catalog/_resource_envelopes.py` emits a fixed key set, so a namespaced key
routed through it would be dropped silently — the failure mode here is a fact that is neither
deliberately exposed nor deliberately withheld.

## Expected outcome

- A stated read scope for the Host Interface posture in `byo_adopt_facts`: which tool (if any)
surfaces it, and to which role. The plausible answer is operator-only — the same platform-role
gate `ops/` tools sit behind — with nothing on the agent-facing catalog surface, but it should
be decided rather than inherited.
- Whichever way it goes, a test that pins it, so the fact cannot start appearing in an envelope
through an unrelated change.
- If any agent-facing surface does carry it, the wrapper docstring and `Field` text state what it
means, per this repo's MCP surface rules.

Scope note: this is a read-scope decision on a fact #1823 writes. Sized to one PR alongside that
entry, or immediately after it.

Blocked by #1823

Contributor guide

Open the contributing guide

Research direction

Start with docs/adr/0547-host-interface-in-band-bmc-path.md and docs/adr/0540-adopt-only-provisioning.md, then inspect docs/design/m4-byo-host.md and src/kdive/mcp/tools/catalog/_resource_envelopes.py. Trace the relevant MCP surfaces and existing role gates before deciding the read scope. Done means the scope is documented, a test pins exposure or withholding, and any agent-facing wrapper text is updated if needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
authorization, backend, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.