IF Commons GitHub

governance/model

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-findings-model FR-001, 0002-findings-model FR-002, 0002-findings-model FR-003

What a finding is, whichever tool found it: a rule, a title, a severity, the asset it is about and where on it, a description, a way to fix it, the weaknesses (CWE) and vulnerabilities (CVE) it names, a short redacted piece of evidence, and where it was read from. Its identity is the fingerprint of what makes it the same finding in the next report: the tool, the rule, the asset and the place (without its query), so that a retest recognizes it. The evidence is cut short and anything that looks like a credential in it is replaced, because a report holds what the tool saw, and the tool saw secrets.

import { SEVERITIES, redact } from "./model.ts";
SEVERITIES[0]; // "critical"
redact("Authorization: Bearer abc.def.ghi"); // "Authorization: [redacted]"

Source: commons/findings/src/governance/model.ts

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

governance.SEVERITIESconstno test imports it
const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"]

The severities, from the worst.

governance.Severitytypeno test imports it
type Severity = (typeof SEVERITIES)[number];

A severity.

governance.Sourcetypeno test imports it
type Source = { readonly tool: string; readonly version?: string; readonly file: string };

Where a finding was read from.

governance.RawFindingtypeno test imports it
type RawFinding = { readonly rule: string; readonly title: string; readonly severity: Severity; /** What it is a… (500 characters)
type RawFinding = {
  readonly rule: string;
  readonly title: string;
  readonly severity: Severity;
  /** What it is about, as the report names it: a host, a URL's origin, a repository. */
  readonly asset: string;
  /** Where on the asset: a path, a port, a file and line. */
  readonly location?: string;
  readonly description: string;
  readonly solution?: string;
  readonly cwe: readonly string[];
  readonly cve: readonly string[];
  readonly evidence?: string;
  readonly source: Source;
};

A finding as a reader gives it, before it has an identity.

governance.Findingtypeno test imports it
type Finding = RawFinding & { readonly id: string };

A finding.

governance.MAX_EVIDENCEconstno test imports it
const MAX_EVIDENCE: 500

The most characters of evidence kept.

governance.redactfunctionno test imports it
function redact(text: string): string

Evidence with what looks like a credential replaced and cut short: credentials in headers, assignments and long tokens.

governance.normalizeLocationfunctionno test imports it
function normalizeLocation(location: string | undefined): string

The place of a finding without what varies between runs: a URL without its query and fragment, a path as it is.

governance.fingerprintOffunctionno test imports it
function fingerprintOf(f: Pick<RawFinding, "asset" | "location" | "rule" | "source">): Promise<string>

The identity of a finding: the first 16 hexadecimal digits of the SHA-256 of the tool, the rule, the asset and the place.

governance.identifyfunctionno test imports it
function identify(raw: readonly RawFinding[]): Promise<{ readonly findings: readonly Finding[]; readonly repeats: number; }>

The findings with their identities. Two findings that make one identity are one: the first is kept and the count of the repeats is given.

governance.cweOffunctionno test imports it
function cweOf(text: string | number | undefined): string | undefined

A weakness identifier as CWE-79, from a number or a text that holds one; nothing where there is none (0 and -1 are what tools write for none).

governance.cvesInfunctionno test imports it
function cvesIn(text: string): readonly string[]

The vulnerability identifiers in a text, as CVE-2024-12345, without repeats.

SEVERITIESconst
const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"]

The severities, from the worst.

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

Severitytypeno test imports it
type Severity = (typeof SEVERITIES)[number];

A severity.

Sourcetypeno test imports it
type Source = { readonly tool: string; readonly version?: string; readonly file: string };

Where a finding was read from.

RawFindingtype
type RawFinding = { readonly rule: string; readonly title: string; readonly severity: Severity; /** What it is a… (500 characters)
type RawFinding = {
  readonly rule: string;
  readonly title: string;
  readonly severity: Severity;
  /** What it is about, as the report names it: a host, a URL's origin, a repository. */
  readonly asset: string;
  /** Where on the asset: a path, a port, a file and line. */
  readonly location?: string;
  readonly description: string;
  readonly solution?: string;
  readonly cwe: readonly string[];
  readonly cve: readonly string[];
  readonly evidence?: string;
  readonly source: Source;
};

A finding as a reader gives it, before it has an identity.

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

Findingtype
type Finding = RawFinding & { readonly id: string };

A finding.

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

MAX_EVIDENCEconst
const MAX_EVIDENCE: 500

The most characters of evidence kept.

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

redactfunction
function redact(text: string): string

Evidence with what looks like a credential replaced and cut short: credentials in headers, assignments and long tokens.

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

normalizeLocationfunction
function normalizeLocation(location: string | undefined): string

The place of a finding without what varies between runs: a URL without its query and fragment, a path as it is.

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

fingerprintOffunction
function fingerprintOf(f: Pick<RawFinding, "asset" | "location" | "rule" | "source">): Promise<string>

The identity of a finding: the first 16 hexadecimal digits of the SHA-256 of the tool, the rule, the asset and the place.

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

identifyfunction
function identify(raw: readonly RawFinding[]): Promise<{ readonly findings: readonly Finding[]; readonly repeats: number; }>

The findings with their identities. Two findings that make one identity are one: the first is kept and the count of the repeats is given.

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

cweOffunction
function cweOf(text: string | number | undefined): string | undefined

A weakness identifier as CWE-79, from a number or a text that holds one; nothing where there is none (0 and -1 are what tools write for none).

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

cvesInfunction
function cvesIn(text: string): readonly string[]

The vulnerability identifiers in a text, as CVE-2024-12345, without repeats.

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

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