Security Whitepaper

Product: Exceptao / paraKSCol / Cyberzgodnošć EDU  ·  Last updated: 2026-05-15

1. Security philosophy

This product is sold to security professionals — CISOs, security engineers, compliance officers — who will scrutinise it before trusting it with their organisation’s compliance data. Three principles guide every design decision:

1. Fail closed. If a security control cannot run — Vault unreachable, audit chain broken, backup provider down, RLS misconfigured — the system refuses to operate the affected surface and surfaces the failure explicitly. It does not silently degrade, skip the control, or log a warning and continue. Compliance software that silently degrades is worse than no software.

2. The database is the security boundary. Tenant isolation is enforced by Postgres Row-Level Security at the database layer, not by application-layer filters. A bug in application code that forgets to filter by tenant is harmless: the database returns zero rows because the RLS policy blocks the query. Application-layer filtering is defence-in-depth, not the primary control.

3. Tamper-evidence over tamper-prevention. Any operator with sufficient database access can in theory modify logs and backups. The architecture does not assume this is impossible — it makes any tampering detectable and traceable through the hash chain, anchor timestamps, and the verification endpoint. An organisation can verify the integrity of their own audit log at any time without trusting the Operator.

2. Tenant isolation

2.1 Postgres FORCE ROW LEVEL SECURITY

Every tenant-scoped table has the following applied at migration time:

ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
ALTER TABLE <table> FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON <table>
  USING (tenant_id::text = current_setting('app.current_tenant_id', true));

FORCE ROW LEVEL SECURITY is the critical line: it applies the policy even to the table owner. The application runtime Postgres role (app) is not a superuser and is not the table owner (tables are owned by migrator). The app role is constrained by RLS on every query — it cannot bypass RLS even if an application bug constructs a query that omits the tenant filter.

The GUC pair (app.current_tenant_id, app.current_org_unit_id) is set within a SET LOCAL block at the start of each request’s database transaction:

# apps/tenants/context.py
with connection.cursor() as cur:
    cur.execute("SET LOCAL ROLE app")
    cur.execute("SET LOCAL app.current_tenant_id = %s", [str(tenant.id)])
    cur.execute("SET LOCAL app.current_org_unit_id = %s", [str(org_unit.id)])

SET LOCAL means the GUC values expire at transaction end. pgbouncer runs in transaction pooling mode — connections are returned to the pool at transaction end, ensuring no GUC value leaks into a subsequent request’s transaction.

2.2 Database role split

The app role cannot read, update, or delete audit log rows written by audit_writer. The superadmin role is used only by the Operator’s cross-tenant administrative panel, and every action taken under superadmin is itself audit-logged.

2.3 Organisation unit (sub-tenant) isolation

A second isolation dimension — org_unit_id — scopes access for site-bound roles in multi-institution deployments (e.g. a JST tenant with nested school units). An ITSO assigned to School A sees only School A’s ControlTasks, incidents, and samoidentyfikacja records. This scoping is enforced by RLS at (tenant_id, org_unit_id), not application code.

2.4 Region isolation

Region is set at Tenant creation and is an immutable attribute. Customer business data does not cross regions. The EU region (Frankfurt) and the PL region (Warsaw — when active) are physically and logically separate deployments. Control-plane metadata (tenant routing, subscription records) is stored in the EU region and contains no customer business data.

3. Authentication

3.1 Local accounts

• Password hashing: Argon2id with parameters meeting or exceeding OWASP 2024 guidance: memory ≥ 64 MiB, iterations (time cost) ≥ 3, parallelism ≥ 4. Parameters are stored in the hash string and are upgradeable without invalidating existing hashes.
• TOTP MFA: Mandatory from the second login (configurable per Tenant: grace-window enrolment or hard-block on first login). TOTP secrets are AES-encrypted at rest via the Vault transit engine. The raw TOTP secret never touches the database in plaintext.
• Login throttling: 5 consecutive failures per account or per source IP → 15-minute lockout. Sustained brute-force (> 20 failures in 10 minutes from a single IP) → alert to Operator security team and source IP ban via Cloudflare WAF.
• Password reset: Signed time-limited token (30-minute validity), single-use, HTTPS-only, audit-logged. Reset token is sent to the registered email address only.
• Account enumeration protection: Login, password reset, and registration endpoints return identical responses for valid and invalid email addresses.

3.2 WebAuthn passkeys

• Supported authenticators: Platform authenticators (Touch ID, Windows Hello, Android biometrics) and roaming authenticators (FIDO2 hardware security keys — YubiKey, etc.).
• Step-up authentication: Passkey assertions are required for sensitive actions: exception approval or rejection, audit-pack export, SSO configuration changes, API key generation, and Tenant Admin role assignment.
• Sign-count validation: The server validates the authenticator’s sign count on each assertion. A sign-count decrease or unexpected value triggers automatic credential revocation and a security alert to the Tenant Admin.
• Attestation: Attestation statements are validated on registration (configurable per Tenant: direct, indirect, or none).

3.3 OIDC SSO

• Per-Tenant configuration: discovery URL (.well-known/openid-configuration), client ID, client secret (envelope-encrypted in Vault).
• Supported flows: Authorization Code with PKCE only. Implicit flow and hybrid flow are not supported and cannot be configured.
• Token validation: signature (JWKS), iss, aud, exp, nbf, nonce (bound to PKCE code); replay window 60 seconds.
• “Sign in with Microsoft” preset: Entra ID / Azure AD via the standard OIDC flow. Supports multi-tenant and single-tenant Entra configurations.
• JIT provisioning: new User records are created on first OIDC login if the email domain matches the Tenant’s configured allowed domains. Group-to-role mapping is configurable.

3.4 SAML 2.0 SSO

• Per-Tenant SAML configuration via IdP XML metadata upload or metadata URL (auto-refreshed).
• SP-initiated SSO; IdP-initiated SSO is disabled by default (configurable per Tenant).
• SP keypair: derived from the application’s secret key via HKDF; not stored externally.
• Attribute mapping: configurable mapping of SAML assertion attributes to User fields (email, name, role).
• JIT provisioning with group-claim-to-role mapping.
• AssertionConsumerService (ACS) URL validated against the SP metadata on every response.
• InResponseTo validated to prevent IdP-initiated replay.

3.5 Sessions

• Server-side Django sessions stored in the database (not in client-side cookies).
• Session cookie attributes: Secure; HttpOnly; SameSite=Lax.
• Session is invalidated server-side on logout. “Logout all devices” invalidates all active sessions for the User.
• Short-lived access: session timeout after 15 minutes of inactivity (configurable per Tenant within a maximum of 8 hours).

4. Authorisation

• Capability-based permissions: Every API action (view, create, approve, export, etc.) checks a named permission code (e.g. exceptions.exception.approve). Permission checks are performed at the API view level on every request.
• Role-based assignment: Roles bundle sets of permission codes. Users are assigned one or more roles. Permissions can also be granted directly to a User outside a role (direct grant).
• Effective permission resolution: Resolved once per request by merging all role-based and direct permissions; the result is cached on the request object for the duration of the request. No caching across requests.
• Built-in roles: tenant_admin (full administrative access), submitter (create and submit exceptions/risks/incidents), approver (approve or reject exceptions/risks), auditor (read-only access to all records plus audit chain verification), itso (institution-scoped equivalent of auditor in NIS2 Schools module).
• Custom roles: Tenants may define custom roles using the same permission code vocabulary. Custom roles are scoped to the Tenant and not visible to other Tenants.
• Org-unit scoping: Roles can be assigned at the Tenant level (sees all org units) or at a specific org unit level (sees only that org unit and its children).
• Security features are not paywalled: MFA, audit log access, audit chain verification, basic audit reports, RBAC, encryption, and ≥ 1 OIDC IdP configuration are available on every subscription tier. No security control is gated by pricing.

5. Audit log integrity

5.1 Append-only enforcement

The Postgres audit_writer role has INSERT privilege on audit_log and no UPDATE or DELETE. The CI/CD pipeline verifies this privilege set on every deployment by running:

SELECT has_table_privilege('audit_writer', 'audit_log', 'UPDATE');
-- must return false
SELECT has_table_privilege('audit_writer', 'audit_log', 'DELETE');
-- must return false

If either check fails, the deployment is blocked.

5.2 SHA-256 hash chain

Each row in audit_log contains a row_hash field computed as:

row_hash_n = sha256( prev_hash_(n-1) || canonical_json(row_n) )

• prev_hash_0 = 32 zero bytes (for the first row of each Tenant’s chain)
• canonical_json = RFC 8785 JSON Canonicalization Scheme (JCS) applied to an explicit, versioned field list
• The field list version (schema_version) is stored on each row, so future schema changes do not retroactively invalidate old hashes

The hash is computed by the application before the INSERT and stored alongside the row. The audit_writer role inserts both the row data and the hash in a single atomic operation.

5.3 Verification endpoint

GET /api/audit/verify walks the full hash chain for the requesting Tenant and returns:

{
  "ok": true,
  "broken_at": null,
  "total_rows": 47291,
  "first_row_at": "2026-01-15T09:00:00Z",
  "last_row_at": "2026-05-15T14:23:11Z",
  "last_anchor_at": "2026-05-15T14:00:00Z",
  "schema_versions_seen": [1]
}

If the chain is broken, ok is false and broken_at contains the ID and timestamp of the first broken row. This endpoint is available to all Users with the auditor role and to the Tenant Admin.

5.4 Hourly anchor snapshots

A Celery beat job runs every hour and records the current row_hash of the latest audit log row per Tenant into an audit_anchor table. This table is written by the superadmin role (not audit_writer) and is read-only from the application’s perspective. Anchors provide a lightweight checkpoint: to verify the chain from the last anchor point, you only need to walk rows since the last anchor, not the full chain.

5.5 Boot-time chain integrity check

On application startup, the system: (1) reads the latest row_hash from audit_log for each Tenant; (2) reads the latest stored anchor from audit_anchor for each Tenant; (3) compares them. A mismatch means rows were added, modified, replaced, or the database was restored to a previous state since the last anchor. On mismatch, a chain_discontinuity anchor event is written and the Operator’s on-call is alerted. This is a deliberate design: any restore or tampering is detectable.

5.6 Right-to-erasure pseudonymisation

On a verified GDPR Art. 17 erasure request, the actor-identity fields in audit log rows (actor_email, actor_ip) are replaced with stable tombstones (actor_tombstone_<uuid>). The hash chain is recomputed over the tombstone value, preserving chain integrity. The event record (action, timestamp, target) is retained. Legal basis: legitimate interest in audit integrity (GDPR Art. 6(1)(f)).

6. Encryption

6.1 In transit

• Edge: TLS 1.3 minimum (TLS 1.2 disabled), Cloudflare-terminated. HSTS preload: Strict-Transport-Security: max-age=63072000; includeSubDomains; preload. Cipher suites: Cloudflare default (TLS 1.3 only ciphers; no RC4, no 3DES, no CBC-mode ciphers).
• Origin: VPS ↔ Cloudflare via mutual TLS (mTLS) Cloudflare Tunnel. The VPS has no inbound ports — there is no direct IP path to the origin.
• Internal: Service-to-service communication (Django ↔ Postgres, Django ↔ Redis, Django ↔ Vault, Django ↔ Celery) is confined to the Docker network on localhost. No plaintext crosses host boundaries.

6.2 At rest

• VPS storage volume: LUKS full-disk encryption. The LUKS key is stored in memory after boot; a reboot requires key re-entry ([TO BE COMPLETED: document LUKS unlock mechanism for production]).
• Database backups: GPG-encrypted with a 4096-bit RSA keypair before transmission to R2 or B2. The private key is stored in 1Password (operator vault) and on a hardware security token (YubiKey or equivalent). The private key never resides on the VPS in plaintext.
• Evidence files (Cloudflare R2): Per-tenant DEK (AES-256-GCM) wraps a per-object DEK. The per-tenant DEK is stored in HashiCorp Vault’s KV store, wrapped by a Vault-managed KEK in the transit engine. R2 also applies its own provider-side AES-256 encryption. Cloudflare sees double-encrypted ciphertext for sensitive evidence files.
• Sensitive credential fields (database columns): OIDC client secrets, Microsoft Graph OAuth tokens, TOTP secrets, integration API keys: stored as Vault transit engine ciphertext. The plaintext is fetched from Vault only in memory, never written to the database.

6.3 HTTP security headers

7. Secret management

• HashiCorp Vault is self-hosted on the Operator’s VPS (EU — Frankfurt). It serves as the sole runtime secret broker — no secrets are hardcoded, stored in environment files, or committed to source control.
• Vault seal/unseal: Vault is sealed at boot. Unseal keys are Shamir-shared (5 shares, threshold 3). Key shares are stored: shares 1–3 in the Operator’s 1Password vault; shares 4–5 on hardware security tokens held by separate keyholders. No single person holds enough shares to unseal Vault alone.
• Application access: The application fetches secrets from Vault at startup via AppRole authentication. The AppRole RoleID and SecretID are injected at container start by the deployment process; neither is persisted to disk. Vault tokens are short-lived and renewed automatically.
• Per-tenant credentials: OIDC secrets, Graph tokens, and integration API keys are stored as Vault KV secrets scoped to the Tenant’s ID. The application fetches them per-request with the minimum required Vault policy.
• Secret scanning: gitleaks runs in CI on every commit and as a pre-commit hook on developer machines. Any detected secret in Git history triggers an immediate incident.
• Rotation: AppRole SecretIDs are rotated on every deployment. Per-tenant DEKs can be rotated on demand via the admin panel.

8. Network architecture

• No public inbound ports. The VPS has no publicly-accessible inbound TCP or UDP ports — not for the application, not for SSH, not for Vault, not for monitoring, not for database. The Linux firewall (UFW) blocks all inbound by default.
• All ingress via Cloudflare Tunnel. cloudflared runs as a service on the VPS and maintains an outbound-only encrypted mTLS connection to Cloudflare’s edge. Cloudflare proxies inbound traffic through this tunnel to the application.
• Operator access. SSH access, Vault UI, Grafana, and other administrative interfaces are exposed through Cloudflare Tunnel and protected by Cloudflare Access (identity-aware proxy). Authentication requires: (a) Cloudflare Zero Trust team membership; (b) MFA. No VPN is used; no SSH keys on the VPS for external access.
• Egress filtering. Outbound traffic from the VPS is filtered by UFW egress rules to permit: Cloudflare API endpoints, R2, Backblaze B2, Microsoft Graph endpoints, package repositories, NTP servers. All other outbound is blocked.
• WAF. Cloudflare managed rule sets are enabled (OWASP Core Rule Set, Cloudflare Managed Rules). Custom rules: rate-limit authentication endpoints (10 req/min per IP); challenge anomalous traffic; block known malicious IP ranges.

9. Backups and disaster recovery

• 3-2-1 backup policy: 3 copies of data, across 2 storage providers (Cloudflare R2 primary + Backblaze B2 secondary), with 1 provider in a different geographic location (both use EU data centres; both are physically distinct from the origin VPS).
• Postgres PITR: Continuous WAL archiving to Cloudflare R2 enables Point-in-Time Recovery (PITR) to any point within the WAL archive retention window. RPO target: ≤ 1 minute.
• Full backups: Nightly full Postgres dumps, GPG-encrypted, uploaded to R2 (primary) and B2 (secondary). Retention: 30 daily backups, 12 monthly backups.
• Vault backup: Vault’s storage backend is included in the nightly backup. Vault unseal keys are stored independently and not included in the backup.
• Restore drills: Quarterly automated restore drill: provision a fresh restore VM in EU region, restore Postgres from the latest GPG-encrypted backup (or PITR), restore Vault from backup and unseal, bring up the full application stack, run the defined smoke-test suite (login, create an exception, submit through the workflow, verify the audit chain via GET /api/audit/verify, generate an audit-pack export), tear down, record the drill outcome in the production audit log.
• RTO target: ≤ 4 hours (v1 with manual restore). Warm-standby with RTO ≤ 30 minutes is planned for Phase 3.

10. Supply chain security

• Dependency pinning: All Python dependencies pinned in requirements.txt with SHA-256 hashes. All npm dependencies pinned in package-lock.json. Docker base images referenced by digest (no floating :latest tags in production).
• Automated vulnerability scanning: pip-audit (Python CVEs), npm audit (Node CVEs), Trivy (container image OS and library CVEs), Semgrep (static analysis for security anti-patterns) — all run in CI on every commit and on a nightly schedule.
• Secret scanning: gitleaks runs in CI and as a pre-commit hook.
• Dependency update management: Dependabot (or Renovate) configured to open PRs for security updates automatically. Security updates are reviewed and merged within the vulnerability SLA window.
• SBOM: A Software Bill of Materials (CycloneDX JSON format) is generated per release and published as a release artifact. This enables downstream consumers to assess supply-chain risk.
• No auto-uploaded telemetry: Third-party packages are evaluated for telemetry at adoption time. Packages that upload data to external services without opt-out are not used.

11. Vulnerability management

• Coordinated disclosure: security@exceptao.com. .well-known/security.txt published at exceptao.com, parakscol.pl, and cyberzgodnosc.edu.pl.
• PGP-encrypted disclosure: [TO BE COMPLETED: publish PGP public key at .well-known/security.txt and at each brand domain for encrypted vulnerability reports].
• External penetration test: Planned before first paying customer. Recurring annual cadence once revenue supports it.
• Severity assessment: CVSS 3.1 base score used for initial triage; context-adjusted score used for prioritisation.

12. Incident response

The Operator maintains a documented Incident Response (IR) runbook covering: detection and initial triage, containment, eradication, recovery, post-mortem, and regulatory notification.

The Operator’s obligation to notify the Controller (Tenant) of a personal data breach is ≤ 72 hours from awareness, per the DPA at /legal/dpa §8. This enables the Tenant to meet its own supervisory authority notification deadline.

14. Contact