IF Commons GitHub

Enrolling a machine for observation

0007Active

0007-machine-probe-enroll · owner if · domain commons

Requirements

FR-001checkpassing

An address MUST be read as user@host or user@host:port (a port from 1 to 65535), and anything else MUST be refused with the reason.

Enforced (check): .github: cd commons/machine-probe && bun run verify — suite/enroll.test.ts

Proved by: machine-probe/suite/enroll.test.ts

Written in: machine-probe/src/physical/enroll.ts

Tests: passed: suite/enroll.test.ts an address is user@host or user@host:port, and anything else is refused

FR-002checkpassing

Enrolling MUST first show the fingerprints of the host keys the machine presents and do nothing else (it MUST write no file and install nothing) until the person gives the fingerprint they compared; a fingerprint that is not one of the machine's MUST pin nothing and install nothing and say so.

Enforced (check): .github: cd commons/machine-probe && bun run verify — suite/enroll.test.ts

Proved by: machine-probe/suite/enroll.test.ts

Written in: machine-probe/src/physical/enroll.ts

Tests: passed: suite/enroll.test.ts on a real sshd the host key is shown first, a wrong fingerprint pins and installs nothing,

FR-003checkpassing

With the right fingerprint, enrolling MUST pin that host key and only it in the known-hosts file (once, however many times it is repeated), make a key for the probe in the folder of keys (readable by its owner alone, made once), and install the probe and exactly one line that restricts the key to it in the person's own account over the person's own ssh (once, however many times it is repeated), and MUST give the reach, the file of the private key and the line; the probe MUST then answer to the restricted key through probeExecutor.

Enforced (check): .github: cd commons/machine-probe && bun run verify — suite/enroll.test.ts

Proved by: machine-probe/suite/enroll.test.ts

Written in: machine-probe/src/physical/enroll.ts

Tests: passed: suite/enroll.test.ts on a real sshd the host key is shown first, a wrong fingerprint pins and installs nothing,

FR-004checkpassing

The observation of a machine MUST be judged by the policy pack and the risks accepted for it: an accepted risk is accepted and never a pass, and a machine that was never observed is waiting in the policy that says so and MUST NOT be failing.

Enforced (check): .github: cd commons/machine-probe && bun run verify — suite/enroll.test.ts

Proved by: machine-probe/suite/enroll.test.ts

Written in: machine-probe/src/logical/judge.ts

Tests: passed: suite/enroll.test.ts a machine never observed is waiting in the policy that says so and never failing, and an o

Acceptance scenarios

  1. Given a machine and no fingerprint, When it is enrolled, Then its fingerprints are shown and nothing is written or installed, per FR-002.
  2. Given the right fingerprint, When it is enrolled twice, Then one host key is pinned and one restricted line is installed, per FR-003.

Out of scope

Edge cases

  • A machine that presents several host keys: the one compared is pinned, per FR-002.

Assumptions

  • The person's own ssh reaches the machine as the account.

Open questions

  • None.

Key entities

  • Enrollment, Reach, Judgement.

Success criteria

SC-001success criterion

A machine is enrolled and observed with a key that can do nothing else.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.