IF Commons GitHub

sql/extensions/osquery/driver

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0058-sql-osquery FR-004, 0058-sql-osquery FR-005, 0058-sql-osquery FR-006

A read-only driver for osquery (commons data 0058-sql-osquery FR-004 to FR-006): a Driver of the library (0056) that asks osqueryi --json "<sql>" on demand, through a function that runs a program (the caller gives it, system.proc.run in practice, so that this library depends on no runtime). Only a SELECT (or a WITH that ends in one) of one statement is run: anything else, and a table that osquery has for its side effects, is refused as an error value before a process is started; a table that does not exist on the platform is a typed error that says where it does. Rows are given with the types of the schema, since osquery prints every value as text.

Source: commons/data/sql/extensions/osquery/driver.ts

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

MachineTargetinterfaceno test imports it
interface MachineTarget

A machine that a fan-out (0059) can ask: a name, its platform and the read-only driver; the shape of a federation target, without depending on it.

MemberTypeWhat it is
idstring
platformPlatform
driverDriver
OsqueryErrortypeno test imports it
type OsqueryError = | { readonly kind: "not-select"; readonly why: string } | { readonly kind: "denied-table"; reado… (501 characters)
type OsqueryError =
  | { readonly kind: "not-select"; readonly why: string }
  | { readonly kind: "denied-table"; readonly table: string; readonly why: string }
  | { readonly kind: "unknown-table"; readonly table: string }
  | { readonly kind: "table-unavailable"; readonly table: string; readonly platform: Platform; readonly available: readonly Platform[] }
  | { readonly kind: "failed"; readonly code: number; readonly message: string }
  | { readonly kind: "bad-output"; readonly why: string };

Why a query was not run, or did not give rows.

OsqueryFailureclass
class OsqueryFailure extends Error

The error a driver rejects with, which carries the typed error.

MemberTypeWhat it is
errorOsqueryError
namestring
messagestring
stack?string
cause?unknown

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

OsqueryOptionsinterfaceno test imports it
interface OsqueryOptions

What the driver is told.

MemberTypeWhat it is
runRunRuns osqueryi.
schemaOsquerySchemaThe published schema, which says which table exists where and how a column is typed.
platformPlatformThe platform of the machine osquery runs on.
program?readonly string[]The program, osqueryi where not given (a path, or ssh host osqueryi as a prefix).
deny?readonly string[]Tables that are never run, besides those osquery has for their side effects.
osqueryDriverfunction
function osqueryDriver(options: OsqueryOptions): Driver

The driver of osquery: query runs a SELECT and gives its rows; exec is refused, always, since nothing is changed on the machine.

ParameterWhat it is
optionsthe program runner, the schema and the platform

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

osqueryQueryfunction
function osqueryQuery(options: OsqueryOptions, sql: string): Promise<Result<readonly Readonly<Record<string, string | number | null>>[], OsqueryError>>

Runs a SELECT on the machine through osqueryi --json.

ParameterWhat it is
optionsthe program runner, the schema and the platform
sqlthe statement

Returns: the rows with the types of the schema, or why not

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

osqueryTargetconst
const osqueryTarget: (id: string, options: OsqueryOptions) => MachineTarget

A machine as a target of a fan-out: osqueryDriver for it, with the platform it runs on.

ParameterWhat it is
idwhat the machine is called in results
optionshow to run osqueryi on it (the runner, usually ssh host as a prefix of the program), the schema and its platform

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

OsqueryRowtypeno test imports it
type OsqueryRow = Readonly<Record<string, string | number | null>>;

A row as osquery gives it, with the types of the schema where it knows them.

Raninterface
interface Ran

What a program run gave.

MemberTypeWhat it is
codenumber
stdoutstring
stderrstring

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

Runtypeno test imports it
type Run = (argv: readonly string[]) => Promise<Ran>;

Runs a program by its argument vector.

selectOnlyfunction
function selectOnly(sql: string): Result<string, OsqueryError>

Whether a statement may be run: one statement that only reads, as the guard of the SQL language library judges it with the SQLite parser (0058-sql-osquery FR-004).

ParameterWhat it is
sqlthe statement

Returns: the statement as it is to be run, or why it is refused

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

SIDE_EFFECT_TABLESconst
const SIDE_EFFECT_TABLES: readonly string[]

The tables that act on the world and not only report it: they fetch from the network or carve files.

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

tablesReadfunction
function tablesRead(sql: string): readonly string[]

The names of the tables a statement reads, in lower case and the order first read, found in its tree (a name in a string or a comment is none); none for a text that does not read.

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

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