IF Commons GitHub

logical/observed

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-machine-probe-observation FR-001, 0003-machine-probe-observation FR-002, 0003-machine-probe-observation FR-003

The facts a probe gives, as a typed observation: the sections and key=value lines of its output read into a record of the operating system, the hardware, the security settings, the software and the ports that listen, with what the probe could not tell said as unknown; and the keyed records of that observation that an estate compares with what is declared, which hold nothing that changes only because the time does.

import { parseProbe, toObserved } from "./observed.ts";
const o = toObserved(parseProbe("@probe\nversion=1\nat=2026-12-01T00:00:00Z\n@os\nfamily=ubuntu\nversion=24.04\n"));
o.kind; // "ok"

Source: commons/machine-probe/src/logical/observed.ts

4 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.ProbeOutputtypeno test imports it
type ProbeOutput = Readonly<Record<string, Readonly<Record<string, string>>>>;

A probe's output: sections, each a map of key to value.

logical.parseProbefunctionno test imports it
function parseProbe(text: string): Readonly<Record<string, Readonly<Record<string, string>>>>

The probe's output read: @section lines start a section and key=value lines fill it; a blank line is skipped, and a line before any section belongs to none and is skipped.

logical.Observedtypeno test imports it
type Observed = { /** When (an instant, ISO 8601) and with which version of the probe. */ readonly at: string; rea… (1090 characters)
type Observed = {
  /** When (an instant, ISO 8601) and with which version of the probe. */
  readonly at: string;
  readonly probe: string;
  readonly os: { readonly family: string; readonly name: string; readonly version: string; readonly kernel: string; readonly arch: string; readonly hostname: string; readonly model?: string; readonly serial?: string; readonly flavor?: string; readonly wsl?: boolean };
  readonly hardware: { readonly cpus?: number; readonly memoryMB?: number; readonly diskTotalGB?: number; readonly diskUsedPct?: number };
  /** Security settings: `on`, `off`, `manual` or `unknown`. */
  readonly security: { readonly diskEncryption: string; readonly firewall: string; readonly autoUpdates: string; readonly sshPasswordAuth?: string; readonly antivirus?: string; readonly admins: readonly string[] };
  readonly software: { readonly manager?: string; readonly packages?: number; readonly brewPackages?: number; readonly pendingUpdates?: number; readonly osquery?: string };
  /** The TCP ports that listen, in order. */
  readonly listening: readonly number[];
};

What the probe found on a machine.

logical.toObservedfunctionno test imports it
function toObserved(p: Readonly<Record<string, Readonly<Record<string, string>>>>): Result<Observed, string>

The probe's output as an observation, or why not: a probe that gives no time is refused, because an observation with no time is no evidence.

logical.observedStatefunctionno test imports it
function observedState(o: Observed): Readonly<Record<string, Json>>

The keyed records of an observation that an estate compares with what is declared: the system, the security settings, the software and the ports. The time of the observation, the version of the probe and the counters that change on their own (the memory, the disk in use, the updates waiting) are left out, so that two observations of a machine that did not change are the same.

ProbeOutputtypeno test imports it
type ProbeOutput = Readonly<Record<string, Readonly<Record<string, string>>>>;

A probe's output: sections, each a map of key to value.

parseProbefunction
function parseProbe(text: string): Readonly<Record<string, Readonly<Record<string, string>>>>

The probe's output read: @section lines start a section and key=value lines fill it; a blank line is skipped, and a line before any section belongs to none and is skipped.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

Observedtype
type Observed = { /** When (an instant, ISO 8601) and with which version of the probe. */ readonly at: string; rea… (1090 characters)
type Observed = {
  /** When (an instant, ISO 8601) and with which version of the probe. */
  readonly at: string;
  readonly probe: string;
  readonly os: { readonly family: string; readonly name: string; readonly version: string; readonly kernel: string; readonly arch: string; readonly hostname: string; readonly model?: string; readonly serial?: string; readonly flavor?: string; readonly wsl?: boolean };
  readonly hardware: { readonly cpus?: number; readonly memoryMB?: number; readonly diskTotalGB?: number; readonly diskUsedPct?: number };
  /** Security settings: `on`, `off`, `manual` or `unknown`. */
  readonly security: { readonly diskEncryption: string; readonly firewall: string; readonly autoUpdates: string; readonly sshPasswordAuth?: string; readonly antivirus?: string; readonly admins: readonly string[] };
  readonly software: { readonly manager?: string; readonly packages?: number; readonly brewPackages?: number; readonly pendingUpdates?: number; readonly osquery?: string };
  /** The TCP ports that listen, in order. */
  readonly listening: readonly number[];
};

What the probe found on a machine.

Imported by 7 tests of the run (7 passed, 0 failed): the library's results

toObservedfunction
function toObserved(p: Readonly<Record<string, Readonly<Record<string, string>>>>): Result<Observed, string>

The probe's output as an observation, or why not: a probe that gives no time is refused, because an observation with no time is no evidence.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

observedStatefunction
function observedState(o: Observed): Readonly<Record<string, Json>>

The keyed records of an observation that an estate compares with what is declared: the system, the security settings, the software and the ports. The time of the observation, the version of the probe and the counters that change on their own (the memory, the disk in use, the updates waiting) are left out, so that two observations of a machine that did not change are the same.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

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