ZERONE Platform Administration Guide

1Platform Overview

Zerone is an integrated GRC + cybersecurity governance platform. It unifies asset discovery, a continuously-validated CMDB, multi-domain inventory (software / data / accounts), configuration-benchmark compliance, a central risk register with policy/control/framework mapping, evidence and audit readiness, remediation, an on-host endpoint agent, DLP decisioning, SIEM forwarding and reporting — moving an organization from fragmented, manual security to unified, measurable, control-driven governance.

Architecture

• Frontend: static HTML + per-page JavaScript served by the FastAPI app.
• Backend: FastAPI + SQLAlchemy; SQLite by default, PostgreSQL supported. Two API generations coexist — prefer /api/v1/* (legacy /api/* lacks separation-of-duties + audit on some routes).
• Optional Redis: caching / sessions / throttling, with transparent in-memory fallback (single-worker installs run without Redis).
• Endpoint agent: a real OS service (Windows/Linux/macOS) that registers over TLS and posts collector data.
• Background daemons: discovery scheduler, inventory-refresh scheduler, SIEM forwarder, license heartbeat.

2Core Concepts

3Roles & Responsibilities Implemented

A rank-based RBAC matrix (role → module → action → scope) resolves the permissive union across a user's active roles; scope order all > assigned > dept > own > none. ~27 customer roles across 4 ranks + vendor-only roles. Segregation of Duties is enforced on role assignment (18 seeded rules; conflicts hard-blocked).

4Access Control & Administration

5Dashboards Implemented

Executive dashboard + analytics read aggregate KPIs: open/critical risks, compliance %, inventory freshness, discovery status, remediation status. Drops in compliance % = new failed checks; rising stale % = growing blind spots; overdue remediation = accountability gaps.

6Discovery Implemented

A discovery profile (the schedule) carries: target (CIDR/IP/list), ports, frequency, credential(s), business unit, environment, scan window, probe methods, allowed ports, enrichment scope, max concurrency (32), timeout (5s), missed-scan threshold (3), stale-days (30). Scans are bounded TCP-connect probes; no aggressive scanning by default; scanning does not require a credential (credential is only used to authenticate/enrich). Hostname = NetBIOS + cleaned reverse-DNS, overridden by the credential/agent OS name.

Surfaces: discovery.html; /api/discovery/{summary,drift,review-queue,candidates,retire-candidates}, /assets/{id}/history.

7CMDB / Assets Implemented

What the CMDB is

The CMDB (assets, cmdb_inventory.html, /api/assets) is the authoritative inventory of every managed asset and the single source of truth the rest of the platform builds on (inventory, compliance, vulnerabilities, risk, ISMS scope). Each asset carriesfour independent lifecycle axes, deliberately kept separate:

The end-to-end pipeline

From first sight of a host to a governed risk, every stage is explicit, auditable and reversible:

Onboarding candidates & the decision

Newly-discovered hosts appear in the Onboarding Candidates panel at the top ofcmdb_inventory.html. A candidate is not a managed asset: it is created withstatus=candidate, managed_status=discovered, environment=unknown,criticality=low, not authorized, and onboarding_state=review_required.

Candidate lifecycle: detected → identity_matching → credential_matching → authentication_succeeded / authentication_failed → review_required → approved_for_onboarding → onboarded / rejected / ignored.

Credential safety

Authentication uses scoped Credential Vault service accounts (WinRM for Windows, SSH for Linux/mac), with three safety controls:

Collection & honest freshness

Onboarded, authenticated assets are enriched by one shared engine (software → vulnerability → accounts → configuration → data). Per-module outcomes are tracked on the collection job, and asset freshness is honest about partial failure:

Configuration-benchmark assignment

The configuration benchmark (CIS) for an asset is resolved deterministically: an explicit per-asset assignment wins, else the active policy matching the asset's OS family (and version). If the OS is unknown or no policy matches that OS, the asset is left unassigned — it is never scored against a benchmark for the wrong OS (e.g. a Linux host against a Windows baseline), and a benchmark is never chosen "because a vulnerability was found".

Risk unification — one canonical register

Every automated risk source — configuration failures, framework non-conformity, external-scanner CVEs, inventory drift and asset-posture — now writes the single canonical Risk Register(grc_risks) through the shared risk bridge, deduplicated so the same condition seen by two paths converges onto one risk (an external-scanner CVE and the built-in scan collapse together). Closure is verification-gated — a passing re-scan, a scanner "not-seen" or a reviewed drift closes the linked risk, and a human-edited risk is never auto-closed.

Reachability, retirement & history

Assets not seen across scans go not_seen → down (threshold-gated) and, after prolonged absence, become retire candidates surfaced in a separate panel. Nothing is ever auto-deleted — a human keeps, retires (soft, kept for records) or deletes (rank 3). Every reachability / credential / managed / onboarding change is appended toasset_status_history.

The CMDB screen

cmdb_inventory.html shows, top to bottom: platform metrics, security-coverage and freshness strips, the Onboarding Candidates panel (approve / reject / ignore), the Retire Candidates panel, and the main asset table with reachability / credential / managed / onboardingbadges, filters and per-asset detail. All confirmations use the platform's styled dialog and toast — never native browser pop-ups.

Supporting Assets Register — governance overlay

The Assets & Inventory → Supporting Assets page (supporting_assets.html) is the canonical register of everything that supports the organisation's services and information — not just discovered technical systems, but external services, people/roles, organizational architecture and physical facilities. Because the CMDB Asset requires a unique IP and a technical schema, it cannot hold non-technical assets; the Supporting Assets Register is therefore agovernance overlay — a SupportingAsset (SA-####) with an optional1:1 link to the CMDB asset. Technical inventory/software/accounts/vulnerabilities stay authoritative in CMDB (linked, never copied); ownership, governance category, related services, service impact, information-asset dependencies, operational lifecycle and review live here.

• 15 governance fields: ID · name · description & purpose · governance category (7, separate from the technical type) · owner (+department/vendor) · environment (5) · location/host/platform (readable summary + structured details) · stored Information Assets (M2M) · related Service (M2M → the Services Register / bcm_products) · service impact (5, per service) · operational status (5) · inventory/registration number (text) · last review · notes.
• Services come from the existing Services Register (IaaS/Co-location/BaaS/DRaaS/Sima/… areseeded idempotently); overall impact is derived as the highest active service impact.
• Manual + automated: register manually (non-technical assets need no IP/host/OS), or ingest viaPOST /supporting-assets/observe from discovery/agent/credential/cloud/import. Modes:propose_only (reconciliation queue), auto_create_draft (default — unverified),auto_create_active (policy-gated; never activates an incomplete record).
• Identity & no duplicates: matches on CMDB link / external id / (source, record)idempotency key / name — never IP alone. Verdicts exact/probable/conflict/new; a Reconciliation Inbox lets an analyst merge/create/ignore/defer. Re-scans never duplicate an asset.
• Field authority: inventory refresh updates observation fields (last seen, collection/credential status, technical location) but never overwrites a confirmed governance field, reduces service impact, removes an owner, or cancels an asset. Discovery does not cancel an unreachable asset.

How it works, day to day

1. Register. Assets & Inventory → Supporting Assets → fill name + governance category; save asPlanned (default) or Active. Non-technical assets (people, external services, org units, facilities) need no IP/hostname/OS. To go Active, an internal owner or responsible department + a category are required.
2. Enrich in the drawer. Open a row → tabs for Information Assets (link what the asset stores/processes/hosts), Services & Impact (link services from the Services Register and set a per-service impact — the overall impact is derived as the highest active),Technical (CMDB), Provenance, Reviews, History.
3. Discovered assets flow in automatically. The existing Subnet Discovery → Live Host → Credential → Collection → Risk pipeline is unchanged; a discovered technical host is ingested viaobserve as an unverified draft (or a reconciliation proposal) and auto-linked to its CMDB record — never duplicated on re-scan. An analyst confirms governance fields and flips it to Active.
4. Reconcile. The Reconciliation Inbox tab lists automation proposals with observed-vs- confirmed conflicts; merge to a confirmed asset, create a draft, ignore or defer.
5. Review & export. Record reviews (cadence-driven next-review + overdue), and export the 15-column Azerbaijani CSV.

CMDB linking — link ≠ add to CMDB

The Technical (CMDB) tab lets you link an existing CMDB record 1:1 (search by asset id / name / IP → Link; Unlink to detach). It does not create a CMDB row and cannot push a non-conforming asset into CMDB — the endpoint accepts only an existing CMDB asset (404 otherwise) and rejects a record already linked elsewhere (409, one-to-one). Only link when the supporting asset has a real technical counterpart in CMDB (e.g. “Core banking DB” → db01). Assets that donot correspond to a CMDB record — people, external services, org architecture, physical facilities — are not added to CMDB; they live in the Supporting Assets Register unlinked. That separation is the whole point of the overlay: non-technical assets are never forced into the CMDB's IP/host schema.

Endpoints

GET /api/discovery/candidates (onboarding queue) ·POST /api/discovery/assets/{id}/onboarding?action=approve|reject|ignore (rank-gated, audited) · GET /api/discovery/{summary,review-queue,retire-candidates,drift} ·GET /api/discovery/assets/{id}/history ·POST /api/credentials/{id}/test · GET/POST /api/assets… ·GET/POST /api/v1/supporting-assets….

8Credentials / Service Users Implemented

Vault credentials (CredentialVault): type, username, AES-GCM secret_enc, port, IP-range scope. Matching is strict — exact-IP → narrowest CIDR (+ optional type); a credential whose scope does not cover the host is refused rather than tried. WinRM (Windows) / SSH (Linux) via host_agent; the working credential is remembered and auto-resolved per asset. Repeated auth failures trip an exponential back-off breaker so a wrong credential can't keep hammering a target's lockout. POST /api/credentials/{id}/test runs a real OS-appropriate probe. All usage is written to credential_usage_logs — never the secret, in any response, log, audit line or error.

9Inventory Auto-Refresh Implemented

Re-verifies existing assets on a schedule using the auto-resolved credential (or agent), snapshots inventories, and raises drift. Never deletes inventory. Freshness statuses: Fresh · Due Soon · Stale · Refresh Failed · Unreachable · Credential Failed · Unknown · Disabled.

Surface: inventory_refresh.html; /api/inventory-refresh/* (incl. /drift,/drift/summary, /drift/{id}/review). Data is stored already-masked; snapshots never delete live inventory. The drift table is shared with the Discovery module's reachability/host drift.

10Software Inventory Implemented

11Data Inventory Implemented

Scans allow-listed paths, classifies sensitive data, stores masked findings — full sensitive values are never persisted.

12Account Management Implemented

13Configuration Compliance Implemented

Tabs: Dashboard · Benchmark Library · Parser Review · Asset Scan · Scan Results · Manual Review · Exceptions · Remediation · Reports.

14Risk Register Implemented

Risk Register — the central register

The Risk Register (grc_risks, /api/v1/risks) is the authoritative register of enterprise risks. Each risk carries a server-generated reference (RISK-0001), an owner, an inherent and residual rating, a treatment/response, links to the mitigating controls, mappings to policies/frameworks, and a full governed lifecycle with review cadence and audit trail. Menu: Risk Management → Risk Register.

The workspace

The page is a multi-tab workspace: Dashboard · Risk Register · Incidents ·Control Register / Control Assessment · Residual Risk & Response ·Action Plan · Risk Taxonomy · KRI / Fine-Kinney · Treatment Plans ·Proposals · Reviews · Analytics · SLA · Audit Trail ·Categories · Risk Rating Tables. The register table has filters + a heatmap; opening a risk shows its detail (assessment, treatment, controls, compliance mappings, lifecycle, history).

Risk taxonomy & categories

Risks are classified by a hierarchical taxonomy (grc_risk_categories, managed on the Categories / Risk Taxonomy tabs) — parent/child categories with severity mapping, owner and colour. A risk references one category; the taxonomy drives grouping, heatmap breakdowns and reporting.

Registering a risk

Create a risk (POST /risks): the reference RISK-#### is generated server-side. Fields: title, description, threat scenario, category, owner (required), reviewer, department, asset scope, inherent likelihood & impact, identified date, target closure date, tags. A new risk starts in the Draft/Registered lifecycle state.

Extended register fields — how it works

A supplied 29-column register was compared column-by-column against the canonical platform; only the genuinely missing fields were added (additive), and everything the platform already had was reused — the detailed lifecycle, methodologies and versioned assessments stay canonical. Day to day:

1. Identity & ownership. Give the risk a title + owner as before. New: record theperson reporting the risk — a platform user, or free text for an external reporter (e.g. a pentest firm). This is separate from the owner/reviewer/creator; a resolved reporter is stamped reporter_source=manual, and automated risks are stampedreporter_source=communication_method=automation.
2. Communication method. Pick how the risk was communicated — Platform / Email / Meeting / Phone / Ticket / Formal report / Automation / Other. Choosing Other reveals a required note. The list is served from one server-side taxonomy (GET /risks/communication-methods), not hardcoded in the page.
3. Assets & information. Keep the technical asset scope as before, and link stored Information Assets (POST /risks/{id}/information-assets) — one may be marked primary; classification and C/I/A/Cr are read live from the Information Asset Register, never copied.
4. Threat / nonconformity / master / incident links reuse the existing relationship registers (Threat Register, Risk Findings, master-child relationships, incident links) — nothing is duplicated.
5. Methodology & scoring are unchanged and server-authoritative: Standard 5×5 (likelihood × impact), ATV-500 (threat_likelihood × nonconformity_severity × asset_total, 1–500) and Fine-Kinney. The completeness report is now methodology-aware — ATV-500 factor checks apply only to ATV-500 risks, so a 5×5 risk is never dinged for them.
6. Status & dates. The detail view keeps the detailed lifecycle as canonical and derives a coarse Open/Closed compatibility view, plus the last assessment date from the current versioned assessment. Export CSV (button on the register) emits the 21 Azerbaijani columns.

Inherent vs residual & the rating matrix

Risk is scored on a 5×5 matrix: likelihood and impact each 1–5 (Very Low · Low · Medium · High · Very High); score = likelihood × impact (1–25); the score maps to a rating band (Low / Medium / High / Critical). Inherent = before controls; residual = after the mitigating controls are considered.

The impact scales (financial, capital, EBITDA, safety, …) and rating bands are configurableon the Risk Rating Tables tab. A Fine-Kinney method (probability × exposure × consequence) is also available for the KRI / operational-safety context.

Treatment, response & residual

Each risk gets a response (response_type): mitigate ·accept · transfer · avoid, with response notes. Treatment is planned on Treatment Plans / Action Plan tabs (linked to corrective actions), and theResidual Risk & Response tab records the post-treatment residual rating. Proposalssupport a propose→review workflow for treatment decisions.

Risk acceptance & exceptions

Accepting a risk (POST /risks/{id}/accept) records the accepting authority, acceptance date, rationale and an acceptance expiry (so acceptance is time-boxed and re-reviewed).

Controls linkage

Risks link to the mitigating internal controls (grc_risk_controls,/risks/{id}/controls): each link carries the control's effectiveness(effective/partial/ineffective/not_tested), a relationship type(primary/supporting/compensating/preventive/detective) and coverage. This is the same authoritative Control Library — a control's assessed effectiveness informs the residual rating.

Compliance & policy mappings

The Compliance tab maps a risk to governance context (grc_risk_mappings,/risks/{id}/mappings) with a mapping type — violates · impacts· mitigated_by · related_to — targeting a framework requirement, policy document, internal control or clause, with an optional gap description. Picker source:GET /risks/mapping-options. This ties a risk to the requirements/policies it threatens or is mitigated by, feeding compliance rollups.

KRIs (Key Risk Indicators)

KRIs (/risks/kris) are measurable indicators with thresholds (green/amber/red) linked to a risk; measurements (/kris/{id}/measurements) are recorded over time so a breached threshold signals rising risk. The KRI / Fine-Kinney tab manages them.

Lifecycle, review cadence & governance

A risk moves through a governed lifecycle (lifecycle_status): Draft → Registered → Under Review → Treatment Planned → Treatment In Progress → Pending Evidence → Pending Approval → Accepted / Exception Approved / Mitigated → Closed, plus Overdue · Reopened · Cancelled. Actions:/review (advances the review cadence), /close, /reopen,/escalate. Every status change, review and date change is written to append-only history (risk_status_history · risk_review_history ·risk_date_change_history). Missing/overdue review dates surface as governance flags.

Risk automation — findings become risks

The Risk Automation engine converts technical findings (vulnerability, configuration-compliance, account, data, software, asset-governance, framework and discovery collectors) into scoredgrc_risks entries — via rules on Risk Rules (auto-create risk/task; notify on new risk). Imports: POST /risks/import/from-vulns|from-controls|from-alerts.

Auto-created risks are de-duplicated by a dedupe_key (occurrence count + first/last seen) so a recurring finding updates one risk instead of spawning duplicates, and they carry risk_source/related_* so their origin is traceable. Manual edits to an auto-created risk are preserved.

Heatmap, dashboard & analytics

Server-side widgets: GET /risks/heatmap (likelihood×impact grid),/risks/dashboard and /risks/statistics (by status/rating/category, above appetite, overdue review, missing owner, expiring acceptances), plus the Analytics andSLA tabs for trend and treatment-timeliness reporting.

Roles & permissions

Enforced on the backend; administer via /api/v1/risks/* (the legacy assetrisk_register routes are technical/asset-scoped).

Risk methodology — opt-in, versioned (5×5 · 1–500 · Fine–Kinney)

Alongside the default Standard 5×5, the platform offers an opt-in, versionedrisk-scoring layer. It does not change the canonical register, recalculate existing risks, or create a second register — every existing risk stays on STANDARD_5X5 and a risk uses another methodology only when it is explicitly scored with one. Administer it fromRisk → Risk Methodology (risk_methodology.html).

For the 1–500 methodology: Asset Total Rating = C + I + A + Authenticity (each 1–5 → 4–20);Residual = Inherent × (1 − Overall Control Effectiveness) (effectiveness 0.00–0.90). Level bands, with a boundary value belonging to the higher band: Very Low ≤99 · Low 100–174 · Medium 175–249 · High 250–350 · Very High ≥351.

• Server-authoritative scoring. The workspace calculators (Inherent / Asset Total / Residual) call the engine; the stored score is never taken from the client. Each version stores its formula, factor scales, thresholds and rounding as JSON — configurable without code changes.
• Versions are immutable once published. Edit a draft, then Publish (→ Active, retiring the prior Active) or Retire. A risk records the exact version it was scored with, so history stays reproducible.
• Supporting registers: Threat Catalog (/risk-threats), versioned Information-Asset Valuations with the Authenticity dimension (/asset-valuations), Risk↔Finding links with an asset-integrity check (/risk-finding-links), and manual nonconformities (/manual-nonconformities).
• Governance: Risk Appetite thresholds (/risk-appetite — the 1–500 and 5×5 scales get separate ceilings), master/child relationships, risk↔incident links, and aRisk Governance Config whose enforcement flags default OFF:enforce_sod_on_acceptance (owner can't self-approve), require_evidence_for_residual,residual_requires_approval (approver ≠ owner). Enabling a flag changes behaviour only from that point on.

Importing the IT/InfoSec register. Risk → Risk Methodology → Register Import: (1) Parse the .xlsx; (2) Analyze — the importer recomputes every score and reports each row as create / update / error plus discrepancies. It does nottrust the file's numbers (e.g. a file inherent of 277 where 4×4×18 = 288 is flaggedinherent_mismatch; a C+I+A+Authenticity that ≠ the file's asset total is flaggedasset_total_mismatch); nothing is written. (3) Apply — idempotent upsert by risk ref (re-running never duplicates), optionally also creating the threat, nonconformity, risk↔finding link and master/child relationship.

Threat Register — catalog, observations & controlled automation

The lightweight Threat Catalog in Risk Methodology is the quick editor; the fullRisk → Threat Register (threat_register.html) is the canonical register. Its central rule is a clean separation of three concepts — a catalog record is a reusable definition, not an occurrence:

• Catalog (/risk-threats, TH-####) — reusable threatdefinitions with the full nine-taxonomy classification (category · source · intent · purpose · vector · target · consequence · detection source · likelihood 1–5), lifecycle and review cadence. Feeds the ATV-500 threat-likelihood factor. Curate one row per distinct threattype — never one per alert.
• Observations — the actual security signals (SIEM, vuln scan, incident, CERT, vendor). Idempotent by source + record id: a repeated signal bumps the occurrence count and last-seen, it never duplicates the catalog threat. An observation is unmapped until an analyst (or an automation rule) links it to a catalog threat.
• Automation Inbox — automation proposes, an analyst decides: map to an existing threat, create a draft, merge, reject or defer. Ingest runs in one of three modes —propose_only (default; nothing touches the catalog), auto_map_observation(maps only on an exact fingerprint match) or auto_create_draft (adds a draftthreat, kept out of authoritative scoring until reviewed).

Duplicate detection uses a deterministic fingerprint (normalised name + resolved category/source/intent/purpose/vector/target + external ref) returning exact,probable or new — surfaced as a non-blocking warning on manual create and via a Check-for-duplicates button. Taxonomies are server-authoritative (codes stored, AZ/EN labels + import aliases central); unknown legacy free-text is preserved and flagged aslegacy, never rewritten. A threat's drawer links Targets (assets / processes / services / departments / vendors / subjects), extra taxonomy values, Risks, Controls(effectiveness read live), Observations and Reviews. Export emits the 14 Azerbaijani columns (UTF-8 BOM, injection-safe), and is audited.

The engine never silently rescores existing risks. Likelihood changes are explicit, stamped and recorded in threat history; ATV-500 and historical reproducibility are untouched.

Nonconformity Register — Uyğunsuzluqlar reyestri

The Nonconformity Register (nonconformity_register.html,/api/v1/nonconformities) is the platform's single canonical record of a nonconformity (ISO 27001 cl. 10) — a detected gap or violation against an asset, requirement or control. It is backed by the existing risk_manual_nonconformities table (modelManualNonconformity), promoted to a first-class register rather than a new duplicate module: risks, findings, corrective actions and controls reference the canonical record. Severity (1–5) feeds the ATV-500 methodology's Nonconformity-Severity factor.

How it differs from neighbouring concepts. A finding/vulnerability is raw technical evidence; an issue is a generic remediation ticket; a nonconformityis the governed, audited assertion that a requirement/control is not met; a risk is the potential impact; a CAPA/Action is the corrective work. A nonconformity can be raised from a finding, generate a risk candidate, and be remediated through the Actions/CAPA workflow — each as a link, never a copy.

• Identity — an immutable, server-generated business ID NC-YYYY-######(race-tolerant; the browser never allocates it). Imported legacy IDs are accepted only after a uniqueness check. The legacy NC-#### ref is preserved.
• Fields — title, description, category, target object type, affected asset (explicit kind + canonical id → Information / Supporting / CMDB asset; the register always shows the current canonical asset name, not a stale snapshot), violatedrequirement (registered → grc_requirements/framework clause, or a controlled external free-text ref; multi-link, dedup-protected), detection source, timezone-awaredetected-at, optional CVSS (version/vector/base/source — never auto-mapped to severity), canonical numeric severity 1–5 with provenance, stable status codes, polymorphic responsible party (user / department / LDAP group / internal group, with a display snapshot so it renders even if LDAP is offline), remediation plan, review dates and notes.
• Lifecycle — Qiymətləndirilir → Açıq → Aradan qaldırılma mərhələsində → Qismən aradan qaldırılıb → Bağlanıb, plus Qəbul edilib (accepted). All transitions are enforced server-side. Close requires a closure summary, verification result and either evidence or an approved evidence exception. Accept requires justification and an expiry/next-review date; a severity 4/5 record cannot be accepted by its own creator (separation of duties). A severity change requires a justification and is audited.Reopen (from closed/accepted) requires a reason. Optimistic locking (version counter) blocks lost updates.
• Traceability — Create Risk Candidate raises a draft risk (human-validated in the Risk Register) and links it via RiskFindingLink — it never duplicates a risk and passes severity/asset/evidence as structured inputs (it does not silently overwrite likelihood or asset value). CAPA creates/links an Action(source_type=nonconformity) and advances the record to remediation. Comments/evidence use the platform's polymorphic mechanism. A full history + formal review trail (reviewer, decision, prev/new severity + status) is kept; last_reviewed_at advances only on a formal review, not on every edit.
• Register UI — server-side summary KPIs (total / per-status / high-severity / overdue remediation / overdue review / automation candidates), server-side filtering, sorting and pagination, active-filter chips, and a filtered/authorised CSV export emitting the 18 Azerbaijani columns (UTF-8 BOM, formula-injection-safe, audited). Taxonomies are server-authoritative (codes stored; AZ/EN labels + import aliases central); unknown legacy values are preserved and flagged for reconciliation, never rewritten.

15Policy, Framework & Control Library Implemented

Control Library — the canonical register

The Control Library is the single, canonical register of internal controls. Every other module references it — never re-creates it: framework requirements, the ISMS Statement of Applicability, compliance programs, the risk register, evidence, control testing, audits & findings, issues & actions, exceptions, and assets/services/departments. Configuration Compliance provides an automated assurance signal for controls but does not own them. Menu: Compliance & Controls → Control Library.

The separated status model

A control's condition is described by four independent fields — a single mixed "status" is the anti-pattern this removes. A control can be active yet not implemented andnot assessed, so the library never claims a control works just because it exists. The legacy status column is kept only as a mirror of lifecycle status.

Assessment ≠ governance review · effectiveness

Two deliberately decoupled activities. Recording an assessment never advances or completes the governance review, and vice-versa.

Roles & permissions

Enforced on the backend via the permission matrix (module controls); the UI mirrors it via grc-permissions.js and hides any action the API would reject.

Main screen & KPIs

Five grouped KPI card sets are computed server-side (GET /controls/portfolio) — never from the loaded page — each with a tooltip and clickable drill-down that reuses the metric's own backend filter (so count and drill-down always agree): Portfolio · Implementation · Assurance · Evidence · Governance. The filter bar covers lifecycle/implementation/effectiveness/assessment/ type/enforcement/framework/owner plus flag filters; active filters show as removable chips; search is debounced; pagination/sorting are server-side.

Creating a control · validation

The reference (CTL-####) is generated server-side (concurrency-safe). New controls start as Draft. Validation distinguishes blocking errors from advisory warnings:

Lifecycle & approval workflow

Reject requires a reason (→ Draft). Retire requires a reason and returns an impact summary; the control stays visible in historical reporting. Delete is GRC-administrator-only and limited to draft & unreferenced controls — anything with references or history is retired, never physically deleted. Every transition is recorded in the status history + audit trail.

The details drawer (10 tabs)

Framework mappings — requirement-driven

Mappings link a control to real framework requirements — you never type a reference.

Assessments · evidence coverage · config signal

• Assessments (POST /controls/{id}/tests): date, result, method, reviewer, population/sample, notes. A fail auto-raises a linked corrective-action Issue. Approval by a different user sets effectiveness.
• Evidence coverage: read-through of the Evidence module — required / approved-valid / missing / expiring / expired + coverage %. Rejected and expired artifacts are never counted as valid.
• Configuration-Compliance signal: for a control mapped to requirements that config checks also cover, the latest results roll up into an informational pass/partial/failsignal on the Assessments tab. It is a signal only — it does not set effectiveness.

ISMS SoA integration

ISMS coverage is derived from the authoritative Control Library: a requirement isimplemented when a mapped control has implementation_status='implemented'(lifecycle active alone is not proof), and a control is effective wheneffectiveness='effective' (its latest approved assessment). These roll up into the SoA implementation-coverage / control-effectiveness / evidence-coverage percentages.

Exports & reports

All server-side and permission-aware (controls:export), each writing an audit event; evidence file contents are never exported: current filtered view, full library, framework mapping report, control assurance report, evidence gaps report, overdue reviews report.

Migration & backfill (existing installs)

New columns are added additively on startup and a one-time, idempotent backfill maps the legacystatus onto the four new fields — conservatively (it never claims implementation/effectiveness the legacy record doesn't evidence). Back up the database before the first migrated start.

Troubleshooting

16Evidence Implemented

Use the v1 evidence API: multipart upload with checksum/size/mime, source (manual/automated), owner, validity (valid_from/valid_until), approval withseparation of duties (submitter ≠ approver, mandatory reject comment), and an audit trail. Map evidence to controls/requirements/risks. Track expiry to keep evidence current.

17Remediation

Remediation spans Actions (actions.html), config-compliance tasks, risk tasks and CAPA. Tasks carry owner, due date, priority and source. Config-compliance auto-verifies and closes the risk/task when the check later passes.

18Exceptions Implemented

Config-compliance exceptions (risk acceptance, expiry, active = counts compliant), DLP exceptions (multi-level security/compliance/admin approvals that short-circuit enforcement), data-classification and policy exceptions. Give every exception an expiry and review it — automatic expiry-enforcement is Partial.

19ISMS (ISO/IEC 27001) Implemented

The ISMS module is a governance & assurance overlay: it references and aggregates the platform's authoritative modules (CMDB, Risk Register, Control Library, Evidence, Audit, Documents, Configuration Compliance) instead of keeping duplicate registers. Every dashboard metric carries its source and calculation. Surface: isms.html; /api/v1/isms/*. Full detail lives in the dedicated ISMS Administration Guide.

Permissions. View = any authenticated user; create/update = Compliance Manager (rank 2); approve / activate / seed Annex A = GRC Admin (rank 3). Every state change is audited.

Information Asset Register — the canonical manual register

The Information Asset Register is the single, canonical record of the organisation'smanually-governed information assets (data sets, databases, documents, systems, physical media). It is distinct from the CMDB (discovered technical assets) — the register reuses CMDB assets as supporting dependencies, never duplicates them. Menu:Compliance & Controls → ISMS → Information Assets. Surface: isms.html (tab);/api/v1/isms/assets*.

Fields (manual · computed · discovered)

Manual (user-entered): asset ref (IA-####, auto or manual, unique), name, purpose, description, nature (digital/physical) & detailed type, storage/location, eight explicit Yes/No sensitive-data indicators (PII · bank/payment/insurance · biometric · salary · commercial · risk/incident/audit/vuln · board/committee minutes · other — the last requires a description),is_regulated + regulation types (orthogonal to classification), owner & internal users & external parties, business-process & supporting-asset links, C/I/A/Cr, retention (value + unit), status, review date.Server-computed (never client-trusted): total = C+I+A+Cr, the 4-level classification, completeness %.Proposed by discovery/classification (advisory): automated file-scan findings may proposea higher classification; they never silently lower an approved one — conflicts surface as review items.

Valuation & classification

C/I/A/Cr (each 1–5) are recorded as a versioned InformationAssetValuation (reused, not duplicated): editing them creates a new version and supersedes the prior — only one is current per asset; assessor/approver/status/rationale are retained; history is one click away. Classification is the higher of the total-band and the confidentiality band, on a strictfour-level scale:

A sensitive-data flag forces C=5 → Restricted. The form shows a live preview (total-band, C-band, final, driver, explanation); the server always recomputes and validates.

Relationships

Four normalized many-to-many links (no comma-separated ID text), each scope-validated, deduped and audited: supported business processes (BCM Register), supporting assets (CMDB),internal users (users / departments / roles), external parties (registered vendors or a controlled free-text fallback). Managed from the asset's detail drawer with searchable selectors. An asset cannot be deleted while linked risks or active relationships exist — archive it instead.

Roles, audit & export

Permissions (module information_assets): Administrator / GRC Admin = full; CISO & Asset Manager = manage + approve (no delete); Risk Manager, Compliance Manager & Auditor = read + export; others = none. Every write is audited (isms.asset.*) with actor, timestamp, entity and changed fields. Export is a formula-injection-safe, UTF-8 CSV (audited) with the current valuation's C/I/A/Cr, total and classification. The list shows readable owner names (not raw ids), completeness and relationship counts.

Full field/API/migration detail: docs/information_asset_register/.

20Endpoint Agent Implemented

A real OS service (grc_agent/ + Windows MSI): registers over TLS with token rotation, runs collectors (asset/software/compliance/logs/data/classification/DLP), buffers offline, self-updates (pilot/test/prod rings) and reports health via heartbeat.

21DLP Decision engine

22AI Governance Not Found

There is no AI Governance subsystem today (only a reserved RBAC slot + a dead-link menu item).Recommendation: build it as a new domain module that reuses the existing Risk, Policy/Control, Evidence, Task and Audit engines — AI asset register, Shadow-AI discovery, AI-usage policy, AI risk assessment (new collectors/rules), findings + remediation + audit. Do not duplicate the risk/task/evidence systems.

23Audit & Logs Implemented

Central event_logger → EventLog with automatic secret masking (passwords/tokens/JWT/PAN→last4/IBAN/email); a second GRCAuditLog stream records admin/GRC entity changes. Categories: auth, authz, admin, rbac, api, security, document, workflow, risk, compliance, dlp, agent, siem. Critical events forward to SIEM via a durable queue (LEEF/QRadar).

24Reports XLSX / CSV

Multi-sheet XLSX (executive / risks / control-effectiveness / vendor-risk / issues / audit-findings / evidence-freshness / KRI) + CSV. Per-module CSV exports (assets, software, inventory, accounts, config-compliance). PDF reports and scheduled reports are Not Found.

25Notifications Implemented

Rule-driven dispatcher matches enabled alert rules, evaluates conditions, resolves recipients (by user, role, or record owner/assignee/creator) and fans out to in-app + email (SMTP, encrypted password, templates, delivery log, retry, daily limit) honoring per-user preferences. Wired events: new host discovered, credential failed, auto-created risks. Create additional alert rules for: asset down/stale, unauthorized software, new privileged account, sensitive data found, failed compliance check, overdue remediation, expired exception.

26Settings

Settings are distributed: per discovery profile, per-asset refresh schedules, the credential vault, risk-automation rules + severity weights, alert rules + SMTP + per-user prefs, global + per-agent agent config, per-policy DLP enforcement mode + connectors. Evidence/audit retention is Planned.

27Operational Workflows

28Best Practices

• Assign an owner + business unit to every CMDB asset.
• Scope discovery profiles tightly; schedule scans off-peak; use least-privilege read-only credentials.
• Trust thresholds before marking assets DOWN; never auto-delete — use the retire queue; owner-review uncertain matches.
• Keep evidence current (watch valid_until); give exceptions an expiry.
• Review credential failures, stale assets, new privileged accounts and agent health regularly.
• Prefer /api/v1/* (SoD + audit); forward critical events to SIEM; enable the tamper-evident chain for high assurance.

29Troubleshooting

30Admin Checklists

Initial setup

1. Create admin + break-glass accounts; enforce MFA.
2. Connect Entra/LDAP (optional).
3. Create external frameworks (ISO/NIST/CIS/PCI) — not seeded.
4. Add vault credentials (least-privilege); create scoped discovery profiles.
5. Configure inventory-refresh schedules; upload + approve benchmarks; assign to assets.
6. Define risk-automation rules; create alert rules; configure SIEM forwarding.
7. Deploy agents to critical hosts; set retention operationally.

Daily

Dashboard · failed discovery jobs · credential failures · high-risk findings · overdue remediation · agent health · DLP high-severity events.

Weekly

New hosts · unauthenticated hosts · stale assets · software changes · account privilege changes · failed compliance checks · risk updates.

Monthly

Risk register · policy/control compliance · evidence expiry · exceptions · admin users · service credentials · management reports.