Risk Assessment Ecosystem

User manual · Configurator v1.62 · Assessor v3.6.1 · June 2026

1 · The ecosystem

The ecosystem is two single-file HTML applications plus a library of JSON configuration files. Everything runs locally in your browser — no server, no install, no data leaves your machine unless you explicitly use an AI feature.

The Configurator is for the method owner: it defines what gets assessed (the risk map), what evidence is collected (scoping questions, vendor and internal surveys), what reduces risk (controls), and how numbers become ratings (matrix, bands, scoring options). The Assessor is for the person running an individual assessment: it loads a config and walks through an 8-step pipeline, computing live risk ratings as answers arrive.

2 · Quick start

1. Open Risk-assessor.html in a browser.
2. Drop a config file onto the landing screen — e.g. configs/full-AI-risk-assessment.json or any starter pack from configs/.
3. Fill in Metadata (project, organisation, assessor).
4. Answer the Scope questions. Risks tied to a "No" are scoped out.
5. Answer the Vendor and Internal surveys — these reduce the likelihood of well-managed risks.
6. Rate the Controls — these produce the residual position.
7. Review the Output heatmap; export Markdown / JSON / CSV or Print/PDF.

3 · Risk Configurator

Landing page (v1.58)

The configurator opens with four paths: 🧱 brand-new empty configuration (one placeholder family × one period, zero risks/questions/controls — build everything from scratch; matrix and scoring start from defaults), 🗂 start from the default register (the built-in 77-risk standard map), ↑ open an existing config file (the canvas behind the dialog starts empty, not the default register), or load a predefined template from the gallery of all bundled risk maps.

Templates load automatically with zero prompts, even from disk: a companion file configs/packs-bundle.js carries all 23 bundled configs and loads via a script tag, which browsers permit on file:// (unlike fetch). Over http the live JSON files are preferred, so edits show without rebuilding. After adding or editing a pack, refresh the bundle with node build-packs-bundle.js from the tests/ folder. ↺ Reset returns to the landing page.

ℹ Config descriptions (v1.58)

Every template card on the landing carries an ℹ button, and the in-app Configuration label has one too. Both open a floating window with the configuration's full details read from the JSON: label, version, risk/control/survey counts, narrative, the long-form description, families and periods. Esc or click-outside closes it. The description field survives load → Save Config round-trips.

Eight tabs, in the order you would normally work:

Top-bar tools

• ✨ Copilot — describe a use case; an LLM drafts a starter config (clearly labelled AI DRAFT) that you can load or download. Always run Validate and review before use.
• ✔ Validate — integrity checks: duplicate IDs, orphan references, risks without controls or surveys, risks no scope question can suppress, unlinked questions/controls, uniform appetites, and matrix label-vs-points contradictions. ERROR / WARN / INFO findings.
• Save Config — writes the full config including the resolved block the assessor reads.

4 · Risk Assessor

An 8-step pipeline. Steps turn green as their relevant questions are completed.

Landing screen (v3.4)

The assessor landing is assessment-only: load a config exported by the configurator (drop zone or file picker), resume a saved assessment, or restore an autosaved session. The bundled-config gallery lives on the configurator's landing page — pick a preconfigured risk map there, tailor it, Save Config, then load that file here.

Comparing two assessments (v3.2)

⇄ Compare session on the Output step loads a previously saved session file and shows per-risk residual deltas: improved, worsened, newly in scope, and dropped out — the basis for reassessment cycles and trend reporting. Risks are matched by ID; a warning appears if the sessions used different configs.

Keyboard answering (v3.2)

Tab or click onto a question/control card, then press Y (Yes), P (Partial), N (No), A (N/A) or D (Do not know — scope only). ↑/↓ move between cards, Enter/Space toggles a focused controls section, Esc closes modals. The step pipeline shows answer percentages, and the Controls step has Expand-all / Collapse-all.

Guided mode (v3.3)

Business-language coaching on every step: how to answer like an auditor, what weights mean, when to scope risks out, what the heatmap modes tell you. On by default for new users; dismiss tips individually (✕) or switch the layer off in Settings → Guided help. The configurator has the same layer behind the 💡 Tips topbar button, including a live hint in the risk editor showing which business impact band a score lands in.

What-if simulator (v3.3)

🧪 Simulate controls in the risk popup sandboxes the control answers for that risk — change them freely and watch the simulated residual move; nothing touches the assessment until you press Apply (or Discard / close the popup). 🧪 Opportunities on the Output step ranks the not-yet-implemented controls by the total residual-points reduction each would buy across its linked risks — a control-investment priority list.

Evidence assurance (v3.3)

Of the controls credited Yes/Partial, how many carry an evidence reference? The percentage appears on the Output step and per risk in the popup, with an "Evidence Assurance" section in the Markdown export (listing unevidenced credited controls), an assurance block in JSON, and an "Assurance %" column in CSV. Optional anti-gaming mode: set scoring.unevidencedYes to partial in the configurator's Scoring Options and an unevidenced Yes only earns Partial credit.

5 · How scoring works

The engine is a qualitative 5×5 model driven by one calculation pipeline. All scores live on two scales: risk scores 1–10 (configurator) and points 1–100 (assessor, = score × 10).

fullScore   = clamp( baseScore × (1 + strategyPct/100), 1, 10 )            ← configurator
tpra        = vendor security rating normalised to ×0.80 … ×1.20           ← optional
adjusted    = clamp( fullScore × tpra, 1, 10 )       (vendor-linked risks; axis is configurable)
impactPts   = adjusted × 10                                                 (1–100)

likeBase    = baseLikelihood × 10   if set per risk   — otherwise = impactPts
surveyScore = Σ answer points / Σ weights   over answered linked questions  (N/A excluded)
likelihoodPts = likeBase × (1 − surveyScore% × surveyMaxReduction)          default cap 60%

CURRENT     = matrix[ impactBand ][ likelihoodBand ]      → label + points

ctrlScore   = Σ answer points / Σ weights   over rated linked controls      (N/A excluded)
likelihood controls (effect ≠ Impact)  reduce likelihoodPts  up to controlMaxReduction (80%)
impact controls     (Impact or Both)   reduce impactPts      up to controlMaxReduction (80%)

RESIDUAL    = matrix lookup on the reduced points

Answer scoring

Control effects

6 · Heatmaps & view modes

The heatmap is a families × periods grid — each cell is one risk. Cell colour is the matrix rating of that risk in the selected mode. Click a cell for the full popup: three score cards, a calculation trace, band overrides, the treatment plan, and inline control answers.

The 5×5 matrix

Rows = impact band (Insignificant → Catastrophic), columns = likelihood band (Rare → Almost Certain). Each cell carries a label and a points value (1–100). The matrix is the scoring model — ratings come from direct cell lookup, so the calculator, heatmap and exports always agree. Two deliberate calibrations: Catastrophic × Rare = MEDIUM and Major × Rare = MEDIUM — tail risks never disappear into green.

7 · Risk appetite

Each risk carries an appetite (1 conservative … 9 aggressive), set per family in the shipped maps — e.g. Security/Agentic/Fail-Safe 3, Data/Governance 4, Business 6 in the AI map. A risk exceeds appetite when its residual points are above appetite × 10 and its residual rating is not LOW. Exceeding risks appear in the Exceeds Appetite view, a dedicated export table, and qualify for ✨ AI treatment suggestions.

8 · TPRA multiplier

A third-party security rating (BitSight, Panorays, UpGuard, or manual 1–10) is normalised to a multiplier between ×0.80 (excellent vendor) and ×1.20 (poor vendor) and applied to vendor-linked risks only — those with a vendor survey mapping. The config key scoring.tpraAffects selects the axis: impact (legacy) or likelihood (recommended — a vendor rating is evidence about how likely compromise is, not how big it would be). The assessor can override the multiplier per assessment.

9 · AI integration

Connection settings

Assessor: Settings → AI Connection. Configurator: inside the Copilot dialog. Two providers are supported: Anthropic (direct browser calls, default endpoint) and OpenAI-compatible (set the full chat-completions URL — note that some providers, including Azure OpenAI, block browser calls; use a proxy in that case).

10 · Config files & starter packs

All bundled packs live in configs/ and are available from the configurator's starter-pack gallery. Pick the closest pack, tailor scoring/appetite/wording, then use Save Config and load that file into the assessor. Periods are reused by domain: they may mean lifecycle stages, deal phases, maturity levels, migration waves or response stages.

11 · Schema reference (essentials)

12 · Data & storage

• Autosave — assessor sessions (riskAssessorAutosave) and configurator state (riskConfiguratorAutosave) in browser local storage, debounced 2 s. Security toggle (v3.5/v1.60): both top bars carry an Autosave ON/OFF button — OFF removes the existing autosave immediately and stops all background writes until you click Save yourself (hover the button for the explanation; with autosave off, unsaved work is lost if the tab closes or crashes). The preference persists per browser.
• 🧹 Clear storage (both top bars, icon button — hover for details) — one click wipes everything the Risk apps keep between sessions in this browser: both autosaved sessions, guided-help preferences, AI connection settings and the session API key. Files saved to disk are untouched. If autosave was OFF, that security preference survives the wipe.
• ⏏ Exit (both top bars) — returns to the launcher (index.html). If there is unsaved work it first asks whether to save; choosing not to save warns that changes are lost, noting whether autosave retains a copy.
• AI settings — riskAssessorAI / riskConfiguratorAI (localStorage) hold provider, endpoint and model. The API key is held separately in sessionStorage and is deleted when the tab or browser closes.
• Nothing else leaves the browser. Configs, sessions and exports are plain files you control. AI features are the only network calls, and only to the endpoint you configure.
• Session files embed the config, all answers, notes, evidence references, treatments, overrides, custom controls and the AI report — one file restores the entire assessment.

13 · Tests & versions

The tests/ folder contains a runnable regression suite (requires Node.js). Run everything with node run-all.js from the tests/ folder — it executes syntax_check.js, extract_scoring.js, regression.js (40 scoring assertions) and phase2_test.js (13 feature assertions) in order and exits non-zero on any failure. The suites refuse to run against a truncated or stale copy of the HTML apps (e.g. an unsynced cloud mirror) instead of producing misleading failures. Run them after any change to the scoring code or the shipped configs.