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 itinterface 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.
| Member | Type | What it is |
|---|
id | string | |
platform | Platform | |
driver | Driver | |
OsqueryErrortypeno test imports ittype 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.
class OsqueryFailure extends Error
The error a driver rejects with, which carries the typed error.
| Member | Type | What it is |
|---|
error | OsqueryError | |
name | string | |
message | string | |
stack? | string | |
cause? | unknown | |
Imported by 7 tests of the run (7 passed, 0 failed): the library's results
OsqueryOptionsinterfaceno test imports itinterface OsqueryOptions
What the driver is told.
| Member | Type | What it is |
|---|
run | Run | Runs osqueryi. |
schema | OsquerySchema | The published schema, which says which table exists where and how a column is typed. |
platform | Platform | The 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. |
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.
| Parameter | What it is |
|---|
options | the program runner, the schema and the platform |
Imported by 7 tests of the run (7 passed, 0 failed): the library's results
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.
| Parameter | What it is |
|---|
options | the program runner, the schema and the platform |
sql | the 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
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.
| Parameter | What it is |
|---|
id | what the machine is called in results |
options | how 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 ittype OsqueryRow = Readonly<Record<string, string | number | null>>;
A row as osquery gives it, with the types of the schema where it knows them.
interface Ran
What a program run gave.
| Member | Type | What it is |
|---|
code | number | |
stdout | string | |
stderr | string | |
Imported by 14 tests of the run (14 passed, 0 failed): the library's results
Runtypeno test imports ittype Run = (argv: readonly string[]) => Promise<Ran>;
Runs a program by its argument vector.
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).
| Parameter | What it is |
|---|
sql | the 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
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
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