IF Commons GitHub

physical/run

Written to: 5 requirements: 5 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-scanners-run FR-001, 0004-scanners-run FR-002, 0004-scanners-run FR-003, 0004-scanners-run FR-004, 0004-scanners-run FR-005

Running a scanner, the safe way. In this order, and stopping at the first that fails: the scanner and the target are known and the target fit to be given to a tool; the engagement allows the technique on the asset (the caller's authorize, which is Opsfolio's pentest authorize); the tool has a pin and the file at its path has the pinned SHA-256; then the tool is run with an argument vector (no shell), in an empty folder, with a bare environment and a time limit. What it prints is read into findings, which are about the estate's asset. Every run, refused or made, gives a record of who it was for, what was run, with which binary and what came of it. Nothing here installs or fetches a tool.

import { runScanner } from "./run.ts";
// await runScanner({ scanner: "nuclei", asset: "portal", target, authorize, pins, now }) // { kind: "ok", value: { record, findings, problems } }

Source: commons/scanners/src/physical/run.ts

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

physical.Authorizetypeno test imports it
type Authorize = (asset: string, technique: string) => { readonly allowed: boolean; readonly reason: string };

The engagement's answer to one action.

physical.RunInputtypeno test imports it
type RunInput = { readonly scanner: string; /** The asset of the estate the scan is about: what its findings are abo… (541 characters)
type RunInput = {
  readonly scanner: string;
  /** The asset of the estate the scan is about: what its findings are about, and what the engagement's scope is asked. */
  readonly asset: string;
  readonly target: Target;
  readonly authorize: Authorize;
  readonly pins: Pins;
  readonly now: string;
  readonly rate?: number;
  readonly ports?: string;
  readonly timeoutMs?: number;
  /** The built-in check's contact with the target (the real one by default). */
  readonly probe?: (url: string, timeoutMs: number) => Promise<Probed>;
};

What a run is given.

physical.RunRecordtypeno test imports it
type RunRecord = {
  readonly scanner: string;
  readonly asset: string;
  readonly target: string;
  readonly technique: string;
  readonly startedAt: string;
  readonly tookMs: number;
  readonly tool?: { readonly name: string; readonly version: string; readonly sha256: string };
  readonly exit: number | null;
  readonly findings: number;
  readonly refused?: string;
};

The record of a run, refused or made.

physical.RunResulttypeno test imports it
type RunResult = { readonly record: RunRecord; readonly findings: readonly RawFinding[]; readonly problems: readonly string[] };

What a run gave.

physical.RunRefusaltypeno test imports it
type RunRefusal = { readonly reason: string; readonly record: RunRecord };

A run that was refused or failed: why, and the record.

physical.runScannerfunctionno test imports it
function runScanner(i: RunInput): Promise<Result<RunResult, RunRefusal>>

Runs a scanner against a target of the estate.

Authorizetype
type Authorize = (asset: string, technique: string) => { readonly allowed: boolean; readonly reason: string };

The engagement's answer to one action.

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

RunInputtype
type RunInput = { readonly scanner: string; /** The asset of the estate the scan is about: what its findings are abo… (541 characters)
type RunInput = {
  readonly scanner: string;
  /** The asset of the estate the scan is about: what its findings are about, and what the engagement's scope is asked. */
  readonly asset: string;
  readonly target: Target;
  readonly authorize: Authorize;
  readonly pins: Pins;
  readonly now: string;
  readonly rate?: number;
  readonly ports?: string;
  readonly timeoutMs?: number;
  /** The built-in check's contact with the target (the real one by default). */
  readonly probe?: (url: string, timeoutMs: number) => Promise<Probed>;
};

What a run is given.

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

RunRecordtypeno test imports it
type RunRecord = {
  readonly scanner: string;
  readonly asset: string;
  readonly target: string;
  readonly technique: string;
  readonly startedAt: string;
  readonly tookMs: number;
  readonly tool?: { readonly name: string; readonly version: string; readonly sha256: string };
  readonly exit: number | null;
  readonly findings: number;
  readonly refused?: string;
};

The record of a run, refused or made.

RunResulttypeno test imports it
type RunResult = { readonly record: RunRecord; readonly findings: readonly RawFinding[]; readonly problems: readonly string[] };

What a run gave.

RunRefusaltypeno test imports it
type RunRefusal = { readonly reason: string; readonly record: RunRecord };

A run that was refused or failed: why, and the record.

runScannerfunction
function runScanner(i: RunInput): Promise<Result<RunResult, RunRefusal>>

Runs a scanner against a target of the estate.

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

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