IF Commons GitHub

governance/engagement

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-pentest-engagement FR-002, 0002-pentest-engagement FR-003, 0002-pentest-engagement FR-004

An engagement: the written permission for a security test, as data. It says who authorized it and in what role, the window in which the test may reach its targets, the scope as a question asked of the estate (one statement of SQL that selects the assets, with another for what is left out), the techniques allowed, who tests, who to call, and how to stop. An engagement is refused unless all of it is said: a test without a window, without a scope, without a way to stop it or with a technique that is never granted is not one.

Whether an engagement is in force is not in it: that is the signature of the commit that holds it (commons change-control) and the clock (authorize.ts).

import { defineEngagement } from "./engagement.ts";
defineEngagement({ id: "q4-external", name: "Q4 external test" } as never).kind; // "err"

Source: commons/pentest/src/governance/engagement.ts

4 of 10 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.Contacttypeno test imports it
type Contact = { readonly name: string; readonly role: string; readonly how: string };

A person to call.

governance.EngagementInputtypeno test imports it
type EngagementInput = { readonly id: string; readonly name: string; /** Who authorized the test, in what role, an… (1176 characters)
type EngagementInput = {
  readonly id: string;
  readonly name: string;
  /** Who authorized the test, in what role, and on which day (YYYY-MM-DD). */
  readonly authorizedBy: { readonly name: string; readonly role: string; readonly on: string };
  /** The instants between which the test may reach its targets (ISO 8601). */
  readonly window: { readonly from: string; readonly to: string };
  /** The scope as questions asked of the estate: a statement of SQL that selects a column named `asset`, and one for what is left out. */
  readonly scope: { readonly include: string; readonly exclude?: string };
  /** The techniques allowed, besides `passive`, which is always. */
  readonly techniques: readonly string[];
  /** Who approves the use of an exploit, and why: required where `exploit` is allowed, and not the person who authorized the test. */
  readonly exploit?: { readonly approvedBy: string; readonly reason: string };
  readonly testers: readonly string[];
  readonly contacts: readonly Contact[];
  /** How to stop the test at once: who to tell and how. */
  readonly stop: string;
  /** The ticket or contract that asked for it. */
  readonly ref?: string;
};

What an engagement is made from.

governance.Engagementtypeno test imports it
type Engagement = EngagementInput & { readonly techniques: readonly string[] };

An engagement.

governance.MAX_WINDOW_DAYSconstno test imports it
const MAX_WINDOW_DAYS: 90

The longest window an engagement may have: a test that has no end is not authorized.

governance.defineEngagementfunctionno test imports it
function defineEngagement(input: EngagementInput): Result<Engagement, readonly string[]>

An engagement from its input, or every reason it is refused.

Contacttypeno test imports it
type Contact = { readonly name: string; readonly role: string; readonly how: string };

A person to call.

EngagementInputtype
type EngagementInput = { readonly id: string; readonly name: string; /** Who authorized the test, in what role, an… (1176 characters)
type EngagementInput = {
  readonly id: string;
  readonly name: string;
  /** Who authorized the test, in what role, and on which day (YYYY-MM-DD). */
  readonly authorizedBy: { readonly name: string; readonly role: string; readonly on: string };
  /** The instants between which the test may reach its targets (ISO 8601). */
  readonly window: { readonly from: string; readonly to: string };
  /** The scope as questions asked of the estate: a statement of SQL that selects a column named `asset`, and one for what is left out. */
  readonly scope: { readonly include: string; readonly exclude?: string };
  /** The techniques allowed, besides `passive`, which is always. */
  readonly techniques: readonly string[];
  /** Who approves the use of an exploit, and why: required where `exploit` is allowed, and not the person who authorized the test. */
  readonly exploit?: { readonly approvedBy: string; readonly reason: string };
  readonly testers: readonly string[];
  readonly contacts: readonly Contact[];
  /** How to stop the test at once: who to tell and how. */
  readonly stop: string;
  /** The ticket or contract that asked for it. */
  readonly ref?: string;
};

What an engagement is made from.

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

Engagementtype
type Engagement = EngagementInput & { readonly techniques: readonly string[] };

An engagement.

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

MAX_WINDOW_DAYSconst
const MAX_WINDOW_DAYS: 90

The longest window an engagement may have: a test that has no end is not authorized.

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

defineEngagementfunction
function defineEngagement(input: EngagementInput): Result<Engagement, readonly string[]>

An engagement from its input, or every reason it is refused.

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

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