IF Commons GitHub

logical/observe

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-integrations-observe FR-001, 0005-integrations-observe FR-002, 0005-integrations-observe FR-003, 0005-integrations-observe FR-004, 0005-integrations-observe FR-005, 0005-integrations-observe FR-006 and 2 more

The logical layer of observation (commons integrations 0005-integrations-observe): the observation record, its entities, the Connector contract with describe, probe and observe as methods, the enforcement of governance on what a connector returns, posture policies as data and the evaluation of a policy against an observation.

A connector is made by defineConnector, which refuses governance with a problem and wraps the connector's observe so that the denylist and the declared entity kinds are applied to what it returns, whatever the connector did. A connector sees a ReadPort, which cannot write.

Source: commons/integrations/src/logical/observe.ts

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

Scalartypeno test imports it
type Scalar = string | number | boolean;

A value a posture or a record's property may hold.

Assettypeno test imports it
type Asset = { readonly kind: string; readonly id: string; readonly name: string; readonly where?: string };

Something the system holds.

Gaptypeno test imports it
type Gap = { readonly kind: "denied" | "unavailable" | "partial" | "entity-kind-not-declared"; readonly subject: string };

What an observation could not see, and of what.

ObservedRecordtypeno test imports it
type ObservedRecord = {
  readonly label: string;
  readonly ocsf_class_uid: number;
  readonly native_id: string;
  readonly display_name: string;
  readonly props: Readonly<Record<string, Scalar>>;
  readonly unmapped?: Readonly<Record<string, Json>>;
};

A record in the terms of OCSF: the label of the world's vocabulary, its OCSF class, the system's id, a name and the properties kept.

PersonStatustypeno test imports it
type PersonStatus = "active" | "terminated" | "leave" | "unknown";

Whether a person is employed.

Persontypeno test imports it
type Person = { readonly email: string; readonly name?: string; readonly status: PersonStatus; readonly start?: string; readonly end?: string; readonly manager?: string; readonly type?: string };

A person, as an observer reports them.

Accounttypeno test imports it
type Account = { readonly system: string; readonly id: string; readonly name: string; readonly email?: string; readonly active: boolean; readonly admin?: boolean; readonly mfa?: boolean; readonly lastLogin?: string; readonly service?: boolean };

An account in a system, as an observer reports it.

Devicetypeno test imports it
type Device = { readonly source: string; readonly id: string; readonly name: string; readonly owner?: string; readonly os?: string; readonly serial?: string; readonly encrypted?: boolean; readonly managed: boolean; readonly seen?: string };

A device, as an observer reports it.

Repositorytypeno test imports it
type Repository = { readonly system: string; readonly name: string; readonly private: boolean; readonly protected?: boolean; readonly reviews?: boolean; readonly secretScanning?: boolean; readonly dependencyAlerts?: boolean };

A code repository, as an observer reports it.

Entitiestypeno test imports it
type Entities = {
  readonly people?: readonly Person[];
  readonly accounts?: readonly Account[];
  readonly devices?: readonly Device[];
  readonly repositories?: readonly Repository[];
};

The entities of an observation, by kind.

ENTITY_LISTSconstno test imports it
const ENTITY_LISTS: Readonly<Record<EntityKind, keyof Entities>>

The kind of entity a list of Entities holds.

Observationtype
type Observation = {
  readonly at: Instant;
  readonly provider: string;
  readonly account: string;
  readonly assets: readonly Asset[];
  readonly posture: Readonly<Record<string, Scalar>>;
  readonly gaps: readonly Gap[];
  readonly entities?: Entities;
  readonly records?: readonly ObservedRecord[];
};

An observation of one account of one provider at one moment.

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

OBSERVATION_SCHEMAconstno test imports it
const OBSERVATION_SCHEMA: "integrations/observation/1"

The schema id of a persisted observation.

ObservationDocumenttypeno test imports it
type ObservationDocument = { readonly kind: "observation"; readonly schema: typeof OBSERVATION_SCHEMA; readonly observation: Observation };

A persisted observation: it has a kind and a schema, as every persisted document does.

documentOfconst
const documentOf: (observation: Observation) => ObservationDocument

An observation as the document that is persisted.

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

parseObservationDocumentfunction
function parseObservationDocument(input: unknown): Result<Observation, DecodeError>

Reads a persisted observation back: a document of the right kind and schema, and every field of the right type, or the first error with its path.

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

ObserveErrortypeno test imports it
type ObserveError = | { readonly kind: "denied"; readonly subject: string } | { readonly kind: "unavailable"; readon… (420 characters)
type ObserveError =
  | { readonly kind: "denied"; readonly subject: string }
  | { readonly kind: "unavailable"; readonly subject: string }
  | { readonly kind: "transport"; readonly subject: string; readonly failure: ReadFailure["kind"] }
  | { readonly kind: "decode"; readonly subject: string; readonly expected: string }
  | { readonly kind: "credential"; readonly why: "missing" | "denied" | "vault-unavailable" };

Why an observation or a probe has failed; none of them carries a payload.

fromReadFailurefunction
function fromReadFailure(f: ReadFailure): ObserveError

An observe error from a read failure: a denial and a missing resource are what the system said, the rest is the transport's.

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

gapOffunction
function gapOf(e: ObserveError): Gap | undefined

A gap from an error a connector may carry on: what was denied or unavailable is a gap and not a failure.

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

ObserveContexttypeno test imports it
type ObserveContext = { readonly port: ReadPort; readonly now: Instant };

What a connector is told to observe with.

ProbeReporttypeno test imports it
type ProbeReport = { readonly reachable: true; readonly account: string };

What a probe finds: the system answered the credential, and how the credential is seen by the system.

PosturePolicytype
type PosturePolicy = {
  readonly id: string;
  readonly title: string;
  readonly fact: string;
  readonly want: Expectation;
  readonly severity: Severity;
  readonly onMiss: "fail" | "warn";
  readonly controls: readonly string[];
  readonly fix: string;
};

A posture policy as data, in the vocabulary of GRC (@intellectual-frontiers/grc): the fact it reads, an Expectation of GRC (equals of the scalar; for a bound, every over the one row {value} with the operator ge or le; non-empty for presence), how serious a miss is (GRC's Severity), what status a miss has (fail or warn), the controls it bears on (GRC control urns, attached by the consumer) and what to do.

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

PostureStatustypeno test imports it
type PostureStatus = Status;

How a policy came out: a status of GRC (unknown of the earlier shape is GRC's pending: the fact is not yet observed).

PostureResulttypeno test imports it
type PostureResult = { readonly id: string; readonly title: string; readonly status: Status; readonly severity: Severity; readonly controls: readonly string[]; readonly detail: string; readonly fix: string };

The result of one policy: GRC's status and severity, and what is said of it.

evaluatePolicyfunction
function evaluatePolicy(policy: PosturePolicy, o: Observation): PostureResult

One policy against an observation: pending where the fact was not observed, else GRC's evaluation of the fact against the expectation (a pass, the policy's onMiss, or an error where the fact is not the shape the expectation needs).

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

freshnessResultfunction
function freshnessResult(c: Cadence, o: Observation, now: Instant): PostureResult

The freshness policy every connector has: the observation is not stale at now.

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

Descriptiontypeno test imports it
type Description = { readonly id: string; readonly title: string; readonly class: ConnectorClass; readonly label… (414 characters)
type Description = {
  readonly id: string;
  readonly title: string;
  readonly class: ConnectorClass;
  readonly labels: Labels;
  readonly scope: Scope;
  readonly cadence: Cadence;
  readonly entities: readonly EntityKind[];
  readonly credentialFields: readonly { readonly name: string; readonly secret: boolean; readonly hint: string }[];
  readonly policies: readonly string[];
  readonly readOnly: true;
};

What a connector says of itself: derived from its governance, so that it cannot differ from it. It holds no credential field value, only their names and hints.

Connectortype
type Connector = { readonly governance: ConnectorGovernance; readonly policies: readonly PosturePolicy[]; readonly… (406 characters)
type Connector = {
  readonly governance: ConnectorGovernance;
  readonly policies: readonly PosturePolicy[];
  readonly describe: () => Description;
  readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
  readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
  readonly check: (o: Observation, now: Instant) => readonly PostureResult[];
};

A connector: its governance, and the three things it can do as methods.

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

ConnectorSpectypeno test imports it
type ConnectorSpec = {
  readonly governance: ConnectorGovernance;
  readonly probe: (ctx: ObserveContext) => Promise<Result<ProbeReport, ObserveError>>;
  readonly observe: (ctx: ObserveContext) => Promise<Result<Observation, ObserveError>>;
  readonly policies: readonly PosturePolicy[];
};

What the author of a connector writes: the governance, a read that proves the credential, what it observes and its policies.

DefinitionErrortypeno test imports it
type DefinitionError = { readonly kind: "governance"; readonly problems: readonly GovernanceProblem[] } | { readonly kind: "duplicate-policy"; readonly id: string };

Why a connector is not defined.

enforcefunctionno test imports it
function enforce(g: ConnectorGovernance, o: Observation): Observation

Applies the governance of a connector to an observation: denied properties of records are removed, entity kinds the connector did not declare are removed and named as gaps.

defineConnectorfunction
function defineConnector(spec: ConnectorSpec): Result<Connector, DefinitionError>

A connector from what its author wrote, or why not.

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

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