IF Commons GitHub

GRC runners

0005Active

0005-grc-runners · owner if · domain grc

The port

FR-001checkpassing

A runner MUST be { id, run(check, ctx) }, its id being the kind a check names, returning Result<Observation, RunnerProblem>, where an observation is { value, observedAt, via, tookMs } and value is JSON data; runners MUST be registered by kind in a registry of runners, and a second runner of one kind MUST be refused.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/physical/runner.ts

Tests: passed: suite/runners.test.ts a runner is registered by kind, a second of one kind is refused, and a runner gives an obs

FR-002checkpassing

runCheck MUST, for a check and a subject, find whether the check applies to the subject's platform (a result of not-applicable where it does not), find the runner by the check's kind (a grc.result of status error naming the kind where there is none), run it, judge the observation by evaluate (0003), and make the grc.result; a runner that throws or returns a problem MUST give error for that subject and MUST NOT stop the other checks of runChecks.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/physical/runner.ts

Tests: passed: suite/runners.test.ts runCheck makes the result: not-applicable, an unknown kind, a throw and a timeout are resu

FR-003checkpassing

The time MUST come from a clock the caller gives, and a run MUST be bounded by a timeout the caller gives.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/physical/runner.ts

Tests: passed: suite/runners.test.ts runCheck makes the result: not-applicable, an unknown kind, a throw and a timeout are resu

The runners

FR-004checkpassing

The sql runner MUST take its input as { query, params? } and run it on a connection of the shape { query(text, params) -> rows, readOnly } that the host gives; it MUST refuse a connection that is not read-only, and MUST refuse a query that the guard of the SQL language library (@intellectual-frontiers/lang-sql/aide/guard) does not judge, in the dialect of the connection (ANSI where none is given), to be a single read: more than one statement, a write, a SELECT ... INTO and a PRAGMA that sets are refused by the tree, so a word in a string or a comment is not code; the value is the rows. It MUST import no database library.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/sql/mod.ts

Tests: passed: suite/runners.test.ts the sql runner needs a read-only connection and a single read, and imports no database lib

Cited by: GRC, runners/sql/mod

FR-005checkpassing

The file runner MUST take { path, format, select? } and read the file by a reader the host gives, decode it as json, lines or text, and select a value by a JSON pointer (RFC 6901); a missing file is a problem, not a value.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/file/mod.ts

Tests: passed: suite/runners.test.ts the file runner reads json, lines or text, selects by a JSON pointer, and a missing file i

Cited by: GRC, runners/file/mod

FR-006checkpassing

The api runner MUST take { method, url, select? } (GET and HEAD only) and call a client of the shape { fetch(request) -> { status, body } } that the host gives; the value is { status, body } or what select picks.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/api/mod.ts

Tests: passed: suite/runners.test.ts the api runner makes a GET or HEAD call by a client and selects from the response

Cited by: GRC, runners/api/mod

FR-007checkpassing

The remote runner MUST take { target, argv } and run it on a remote of the shape { exec(target, argv) -> { code, stdout, stderr } } that the host gives (the targets of Headless satisfy it); the value is the code and the output.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/remote/mod.ts

Tests: passed: suite/runners.test.ts the remote runner runs argv on a target by a remote and observes the code and the output

Cited by: GRC, runners/remote/mod

FR-008checkpassing

The manual runner MUST give the status pending until a grc.attestation for the check and subject exists that was made by a role the evidence policy lets attest and is not older than the policy's longest age, and then pass or fail by the attestation's claim; it MUST never answer a question by itself.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/manual/mod.ts

Tests: passed: suite/runners.test.ts the manual runner is pending until a role that may attest has attested within the longest

Cited by: GRC, runners/manual/mod

FR-009checkpassing

The external runner MUST delegate to an evaluator found by id in a registry of evaluators ({ id, evaluate(input, data) }); GRC ships none, so that OPA/Rego and CEL are optional adapters a third party registers, and an unknown evaluator id is a problem that names it.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Written in: grc/src/runners/external/mod.ts

Tests: passed: suite/runners.test.ts the external runner delegates to an evaluator found by id and names an unknown one

Cited by: GRC, runners/external/mod

Conformance

FR-010checkpassing

A conformance suite for runners MUST run any registered runner against fixtures its author gives (an input and the value it must observe) and return each failure as data, and it MUST check that the runner gives the same value for the same input and never an exception; the suite is run on every runner of this library.

Enforced (check): .github: cd commons/grc && bun run verify — suite/runners.test.ts

Proved by: grc/suite/runners.test.ts

Tests: passed: suite/runners.test.ts the conformance suite passes the runners of the library and fails a runner that is not det

Cited by: conformance/mod, GRC

Scenarios

  • Given a check of kind sql and a connection that is not read-only, When the check is run, Then the result is error naming it, per FR-004.
  • Given a check of kind nothing-registered, When the check is run, Then the result is error and names the kind, per FR-002.
  • Given a check of kind manual with no attestation, When the check is run, Then pending; with a role not allowed to attest, pending and the reason, per FR-008.
  • Given the query select 1; drop table t, When the check is run, Then it is refused, per FR-004.

Out of scope

  • Writing a driver for any database; scheduling runs; OPA and CEL adapters.

Edge cases

  • A check that applies to linux run on a windows subject: not-applicable, runner never called, per FR-002.
  • A pointer to a missing member: a problem, per FR-005.

Assumptions

  • A host that wants writes through sql is out of the port: a runner reads.

Open questions

OQ-1open question

Whether an osquery connection should declare its tables so that applicability is checked before the run.

Key entities

  • Runner, Observation, Registry of runners.

Success criteria

SC-001success criterion

A new runner of a third party passes conformance and runs with no change to the core.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

conformance/mod, GRC, physical/runner, runners/api/mod, runners/external/mod, runners/file/mod, runners/manual/mod, runners/remote/mod, runners/sql/mod, GRC governance, GRC logical model

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