IF Commons GitHub

Machine probe observation

0003Active

0003-machine-probe-observation · owner if · domain commons

Requirements

FR-001checkpassing

parseProbe MUST read @section lines and key=value lines into a record of sections, MUST accept lines ending in a carriage return, and MUST skip blank lines and lines before any section.

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

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

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

Tests: passed: suite/observation.test.ts sections and key=value lines are read, a carriage return is dropped, blank lines and lines

FR-002checkpassing

toObserved MUST give a typed observation from the sections, with unknown for a security setting the probe did not give, numbers as numbers, the administrators sorted and the ports in order, and MUST refuse a probe that gave no time, because an observation with no time is not evidence.

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

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

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

Tests: passed: suite/observation.test.ts the output of a real probe is a typed observation with unknown for what the probe did not

FR-003checkpassing

observedState MUST give keyed records of the system, the security settings, the software and the ports, and MUST NOT hold the time of the observation, the version of the probe or a counter that changes on its own, so that two observations of a machine that did not change are equal.

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

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

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

Tests: passed: suite/observation.test.ts the keyed records hold no time, no probe version and no counter, so two observations of a

FR-004checkpassing

observe MUST give the observation of a machine sent facts, unreachable where the command did not run or the ssh client could not reach it (status 255), refused where the probe ended with another status, and unreadable where what it printed is not facts; and query MUST refuse a query that is not one SELECT before sending anything, and give the rows of osquery as text.

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

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

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

Tests: passed: suite/observation.test.ts an observation is given only where the probe answered; unreachable, refused and unreadable

Acceptance scenarios

  1. Given the output of a real probe on Ubuntu, When it is read, Then the family is ubuntu, the version 24.04 and the packages are counted, per FR-001 and FR-002.
  2. Given a probe output with no time, When it is read, Then it is refused, per FR-002.
  3. Given two observations that differ only in time, When their keyed records are compared, Then they are equal, per FR-003.
  4. Given a command that ends with 255, When the machine is observed, Then the error is unreachable and never an observation, per FR-004.

Out of scope

Edge cases

  • A value that contains = keeps everything after the first =, per FR-001.

Assumptions

  • Every value of osquery is text, as osquery prints it.

Open questions

  • None.

Key entities

  • Observation - what the probe found on a machine, with the time and the version of the probe.

Success criteria

SC-001success criterion

A machine that cannot be asked is never reported as agreeing with what is declared.

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.