IF Commons GitHub

governance/observe

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-integrations-governance FR-004, 0002-integrations-governance FR-005, 0002-integrations-governance FR-006, 0002-integrations-governance FR-007, 0002-integrations-governance FR-008, 0002-integrations-governance FR-009

The governance of observation (commons integrations 0002-integrations-governance): what a connector is allowed to be and to read, as data that names no vendor, no HTTP and no file path. A connector has a class, one read-only contract, a credential reference with its least-privilege scope, a cadence, the kinds of entity it may produce and the fields that are never kept, labels in the world's terms, and a policy for the trust it places in the system it reads.

Every list is a closed union with an exhaustive switch where it is read; the policy data of a consumer (a fleet's paths, an estate's labels, a catalogue of controls) is attached by the consumer and is not in this module.

Source: commons/integrations/src/governance/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.

ConnectorClasstypeno test imports it
type ConnectorClass = "cloud" | "identity" | "code-host" | "hr" | "endpoint" | "ticketing" | "network-device" | "vulnerability";

What a connector connects to.

CONNECTOR_CLASSESconst
const CONNECTOR_CLASSES: readonly ConnectorClass[]

The classes of system a connector observes: cloud, identity, code host, HR, endpoint and the like.

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

ServiceModeltypeno test imports it
type ServiceModel = "IaaS" | "PaaS" | "SaaS";

The service models of NIST SP 800-145.

Labelstypeno test imports it
type Labels = { readonly serviceModels: readonly ServiceModel[]; readonly categories: readonly string[] };

The labels of a connector in the world's terms: its service models and the categories a consumer's own vocabulary (an analyst's, a catalogue's) names.

Accesstypeno test imports it
type Access = "read";

The only thing a connector may do to a system it observes.

Granttypeno test imports it
type Grant = { readonly resource: string; readonly access: Access };

One grant of the least-privilege scope: a resource the credential must reach, named in the system's own words, and read access.

Scopetypeno test imports it
type Scope = { readonly grants: readonly Grant[] };

The least privilege a connector needs: its grants, all read.

ReadOnlyContracttypeno test imports it
type ReadOnlyContract = { readonly writes: "never"; readonly tokenEndpoints: readonly string[] };

The read-only contract: a connector never changes what it observes, and this is a value so that a conformance check can hold it.

EntityKindtypeno test imports it
type EntityKind = "person" | "account" | "device" | "repository";

The kinds of entity an observation may carry.

ENTITY_KINDSconstno test imports it
const ENTITY_KINDS: readonly EntityKind[]

The kinds of entity that observing produces: person, account, device and repository.

FieldPatterntypeno test imports it
type FieldPattern =
  | { readonly kind: "exact"; readonly text: string; readonly why: string }
  | { readonly kind: "contains"; readonly text: string; readonly why: string };

What the denylist matches: a field name exactly, or a field name containing the text, ignoring case.

Denylisttypeno test imports it
type Denylist = { readonly patterns: readonly FieldPattern[] };

The fields that are never kept, whichever connector reads them.

GENERIC_DENYLISTconstno test imports it
const GENERIC_DENYLIST: Denylist

The generic denylist: personal, compensation and secret fields. A connector may add to it and never remove from it.

isDeniedfunction
function isDenied(list: Denylist, field: string): boolean

Whether a field name is denied by a denylist.

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

denylistWithconst
const denylistWith: (extra: readonly FieldPattern[]) => Denylist

The denylist of a connector: the generic one and what the connector adds.

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

Cadencetypeno test imports it
type Cadence = { readonly every: Duration; readonly staleAfter: Duration };

A cadence: how often the system is observed, and after how long an observation is stale.

MAX_STALE_MSconst
const MAX_STALE_MS: number

An observation is never held fresh for longer than seven days.

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

CadenceErrortypeno test imports it
type CadenceError =
  | { readonly kind: "cadence-text"; readonly error: IdError }
  | { readonly kind: "stale-before-every"; readonly every: Duration; readonly staleAfter: Duration }
  | { readonly kind: "stale-beyond-cap"; readonly staleAfter: Duration };

Why a cadence is refused.

cadencefunction
function cadence(every: string, staleAfter?: string | undefined): Result<Cadence, CadenceError>

A cadence from every (15m, 6h, 1d) and, where given, staleAfter: by default twice every, never more than seven days, never less than every.

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

isStaleconst
const isStale: (c: Cadence, at: Instant, now: Instant) => boolean

Whether an observation made at at is stale at now.

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

CredentialFieldtypeno test imports it
type CredentialField = { readonly name: string; readonly secret: boolean; readonly hint: string };

A field of the credential a person gives the vault: its name, whether it is secret and a hint. A secret field is never optional.

CredentialSpectypeno test imports it
type CredentialSpec = { readonly ref: CredentialRef; readonly fields: readonly CredentialField[] };

The credential a connector needs: where the vault keeps it (a reference, never a value) and its fields.

CredentialSpecErrortypeno test imports it
type CredentialSpecError = { readonly kind: "no-secret-field" } | { readonly kind: "field-without-hint"; readonly name: string } | { readonly kind: "duplicate-field"; readonly name: string };

Why a credential spec is refused.

credentialSpecfunction
function credentialSpec(ref: CredentialRef, fields: readonly CredentialField[]): Result<CredentialSpec, CredentialSpecError>

A credential spec that has at least one secret field, a hint on each field and no field twice.

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

PinOrigintypeno test imports it
type PinOrigin = "trust-on-first-use" | "preconfigured";

How a pinned certificate came to be trusted: the first one seen (trust on first use), or one that was set beforehand.

TlsPolicytype
type TlsPolicy =
  | { readonly kind: "system-roots" }
  | { readonly kind: "pinned"; readonly origin: PinOrigin; readonly sha256: Sha256 | undefined };

How the TLS of a system is trusted.

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

TransportPolicytypeno test imports it
type TransportPolicy =
  | { readonly kind: "https"; readonly hosts: readonly string[]; readonly tls: TlsPolicy }
  | { readonly kind: "snmp-v3"; readonly level: "authPriv" };

How the system is reached: over HTTPS to listed hosts, or over SNMPv3.

ConnectorGovernancetypeno test imports it
type ConnectorGovernance = {
  readonly id: ConnectorId;
  readonly title: string;
  readonly class: ConnectorClass;
  readonly labels: Labels;
  readonly contract: ReadOnlyContract;
  readonly credential: CredentialSpec;
  readonly scope: Scope;
  readonly cadence: Cadence;
  readonly entities: readonly EntityKind[];
  readonly denylist: Denylist;
  readonly transport: TransportPolicy;
};

The governance of one connector.

GovernanceProblemtypeno test imports it
type GovernanceProblem =
  | { readonly kind: "no-scope" }
  | { readonly kind: "no-host" }
  | { readonly kind: "pin-without-digest"; readonly origin: "preconfigured" }
  | { readonly kind: "denylist-weaker"; readonly missing: string }
  | { readonly kind: "no-service-model" }
  | { readonly kind: "entity-twice"; readonly entity: EntityKind };

What is wrong with the governance of a connector.

governanceProblemsfunction
function governanceProblems(g: ConnectorGovernance): readonly GovernanceProblem[]

Every problem of a connector's governance; none where it may be used.

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

PinDecisiontypeno test imports it
type PinDecision =
  | { readonly kind: "accept" }
  | { readonly kind: "remember"; readonly sha256: Sha256 }
  | { readonly kind: "refuse"; readonly why: "mismatch" | "no-pin-and-not-first-use" | "not-pinned-policy" };

What the next contact with a system does about its pinned certificate.

decidePinfunction
function decidePin(policy: TlsPolicy, shown: Sha256, remembered: Sha256 | undefined): PinDecision

What a pinned policy does with the digest the system shows and the one remembered (or none): a total function of the policy, the shown digest and what is remembered.

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

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