IF Commons GitHub

governance/requests

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-machine-probe-contract FR-001

What a probe answers: three requests (facts, version, and one osquery SELECT). A request that is none of the three is refused here, before anything is run, and the script on the machine refuses it again. How a probe is reached is the ssh target of Headless, and the line of authorized_keys that restricts a key to it is generated by the inbound surface of Headless (see the physical layer).

import { parseRequest, encodeRequest } from "./requests.ts";
const r = parseRequest("facts"); // { kind: "ok", value: { kind: "facts" } }
encodeRequest({ kind: "osquery", sql: "SELECT 1" }); // "osquery U0VMRUNUIDE="

Source: commons/machine-probe/src/governance/requests.ts

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

governance.PROBE_PROGRAMconstno test imports it
const PROBE_PROGRAM: "machine-probe"

The name of the probe program on a machine.

governance.PROBE_PATHconstno test imports it
const PROBE_PATH: ".local/bin/machine-probe"

Where the probe is installed for the account that runs it, relative to its home folder (the forced command runs from there): no root, nothing listening.

governance.ProbeRequesttypeno test imports it
type ProbeRequest = { readonly kind: "facts" } | { readonly kind: "version" } | { readonly kind: "osquery"; readonly sql: string };

A request: the facts of the machine, the version of the probe, or one osquery SELECT.

governance.encodeRequestfunctionno test imports it
function encodeRequest(r: ProbeRequest): string

The text of a request as sent to the probe: facts, version or osquery <base64 of the SELECT>.

governance.parseRequestfunctionno test imports it
function parseRequest(text: string): Result<ProbeRequest, string>

A request from its text, or why it is refused: only facts, version and osquery <base64> of one statement that only reads, as the guard of the SQL language library judges it by its tree in the SQLite dialect of osquery (no second statement, no write).

governance.ProbeReachtypeno test imports it
type ProbeReach = { readonly address: string; readonly port?: number; readonly user: string; readonly credential: string };

How to reach a machine for observation: the account the probe runs as, the address and port, and the name of the key made for the probe. The name is a reference: the key itself is kept outside the repository, where only the machine that observes has it.

import type { ProbeReach } from "./requests.ts";
const reach: ProbeReach = { address: "sparta.example", user: "admin", credential: "sparta-probe" };
PROBE_PROGRAMconstno test imports it
const PROBE_PROGRAM: "machine-probe"

The name of the probe program on a machine.

PROBE_PATHconst
const PROBE_PATH: ".local/bin/machine-probe"

Where the probe is installed for the account that runs it, relative to its home folder (the forced command runs from there): no root, nothing listening.

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

ProbeRequesttypeno test imports it
type ProbeRequest = { readonly kind: "facts" } | { readonly kind: "version" } | { readonly kind: "osquery"; readonly sql: string };

A request: the facts of the machine, the version of the probe, or one osquery SELECT.

encodeRequestfunction
function encodeRequest(r: ProbeRequest): string

The text of a request as sent to the probe: facts, version or osquery <base64 of the SELECT>.

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

parseRequestfunction
function parseRequest(text: string): Result<ProbeRequest, string>

A request from its text, or why it is refused: only facts, version and osquery <base64> of one statement that only reads, as the guard of the SQL language library judges it by its tree in the SQLite dialect of osquery (no second statement, no write).

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

ProbeReachtypeno test imports it
type ProbeReach = { readonly address: string; readonly port?: number; readonly user: string; readonly credential: string };

How to reach a machine for observation: the account the probe runs as, the address and port, and the name of the key made for the probe. The name is a reference: the key itself is kept outside the repository, where only the machine that observes has it.

import type { ProbeReach } from "./requests.ts";
const reach: ProbeReach = { address: "sparta.example", user: "admin", credential: "sparta-probe" };

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