IF Commons GitHub

logical/planning

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0004-findings-lifecycle FR-001, 0004-findings-lifecycle FR-002, 0004-findings-lifecycle FR-003, 0004-findings-lifecycle FR-004

A finding is an item of Planning (commons planning 0037-planning), of its item kind finding: its life is the events of that item and its state is the fold of them, which is Planning's and not ours. What this file says is only how a finding and what is done with it are put in Planning's words, and how the state of an item is read back in the words of a security review. A finding is opened with origin derived (read from a report, so open at once); a person triages it (a label and the reason as a comment; a false positive or a duplicate is closed not-planned or duplicate); accepts the risk until a day (the item is deferred until that day, and open again once it has passed); claims it fixed (a label and a comment, which counts until a retest settles it); and a retest closes it completed or reopens it. No kind of item, event or term is added to Planning's: everything here is labels, comments and the events Planning has.

Every event Planning makes has an actor, and an agent has the person it acts for: the importer is a tool, run by the person who ran it where one is said, and a person's triage is the person's own.

import { openedOf } from "./planning.ts";
openedOf({ id: "a1", rule: "r", title: "t", severity: "high", asset: "portal", description: "d", cwe: [], cve: [], source: { tool: "zap", file: "z.json" } }).kind; // "finding"

Source: commons/findings/src/logical/planning.ts

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

logical.STATUSESconstno test imports it
const STATUSES: readonly ["open", "confirmed", "false-positive", "duplicate", "accepted", "fixed", "verified", "reopened"]

The states of a finding in the words of a security review.

logical.Statustypeno test imports it
type Status = (typeof STATUSES)[number];

A state.

logical.OPEN_STATUSESconstno test imports it
const OPEN_STATUSES: readonly ("accepted" | "confirmed" | "duplicate" | "false-positive" | "fixed" | "open" | "reopened" | "verified")[]

The states in which a finding still counts against the system.

logical.FINGERPRINT_SOURCEconstno test imports it
const FINGERPRINT_SOURCE: "opsfolio-findings"

The source name of the external id a finding carries: its fingerprint.

logical.LABELconstno test imports it
const LABEL: { readonly confirmed: "triage:confirmed"; readonly falsePositive: "triage:false-positive"; readonly accepted: "risk-accepted"; readonly fixClaimed: "fix-claimed"; readonly reopened: "reopened"; }

The labels the lifecycle uses.

logical.openedOffunctionno test imports it
function openedOf(f: Finding): OpenedData

The opening of the item of a finding: kind finding, origin derived, the report's severity kept as the source wrote it, and the facts that make it the same finding in the next report as the labels and the source.

logical.Viewtypeno test imports it
type View = { readonly id: string; readonly fingerprint: string; readonly title: string; readonly severity: Seve… (414 characters)
type View = {
  readonly id: string;
  readonly fingerprint: string;
  readonly title: string;
  readonly severity: Severity;
  readonly asset: string;
  readonly location?: string;
  readonly tool: string;
  readonly rule: string;
  readonly cwe: readonly string[];
  readonly cve: readonly string[];
  readonly status: Status;
  readonly reason?: string;
  readonly until?: string;
  readonly lapsed: boolean;
};

A finding as read back from its item.

logical.statusOffunctionno test imports it
function statusOf(item: Item, now: string): { readonly status: "accepted" | "confirmed" | "duplicate" | "false-positive" | "fixed" | "open" | "reopened" | "verified"; readonly lapsed: boolean; readonly until?: string | undefined; readonly reason?: string | undefined; }

The state of a finding in the words of a security review, from its item at an instant: closed completed is verified, not-planned a false positive, duplicate a duplicate; deferred with the label of an accepted risk is accepted until its day and open again after; otherwise a claimed fix is fixed, a reopening reopened, a triage confirmed, and else open.

logical.viewOffunctionno test imports it
function viewOf(item: Item, now: string): View

The finding an item is, in the words of a security review.

logical.Actiontypeno test imports it
type Action = | { readonly kind: "triage"; readonly as: "confirmed" | "false-positive" | "duplicate"; readonly reason:… (456 characters)
type Action =
  | { readonly kind: "triage"; readonly as: "confirmed" | "false-positive" | "duplicate"; readonly reason: string; readonly duplicateOf?: string }
  | { readonly kind: "accept"; readonly reason: string; readonly until: string }
  | { readonly kind: "fix"; readonly ref?: string }
  | { readonly kind: "retest"; readonly result: "still-present" | "not-found"; readonly source: string }
  | { readonly kind: "reopen"; readonly reason: string };

What a person (or the tool run for one) does to a finding.

logical.eventsOffunctionno test imports it
function eventsOf(a: Action): Result<readonly EventData[], string>

The events of Planning an action is: comments for the reasons, labels for the review's states, and the closing, deferring and reopening Planning has. The caller adds a same-as link to the finding a duplicate repeats.

logical.problemsOffunctionno test imports it
function problemsOf(a: Action, view: View | undefined, by: string, at: string, now: string): readonly string[]

Why an action may not be done to a finding in the state it is in, every reason, or none. by is who does it.

logical.retestsOffunctionno test imports it
function retestsOf(views: readonly View[], incoming: ReadonlySet<string>, source: string): readonly { readonly view: View; readonly action: Action; }[]

The retests a new report gives: for each finding claimed fixed, still-present where the report has its fingerprint and not-found where it does not, and for no other: a report is not a complete picture, and a finding absent from it is not thereby fixed.

STATUSESconstno test imports it
const STATUSES: readonly ["open", "confirmed", "false-positive", "duplicate", "accepted", "fixed", "verified", "reopened"]

The states of a finding in the words of a security review.

Statustypeno test imports it
type Status = (typeof STATUSES)[number];

A state.

OPEN_STATUSESconst
const OPEN_STATUSES: readonly ("accepted" | "confirmed" | "duplicate" | "false-positive" | "fixed" | "open" | "reopened" | "verified")[]

The states in which a finding still counts against the system.

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

FINGERPRINT_SOURCEconst
const FINGERPRINT_SOURCE: "opsfolio-findings"

The source name of the external id a finding carries: its fingerprint.

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

LABELconst
const LABEL: { readonly confirmed: "triage:confirmed"; readonly falsePositive: "triage:false-positive"; readonly accepted: "risk-accepted"; readonly fixClaimed: "fix-claimed"; readonly reopened: "reopened"; }

The labels the lifecycle uses.

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

openedOffunction
function openedOf(f: Finding): OpenedData

The opening of the item of a finding: kind finding, origin derived, the report's severity kept as the source wrote it, and the facts that make it the same finding in the next report as the labels and the source.

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

Viewtypeno test imports it
type View = { readonly id: string; readonly fingerprint: string; readonly title: string; readonly severity: Seve… (414 characters)
type View = {
  readonly id: string;
  readonly fingerprint: string;
  readonly title: string;
  readonly severity: Severity;
  readonly asset: string;
  readonly location?: string;
  readonly tool: string;
  readonly rule: string;
  readonly cwe: readonly string[];
  readonly cve: readonly string[];
  readonly status: Status;
  readonly reason?: string;
  readonly until?: string;
  readonly lapsed: boolean;
};

A finding as read back from its item.

statusOffunction
function statusOf(item: Item, now: string): { readonly status: "accepted" | "confirmed" | "duplicate" | "false-positive" | "fixed" | "open" | "reopened" | "verified"; readonly lapsed: boolean; readonly until?: string | undefined; readonly reason?: string | undefined; }

The state of a finding in the words of a security review, from its item at an instant: closed completed is verified, not-planned a false positive, duplicate a duplicate; deferred with the label of an accepted risk is accepted until its day and open again after; otherwise a claimed fix is fixed, a reopening reopened, a triage confirmed, and else open.

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

viewOffunction
function viewOf(item: Item, now: string): View

The finding an item is, in the words of a security review.

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

Actiontype
type Action = | { readonly kind: "triage"; readonly as: "confirmed" | "false-positive" | "duplicate"; readonly reason:… (456 characters)
type Action =
  | { readonly kind: "triage"; readonly as: "confirmed" | "false-positive" | "duplicate"; readonly reason: string; readonly duplicateOf?: string }
  | { readonly kind: "accept"; readonly reason: string; readonly until: string }
  | { readonly kind: "fix"; readonly ref?: string }
  | { readonly kind: "retest"; readonly result: "still-present" | "not-found"; readonly source: string }
  | { readonly kind: "reopen"; readonly reason: string };

What a person (or the tool run for one) does to a finding.

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

eventsOffunction
function eventsOf(a: Action): Result<readonly EventData[], string>

The events of Planning an action is: comments for the reasons, labels for the review's states, and the closing, deferring and reopening Planning has. The caller adds a same-as link to the finding a duplicate repeats.

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

problemsOffunction
function problemsOf(a: Action, view: View | undefined, by: string, at: string, now: string): readonly string[]

Why an action may not be done to a finding in the state it is in, every reason, or none. by is who does it.

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

retestsOffunction
function retestsOf(views: readonly View[], incoming: ReadonlySet<string>, source: string): readonly { readonly view: View; readonly action: Action; }[]

The retests a new report gives: for each finding claimed fixed, still-present where the report has its fingerprint and not-found where it does not, and for no other: a report is not a complete picture, and a finding absent from it is not thereby fixed.

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

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