NIS2 Compass

NIS2 Compass is the compliance management platform in the opensecstack ecosystem. It helps organisations subject to the EU NIS2 Directive (Directive 2022/2555) assess, track, and demonstrate adherence to the ten cybersecurity risk-management measures defined in Article 21(2), and supports the incident notification obligations in Article 23.

Overview

NIS2 Compass exposes a REST API on port 8090, backed by a Python/Flask application, PostgreSQL 16 as the primary data store, and Redis 7 for caching and session state. Schema migrations are managed by Alembic and applied automatically at container startup. An audit subsystem implements the CITADEL WORM append-only log pattern, producing tamper-evident evidence chains suitable for regulatory inspection.

The platform is licensed under Apache-2.0 and is self-hosted with no external SaaS dependency.

Key features

• Ten-control template library — a canonical reference of all ten NIS2 Article 21(2) measures (a)–(j), seeded into every deployment.
• Structured assessment workflow — assessments progress through a guarded state machine: draft → in_progress → under_review → completed → archived. Each transition is enforced by the API.
• Per-control evidence tracking — each control stores compliance status, JSONB evidence references, risk score, gap description, remediation plan, and reviewer notes.
• Content-addressed artefact storage — evidence files are hashed with SHA-256 on upload; duplicate detection and integrity verification are built-in.
• CITADEL WORM audit chain — every write appends a cryptographically linked row to audit_log. A PostgreSQL trigger blocks any UPDATE or DELETE, making the chain tamper-evident at the database layer.
• NIST CSF category mapping — each NIS2 Article 21(2) control is mapped to a NIST Cybersecurity Framework function (identify, protect, detect, respond, recover) for cross-framework reporting.
• IRFlow Article 23 notifications — IRFlow notifies NIS2 Compass asynchronously when a regulatory-significant incident (P1/P2/P3) is created, updating the Article 21(2)(b) Incident Handling control with evidence.

Architecture

The platform consists of five components, started in a defined dependency order enforced by Docker Compose depends_on conditions:

The database schema uses six core tables. The audit_log table is immutable: a PostgreSQL trigger raises an exception on any UPDATE or DELETE attempt, regardless of the caller's privileges. Each audit row records a SHA-256 chain hash over its own fields plus the preceding row's hash, forming a linked structure where any retroactive alteration produces a detectable break.

Ports & endpoints

The full OpenAPI specification is available at http://localhost:8090/docs when the API is running.

"cm"># Start the development stack
git clone https://github.com/opensecstack/opensecstack.git
cd opensecstack/nis2compass
docker compose -f docker-compose.dev.yml up --build

"cm"># Verify the API is up
curl http://localhost:8090/health
"cm"># {"status": "ok"}

Integration

sinauth (identity)

NIS2 Compass authenticates users via sinauth SSO using OpenID Connect (authorization code + PKCE). RS256-signed tokens are validated against the sinauth JWKS endpoint via app/sinauth.py. The web dashboard uses sinauth.ts for popup-based login and handles the OIDC callback. See the sinauth integration guide for setup details.

CITADEL (governance)

Every write operation appends a row to the WORM audit_log table. The chain hash construction uses SHA-256 over the row's fields plus the preceding row's hash, producing a tamper-evident ledger. Immutability is enforced at both the application layer and the database layer via a PostgreSQL trigger. This satisfies the evidentiary requirements of NIS2 Article 21 and Article 23 audits.

IRFlow (incident response)

IRFlow notifies NIS2 Compass asynchronously via IRFLOW_NIS2_API_URL when a regulatory-significant incident (P1, P2, or P3) is created. The notification updates the Article 21(2)(b) Incident Handling control with incident evidence. The async design means a slow NIS2 Compass API can never block the incident creation path in IRFlow.

APIGuard (API security)

APIGuard scan findings are mapped to NIS2 Article 21 measures and can be submitted as control evidence. See apiguard/docs/nis2-mapping.md for the full mapping.

ThreatFlow (threat intelligence)

ThreatFlow forwards supply chain IOCs to NIS2 Compass as evidence artefacts for the Article 21(2)(d) supply chain security control, in STIX 2.1 format.

Full documentation

The complete NIS2 Compass documentation lives in the nis2compass/docs folder on GitHub. Key references:

• quick-start.md — zero-to-first-assessment guide
• architecture.md — Flask API, PostgreSQL, Redis, Alembic, and CITADEL WORM design
• api-reference.md — full REST API reference
• nis2-controls-reference.md — canonical reference for all ten Article 21(2) measures
• assessment-workflow.md — step-by-step compliance assessment walkthrough
• configuration.md — environment variable reference for all runtime configuration