Scalartypeno test imports ittype Scalar = string | number | boolean;A value a posture or a record's property may hold.
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.
Scalartypeno test imports ittype Scalar = string | number | boolean;A value a posture or a record's property may hold.
Assettypeno test imports ittype Asset = { readonly kind: string; readonly id: string; readonly name: string; readonly where?: string };Something the system holds.
Gaptypeno test imports ittype 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 ittype 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 ittype PersonStatus = "active" | "terminated" | "leave" | "unknown";Whether a person is employed.
Persontypeno test imports ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 itconst ENTITY_LISTS: Readonly<Record<EntityKind, keyof Entities>>The kind of entity a list of Entities holds.
Observationtypetype 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.
OBSERVATION_SCHEMAconstno test imports itconst OBSERVATION_SCHEMA: "integrations/observation/1"The schema id of a persisted observation.
ObservationDocumenttypeno test imports ittype 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.
documentOfconstconst documentOf: (observation: Observation) => ObservationDocumentAn observation as the document that is persisted.
parseObservationDocumentfunctionfunction 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.
ObserveErrortypeno test imports ittype 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.
fromReadFailurefunctionfunction fromReadFailure(f: ReadFailure): ObserveErrorAn observe error from a read failure: a denial and a missing resource are what the system said, the rest is the transport's.
gapOffunctionfunction gapOf(e: ObserveError): Gap | undefinedA gap from an error a connector may carry on: what was denied or unavailable is a gap and not a failure.
ObserveContexttypeno test imports ittype ObserveContext = { readonly port: ReadPort; readonly now: Instant };What a connector is told to observe with.
ProbeReporttypeno test imports ittype 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.
PosturePolicytypetype 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.
PostureStatustypeno test imports ittype 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 ittype 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.
evaluatePolicyfunctionfunction evaluatePolicy(policy: PosturePolicy, o: Observation): PostureResultOne 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).
freshnessResultfunctionfunction freshnessResult(c: Cadence, o: Observation, now: Instant): PostureResultThe freshness policy every connector has: the observation is not stale at now.
Descriptiontypeno test imports ittype 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.
Connectortypetype 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.
ConnectorSpectypeno test imports ittype 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 ittype DefinitionError = { readonly kind: "governance"; readonly problems: readonly GovernanceProblem[] } | { readonly kind: "duplicate-policy"; readonly id: string };Why a connector is not defined.
enforcefunctionno test imports itfunction enforce(g: ConnectorGovernance, o: Observation): ObservationApplies 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.
defineConnectorfunctionfunction defineConnector(spec: ConnectorSpec): Result<Connector, DefinitionError>A connector from what its author wrote, or why not.