Keen documentation
Open Keen ↗

Developing Keen

Risk and ISMS data models

Chapter 6 of 6

Risk register, library and Keen Assurance Framework

Risks, documents, people, assets and SWOT items are ordinary application records with their own services, access rules and version checks. This chapter names the module that owns each one.

api/routes/risks.py handles scenarios and control links; api/routes/risk_register.py adds register views, ratings, thresholds, CSV exchange and reusable templates. Risk is the shared scenario entity: the editor, register and heatmap use the same inherent and residual likelihood and impact fields, each constrained to 1-5, with scores calculated as their product.

RiskLibraryEntry stores reusable scenario text, CIA associations, treatment guidance and suggested assessment data. Creating from a template produces a reviewable risk, and later template changes do not rewrite that assessment. Risk creation receives library_template_id; the server retrieves suggested KEEN-AF control references from the stored template, filters them against remaining controls and writes those links under KEEN-AF:1.0, even when the active framework is different.

Going deeper: migrations and CSV exchange

The release schema and seed migrations supply the risk library, unified risk and asset records, and template control mappings; earlier incremental migrations are archived in alembic/legacy_versions/. Use the active release migration chain when inspecting or extending a fresh installation.

CSV import creates new scenarios and validates the complete file before committing, with size and row limits and validation of ownership, ratings and control references. Export protects spreadsheet cells against formula interpretation. Preserve whole-file rejection and formula-safe output when changing the schema.

Documents, people and assurance records

Native documents support folders, types, tags, rich-text content, immutable content revisions, hashes and comments. The UI's update includes expected_content_version to detect concurrent content edits; preserve server-side sanitisation and version checks when extending the editor.

Keep people and accounts separate. People and personnel-assurance records are separate from login identities: a person can have no Keen account and still have a role, assets, training or other assurance records. Never turn an assurance record into an implicit authentication grant.

A vendor can supply assets, and assigning an asset to a vendor moves its single supplier relationship. ISMS objectives, measures, metrics, assets, access records and meetings link assurance activity to the framework; the access matrix records intended or assessed access while external systems enforce their own permissions. Scheduled audits and metric tasks run through the worker and need deterministic, idempotent behaviour.

SWOT domain and access boundaries

services/isms/swot.py owns SWOT validation, hierarchy edits, version checks, bounded search and relationships, and HTTP adapters retain the ISMS read/manage dependencies. IsmsSwot stores a separate context entity, IsmsSwotLink stores validated references, and the existing ISMS control and clause link tables store framework-specific mappings. A PostgreSQL transaction advisory lock serialises structural and relationship writes and expected_version rejects stale item edits.

BoundLimit
Hierarchy depth12 levels
Relationship writes200 links per item
Framework mapping payloads100 references per kind
List responses200 rows
Going deeper: target access, audits and the planning views

Related targets are resolved at read time. Risk links require the existing per-risk access predicate on both writes and reads, deleted targets are omitted, and target text and identifiers are excluded from relationship changelog entries so target permissions cannot be bypassed. Question targets use isms_swot and recheck source access through the shared question service. Audit samples use the existing source and destination permission checks; audit_swot_scope records explicit audit selection, selected titles and quadrants are deliberately shared with audit readers, scope edits require ISMS source access and existing audit ownership or admin authority, and omitting swot_ids preserves existing selections.

planning-views.js supplies shared boards, timelines, hierarchy and direct relationship visualisations using the existing local D3 asset. Labels use text nodes or the shared HTML escaping helper, status updates use protected API helpers, and drag-and-drop has a select-control alternative. New scripts remain external and use the supplied CSP. SWOT and Objective dates use ISO calendar dates, and 0010_swot_planning extends the active migration chain.

Quizzes, schedules and reminders

services/quizzes/ owns quizzes: authoring.py (settings, questions and status), audience.py (assignment, participants and invitations), rounds.py (rounds and their worker jobs), attempts.py (a person's sittings), grading.py, results.py, and measure.py, which keeps each quiz's own effectiveness measure in step with it and records round averages on it. scoring.py and progress.py are pure functions. 0019_quizzes extends the active migration chain.

A QuizAttempt stores its layout: the questions and options in the order shown, with the answer key, which leaves the server only in a quiz manager's view of the attempt or the person's own open review. A review closes once a later round of the quiz opens. An attempt has one QuizAnswer row per question from the start, so saving a page updates rows, and a question edited or deleted later never changes an attempt. Scores are stored unrounded and rounded for display.

Saving a page or handing in takes a shared lock on the round, and closing a round takes its row lock, so a round's recorded average counts every attempt handed in before it closed and an attempt handed in during the close is refused. Grading locks the attempt, then the round. Two starts of one attempt meet the unique round-and-person constraint, and the second carries on with the first. Answers go in only from the account that started an attempt, and moving the account of a People record with quiz rounds needs quiz.manage.

Saving an active quiz runs open_due_round: a one-off quiz opens its round as it is activated, and a scheduled quiz opens the round its schedule has due today, so a quiz activated or rescheduled after the day's worker run still opens on time. quiz_availability tells the quiz page and the register whether people can take a quiz now, or when they next can.

services/schedules.py holds what scheduled audits and quizzes share: the recurrence rules over the ScheduleColumns mixin, the materialiser that creates one run per date under the schedule's row lock, and deliver_once, which claims a recipient row's timestamp before sending, so overlapping workers never send twice and a failed delivery is tried again. It reads what each email needs in a short transaction and sends it outside any transaction. Requests hand quiz invitations to send_quiz_invitations_task, and quiz_rounds_task invites anyone a round has missed. The daily quiz_rounds_task closes due rounds and then opens scheduled ones; send_reminders_task reminds audit attendees and quiz participants.