API & integration · v0.2

API & integration

There is deliberately no hosted TIR-CMM API. The assessment tool’s strongest property is that nothing you type ever leaves your machine, and that property is only credible if there is no server to send it to. Integrators get four layers instead — a JavaScript library, two JSON Schemas, a reference REST server you run yourself, and the machine-readable model — all of which keep assessment data inside the organisation that owns it.

Four ways to integrate

Four artefacts, in decreasing order of coupling. Pick the lowest-coupling one that does the job: the model data outlives any particular implementation of it, and an integration built against the schemas survives changes to the library that an integration built against internals does not.

Note the split. The model is CC BY-ND 4.0 and the tooling is source-available, but the schemas and the machine-readable model are deliberately CC BY 4.0 so that integration is frictionless. You do not need permission to build against them, and you do not owe a fee for doing so commercially. The licence page sets out the whole position.

JavaScript library

The library is the scoring engine and the model data, and nothing else. It carries no DOM code, no rendering and no storage, which is what lets the same file run in a browser tab, in Node, in a service worker or in a build step that generates a report.

• dist/tir-cmm.mjs — ES module. import { score } from './dist/tir-cmm.mjs'
• dist/tir-cmm.js — classic script. Load it with a <script> tag and the API appears on window.TIRCMM. It also detects CommonJS and AMD, so require() works.

Both are about 100 KB, built from the same flattened source, with no dependencies at all. There is no build step to adopt and no package to install: copy the file, or serve it from your own origin.

A worked example

Score a partial assessment, then take the leadership view, the findings and the sequenced plan off the same result object. Every call below is on the published surface.

import {
  score, resolveDetection, readiness, weaknesses, blueprint,
} from './dist/tir-cmm.mjs';

// 1. Sub-capability scores. One entry per sub-capability you assessed:
//      v  = maturity 0-5, or null for not applicable
//      ev = evidence level 0-3, which caps v under constraint R3
//    A blank evidence level is treated conservatively as level 0.
const scores = {
  'RP-1': { v: 3, ev: 2 },   // IR plan and scope
  'RP-3': { v: 2, ev: 2 },   // roles, rotas and 24/7 reachability
  'RA-1': { v: 2, ev: 2 },   // pre-authorised containment
  'RA-2': { v: 1, ev: 1 },   // decision latency (MTTDecide)
  'RE-1': { v: 3, ev: 1 },   // playbook coverage - capped to 2 by R3
  'CE-1': { v: 3, ev: 2 },   // tiered containment options
  'RV-1': { v: 1, ev: 1 },   // tabletop exercise programme
  // ... the remaining sub-capabilities in scope
};

// 2. The Containment Lattice: attack-path stage x asset class, keyed 'S3-A1'.
//      rrs  = Response Readiness Status 0-3
//      tier = criticality 1 (T3) to 3 (T1, a crown jewel)
const lattice = {
  'S3-A1': { inScope: true, rrs: 0, tier: 3 },   // priv-esc on identity: blind, T1
  'S3-A2': { inScope: true, rrs: 2, tier: 2 },
  'S4-A1': { inScope: true, rrs: 1, tier: 3 },
  'S7-A7': { inScope: true, rrs: 3, tier: 2 },   // impact on data/backup: proven
};

// 3. Decide where the detection figure for constraint R4 comes from, and what
//    band ceiling that source justifies. An imported TID-CMM score carries no
//    ceiling; the prerequisite check caps at L4; nothing at all caps at L3.
const detection = resolveDetection({ imported: 2.34 });

// 4. Score it.
const r = score(scores, {
  detection,
  lattice,
  tempo: { actor: 'TA-01', breakout: 62, mttd: 180, mttdecide: 95, mttc: 40 },
});

console.log(r.band.id, r.band.name);          // constraint-adjusted band
console.log(r.overall, r.selfOverall);        // adjusted vs self-assessed
console.log(r.caps.map(c => c.id));           // which constraints capped the band
console.log(r.lattice.vrsCj);                 // crown-jewel-weighted VRS
console.log(r.tempo.margin, r.tempo.ratio);   // Containment Margin, Tempo Ratio

// 5. The three leadership lenses, re-cutting the same sub-capabilities.
//    The rehearsal ceiling applies here too: no lens may exceed RV + 1.
const lenses = readiness(r.effSubs, r.domains.RV);
for (const l of lenses) console.log(l.name, l.proven, l.verdict.label);

// 6. What is actually holding you back, and what to do about it.
const findings = weaknesses(r);
for (const w of findings) console.log(w.severity, w.title, w.fix);

const plan = blueprint(r, 6);   // up to 6 items per horizon bucket
for (const b of plan) console.log(b.name, b.window, b.total, b.items);

The example scores a handful of sub-capabilities for brevity. A real assessment supplies every sub-capability in scope — 58 at Baseline and Assurance, 20 at Pulse — and the full in-scope lattice. Sub-capabilities left out are treated as not assessed, not as zero.

The public surface

Forty-five exports: thirty data structures and fifteen functions. This is the whole contract. Anything not in the list below is an implementation detail and may change between versions without a major version bump — including internals you can reach from a bundled build. If something you need is missing from the published surface, say so rather than reaching past it.

Data exports

The model as data. All of it is also available, in language-neutral form, in the machine-readable model.

Functions

score(scores, opts) in detail

The first argument is an object keyed by sub-capability ID, each value { v, ev } where v is the 0–5 maturity score or null for not applicable, and ev is the evidence level 0–3. The second argument is options.

score() returns a single object:

• overall and selfOverall — the constraint-adjusted score and the score before any constraint was applied. The gap between them is the part of the capability that is currently assumed rather than demonstrated.
• domains, rawDomains and preConstraint — adjusted, self-assessed, and the post-R3 baseline used for reporting each constraint’s independent effect.
• band and caps — the final band object, and every ceiling that was applied to it with its constraint ID and reason.
• adjustments and r3Hits — per-constraint detail, separating marginal from independent effects, plus every sub-capability the evidence cap actually lowered.
• lattice — vrs, vrsCj, engineered, proven, cell count, and the blind Tier-1 and Tier-2 cells.
• tempo — the resolved tempo object with margin and ratio, or null if tempo evidence was not supplied.
• detection, detectionScore — what R4 used and where it came from.
• roadmap — capability and lattice gaps merged and ranked by normalised impact.
• effSubs — the R3-adjusted sub-capability scores, which is what you pass to readiness().

JSON Schemas

Two contracts, both JSON Schema draft 2020-12, both licensed CC BY 4.0. That is deliberate and it is the whole point: integration should be frictionless, so you may build against them freely, including in commercial products, with attribution and without asking.

The field that carries the most weight

detection_score_pre_substitution supplies D for constraint R4, which caps the response-execution, containment and forensics domains at D + 1: you cannot respond to what you never saw.

It is deliberately the pre-substitution figure. Once a TIR-CMM assessment exists, TID-CMM substitutes the TIR-CMM overall into its own incident-response domain. If TIR-CMM then read the post-substitution TID-CMM score, the response score would be feeding the constraint that governs it, and both numbers would inflate each other quietly and indefinitely. Reading the pre-substitution figure breaks that loop. The ordering is stated in both specifications, and an integration that supplies the wrong figure will produce a result that looks better than it is.

Self-hosted REST server

A minimal HTTP wrapper around the library, provided so that platforms which need REST can have it without assessment data leaving the organisation that owns it. You run it, inside your own boundary, so the data never reaches anyone else. That is the only form of TIR-CMM REST there is, and the only form there is going to be.

• Zero dependencies. Node’s own http, fs, url and path modules, nothing else. No install step.
• Node 18 or later, for top-level await and native ES module import.
• No storage. Nothing is written to disk and nothing is logged beyond the startup line. Every response is sent with cache-control: no-store and an x-tir-cmm-version header.
• Request bodies are capped at 2 MB.

node server/server.mjs --port 8787

TIR-CMM reference server v0.2 on http://localhost:8787
Assessment data stays in this process. Nothing is sent anywhere.

The port may also be set with the PORT environment variable; it defaults to 8787.

Endpoints

Scoring a request

Both POST endpoints take the same body. Every key is optional: scores, lattice, tempo, telemetry, scenarios, governance, prereq, detectionScore, tier, and organisation for /report. The server resolves detection, looks up the tier, scores governance, assembles the R7 ceilings and calls the library exactly as the assessment tool does.

curl -s http://localhost:8787/score \
  -H 'content-type: application/json' \
  -d '{
    "tier": "baseline",
    "organisation": "Meridian Group",
    "detectionScore": 2.34,
    "scores": {
      "RP-1": { "v": 3, "ev": 2 },
      "RA-1": { "v": 2, "ev": 2 },
      "RA-2": { "v": 1, "ev": 1 },
      "RE-1": { "v": 3, "ev": 1 },
      "CE-1": { "v": 3, "ev": 2 },
      "RV-1": { "v": 1, "ev": 1 }
    },
    "lattice": {
      "S3-A1": { "inScope": true, "rrs": 0, "tier": 3 },
      "S4-A1": { "inScope": true, "rrs": 1, "tier": 3 },
      "S7-A7": { "inScope": true, "rrs": 3, "tier": 2 }
    },
    "tempo": { "actor": "TA-01", "breakout": 62,
               "mttd": 180, "mttdecide": 95, "mttc": 40 }
  }'

The response is the export payload. Abbreviated, and using the specification’s worked example rather than the shortened body above:

{
  "schema": "tir-cmm/export/0.2",
  "model_version": "0.2",
  "tier": "baseline",
  "overall": 2.32,
  "self_assessed": 2.69,
  "band": "L1",
  "band_name": "Documented",
  "band_capped_by": ["R5", "R6"],
  "domains": { "RP": 2.80, "RA": 1.90, "RE": 2.40, "CE": 2.50,
               "AO": 2.20, "FI": 2.00, "RV": 1.60, "RG": 2.30 },
  "detection_score": 2.34,
  "detection_source": "tid-cmm",
  "readiness": {
    "respond": { "proven": 2.10, "claimed": 2.44, "verdict": "Partial" }
  },
  "vrs_cj": 0.41,
  "engineered_rate": 0.406,
  "proven_rate": 0.031,
  "blind_cells_t1t2": [ { "stage": "S3", "asset_class": "A1", "tier": "T1" } ],
  "tempo": [ { "actor": "TA-01", "breakout_min": 62,
               "mttd_min": 180, "mttdecide_min": 95, "mttc_min": 40,
               "containment_margin_min": -253, "tempo_ratio": 5.08 } ],
  "constraint_adjustments": [ { "constraint": "R1", "domains": ["RP","CE","AO"] } ]
}

Machine-readable model

The whole model as data, in two formats with identical content: data/tir-cmm-model.json for programs, and data/tir-cmm-model.yaml for humans, diffs and review. Licensed CC BY 4.0.

It carries:

• the eight domains with weights, the question each one answers, and their 58 sub-capabilities — each with its weight, its level-3 anchor, the evidence it expects, and its improvement action with effort, type, owner, the act and the outcome;
• the eight attack-path stages and eight asset classes that form the Containment Lattice, plus the Response Readiness Status scale and the three criticality tiers;
• the seven integrity constraints, the six maturity bands, the four evidence levels and the evidence cap table;
• the three assessment tiers with their ceilings, the Pulse subset, the telemetry attributes, the prerequisite check, the three readiness lenses and the three horizons;
• the twelve scenarios with their lifecycle stages and pass conditions, the governance checks, the calibration questions and the anti-gaming rules;
• the crosswalk to NIST CSF 2.0, SP 800-61r3, ISO/IEC 27035, RE&CT, D3FEND, SOC-CMM and the regulatory regimes;
• and the licence block, so the terms travel with the data.

This is the best artefact to cite. If you are building documentation, a GRC mapping, a training course or an AI system that needs to answer questions about TIR-CMM accurately, read this file rather than scraping the pages: it is generated from the same source the tool runs on, so it cannot drift from the model, and it carries the version and licence in the payload. The site also publishes llms.txt and llms-full.txt for the same reason.

Versioning and stability

• The export schema tag is tir-cmm/export/0.2. It is a const in the schema, so a payload carrying any other tag is invalid against it rather than merely unfamiliar.
• The model version travels in every payload, in model_version, in the machine-readable model, in the library as MODEL_VERSION and in the server’s x-tir-cmm-version response header. Record it alongside any result you store; a score without its model version cannot be compared with anything later.
• Breaking changes bump the schema tag. A change to the meaning of a field, the removal of a field, or a change to how a constraint is applied all count as breaking. Additive fields do not: both schemas set additionalProperties: true, so a consumer that ignores unknown keys will keep working.
• The published API list is the contract. Anything outside it — internal helpers reachable in a bundled build, the exact shape of intermediate objects, the wording of a generated narrative — may change without a major bump.
• TIR-CMM is at v0.2, a draft for review. Several design questions are deliberately open. Expect the model to change before v1.0, and pin the version you built against.

Attribution

If your product integrates TIR-CMM, credit it, name the version, and link to the canonical source. A reasonable citation is:

TIR-CMM v0.2 - Threat-Informed Response Capability Maturity Model,
Reza Adineh, https://tir-cmm.com

In a user interface, a line such as “Maturity scoring based on TIR-CMM v0.2 (CC BY-ND 4.0) — tir-cmm.com” near the result satisfies it. In a machine-readable output, carry model_version and the schema tag, which you get for free by emitting a conforming payload.

Two things attribution does not license, and both are on the licence page in full: you may not publish a modified, rebranded or “extended” version of the model, and you may not redistribute the tooling as your own product. You may build whatever you like against the schemas and the machine-readable model, run the reference server, self-host the tool inside your organisation, assess clients commercially, and publish the results — those are yours.