IRMA voor ontwikkelaars: recepten

Vier recepten. Bij elk staat welke ingang het gebruikt en wat er nog later komt. De begrippen achter de recepten staan in Begrippen.

SIEM of servicedesk: incidenten in IRMA

Via /agent/v1 (service-token). Je SIEM, monitoring of servicedesk levert incidenten aan in het register Incidenten, zonder dubbele meldingen.

Je hebt nodig: een service-token met de scope incidents:write (zie Snelstart).

1. Bepaal per melding de velden.

Veld	Uit je systeem	Tip
title	De naam van de regel of het ticket.	Kort en herkenbaar; de eerste melding blijft de titel.
description	Wat er gebeurde.	Op metaniveau: soort storing, systeem, tijdstip. Geen persoonsgegevens of inhoud van dossiers.
severity	De ernst uit je systeem.	Vertaal naar laag, middel, hoog of kritiek.
source	kind + name + reference.	reference = de link naar je alarm of ticket, zodat je in IRMA terug kunt klikken.
fingerprint	Regel + object.	Bijvoorbeeld siem-rule-4711:fw-01. Zonder tijdstip.
occurredAt	Tijdstip van de melding.	ISO 8601 met tijdzone.

Optioneel: impact, remediation (wat er al gedaan is), resolvedAt, links naar een asset, leverancier, informatiesysteem of risico dat al in IRMA staat ({ "entityType": "asset", "entityId": "<uuid>" }), en metadata (vrije JSON, maximaal 8 KB).

2. Waarom de fingerprint ertoe doet. IRMA herkent een incident aan de fingerprint binnen je organisatie. Komt dezelfde fingerprint terug, dan maakt IRMA geen nieuw incident: het aantal keer gaat omhoog, de laatste melding schuift op en de ernst gaat mee omhoog als de nieuwe melding ernstiger is (nooit omlaag). Titel en beschrijving van de eerste melding blijven staan. Je register toont zo één helder incident in plaats van honderd alarmen.

3. Lever aan en reageer op de uitkomst. Een voorbeeld voor een webhook of cronjob met de CLI:

#!/usr/bin/env bash
# Draai per alarm. RULE en OBJECT komen uit je SIEM.
irma incident create --json --no-dry-run --yes \
  --title "$TITLE" --severity "$SEVERITY" --description "$DESCRIPTION" \
  --source-kind agent --source-name siem --source-ref "$ALERT_URL" \
  --fingerprint "$RULE:$OBJECT" > /tmp/irma-incident.json
case $? in
  0) ;;                                    # aangemaakt of opgeteld bij een bestaand incident
  2) echo "geweigerd of verkeerd ingesteld: herstel, niet herhalen" >&2; exit 2 ;;
  *) echo "onbekende uitkomst: probeer het bij het volgende alarm opnieuw" >&2 ;;
esac

Zonder CLI is het één POST https://api.irma.prudai.com/agent/v1/incidents; 201 is nieuw, 200 opgeteld. Herhaal een aanroep veilig met dezelfde fingerprint: dat wordt hooguit een extra telling.

4. Controleer. irma incident list --status nieuw (scope incidents:read) of kijk in IRMA onder Incidenten.

Twee simulaties vergelijken

Via /v1 (gebruikerstoken).

Je hebt twee Monte Carlo-runs, bijvoorbeeld van voor en na een nieuwe maatregel, en wilt weten wat er verschilt.

irma simulations list                       # runs, nieuwste eerst, met 'nog actueel?'
irma simulations compare <run-a> <run-b>

De vergelijking rekent niet opnieuw: hij legt de twee opgeslagen uitkomsten naast elkaar. Je krijgt de percentielen van A en B met het verschil, welke risico’s alleen in A of alleen in B meededen, welke risico’s het meest verschoven, en een korte uitleg. Kijk eerst naar sameSeed, sameIterations en sameScope: verschillen de seed, het aantal iteraties of de selectie, dan komt een deel van het verschil daar vandaan en niet uit je register.

Een nieuwe run met dezelfde seed maakt de uitkomst herhaalbaar:

irma simulations run --iterations 10000 --seed 42           # droogloop: toont welke risico's meedoen
irma simulations run --iterations 10000 --seed 42 --no-dry-run --yes

Risico’s zonder financiële raming doen niet mee; de droogloop en de envelop (completeness.excluded) tellen ze apart.

Wat veranderde er sinds de import

Via /v1 (gebruikerstoken).

Je hebt je risicoregister uit Excel geïmporteerd en wilt weten wat er sindsdien is veranderd: voor een directiebeoordeling of omdat een auditor ernaar vraagt.

irma risk-profile compare --from import
irma risk-profile compare --from 2026-07-01 --to 2026-10-01

Je krijgt de risico’s die erbij kwamen, die verdwenen en die veranderden, met per veld de oude en nieuwe waarde. --from import is het moment van de eerste risico-import; is er nooit geïmporteerd, dan krijg je 422. Een datum betekent het einde van die dag (UTC). Wil je weten wie een wijziging deed, vraag dan de historie van dat risico op:

irma risks history <risk-id>

Een audit voorbereiden met een agent

Deels later. Lezen werkt met /v1, ook de audit-checks; concepten terugschrijven in IRMA komt later.

De audit-checks zijn vaste regels over je register (heeft elke maatregel een eigenaar, bewijs dat aan de norm voldoet, staat er een afwijking open) per maatregel, risico, eis en organisatie, met een volledigheidsscore waarvan de formule en de gewichten in het antwoord staan. Ze lezen alleen en slaan niets op, en vragen volledige leestoegang:

irma audit summary                      # score, formule en telling per check (standaard iso27001-2022)
irma audit checks --outcome fout        # alleen wat faalt, per onderwerp

Een coding agent zoals Claude Code, met de IRMA-skill, kan een interne audit voorbereiden: hij verzamelt de stand van zaken en schrijft een voorstel dat een mens beoordeelt. Een opdracht kan zo luiden:

Bereid de interne audit ISO 27001 voor. Begin met `irma context --json`.
Haal de normdekking op met `irma compliance coverage <framework>` en de audit-checks met `irma audit summary` en `irma audit checks --outcome fout,waarschuwing`, en zet de open eisen op een rij.
Zoek bij elke open eis de bijbehorende risico's en hun historie.
Schrijf een voorbereidingsnotitie met per eis: status, wat ontbreekt, en welke aanroep je gebruikte.
Noem bij elk getal de herkomst (provenance) en zeg het als de leesscope beperkt is. Wijzig niets in IRMA.

Wat de agent doet, volgt de envelop: hij pagineert tot nextOffset leeg is, gebruikt notIncluded en next om door te vragen, en verzint geen cijfers die geen run of record opleverde. Het resultaat is een notitie voor de auditor of de CISO, geen wijziging in je registers. Zodra concepten via de API kunnen, zet de agent zijn voorstellen als concept klaar in IRMA.