Assessor_2.0/docs/RISK_ACCEPTANCE.md

Accepted Risk: decision record and storage contract

Status: implemented whole-finding and Defender device-scoped application workflows; authenticated organizational approval remains a phase-14 server-readiness requirement.

Purpose and basis

Accepted Risk records an explicit, bounded business decision about a finding. It does not turn a failed scanner result into Passed, remove the finding, improve its technical score or waive a legal, contractual or policy obligation.

The workflow follows the separation of assessment evidence, accountable risk decisions, authorization conditions and monitoring described in NIST SP 800-37 Rev. 2 and the NIST RMF Authorize step. These are design references, not a claim of certification or a universally binding approval policy. No form can guarantee that a decision is legally or organizationally valid in every context.

User decision, 2026-09-10: no existing organizational approval rules; provide a best-practice starting point. The application therefore requires a named risk owner and a different named approving authority with separate contacts, explicit approval evidence, a bounded validity period and a future review date. It does not invent a universal maximum acceptance duration or assume that a particular job title is authorized. Review frequency and acceptance duration must follow the documented exposure and business context.

Recorded information

• Exact scope: affected assets/systems and exclusions, with the canonical finding occurrence linked automatically.
• Risk scenario, likelihood, business impact, initial risk, residual risk and justification for the remaining exposure.
• Business rationale, alternatives considered, and risk-register/ticket reference.
• Compensating controls, accountable control owner and effectiveness evidence; explicitly justify absent controls.
• Risk owner, role/team and contact; independent approving authority, role/decision authority and contact.
• External approval date and an attributable approval evidence reference covering scope, residual risk and validity.
• Validity start, expiry, next review, monitoring arrangements and review owner, escalation/reassessment triggers, and exit/remediation milestones.
• Applicable policy, regulatory and contractual considerations and any consulted specialists or restrictions.
• Additional evidence references, recorder name, revision reason, server recording timestamp and complete prior decision snapshots.

For Microsoft Defender for IoT, the user-entered scope narrative is separate from an immutable system target. A device-finding target captures one exact stable device identity and one canonical CVE/finding definition. A device-snapshot target captures one exact stable device identity and every detailed actionable CVE in the selected active scan-run scope at decision time. Each covered member retains its canonical definition/CVE plus occurrence, scan-run, import-file, source-table and row provenance.

Evidence references are stored as inert text. The form neither uploads documents nor verifies their contents, signatures or availability. Source finding values and scanner provenance remain in the existing canonical model.

States and rules

draft, accept and revoke are persisted revision actions. A partial draft requires a recorder and revision reason. Recording acceptance requires all substantive fields except additional evidence references, distinct owner/approver identities as declared, valid dates, approval on or before the start, a non-retroactive start, future expiry, and a future review date within the validity period. Revocation requires a recorder, reason and a previous acceptance; it retains the accepted decision's original details.

Displayed states are derived at read/render time: Not recorded, Draft, Scheduled, Accepted, Review due, Expired, Revoked and Review required. Expiry dates are inclusive UTC calendar dates; a review becomes due on its specified date. No scheduler or notification service is implied. A new draft becomes the current decision state; earlier approvals remain in history. Renewal or changed scope requires a new recorded acceptance, never editing an earlier snapshot.

The existing review workflow (including the historical Actionable → accepted mapping) is separate and is not repurposed for risk acceptance. Ordinary review edits preserve the structured record. Accepted Risk does not automatically alter bookmarks, remediation status or technical dashboard numbers.

Effective Defender device/CVE coverage is the union of independent valid decisions. A current whole-finding acceptance covers every affected device for that CVE; a device-finding decision covers one device/CVE pair; a device snapshot covers only its captured CVE definitions. Accepted and visibly due Review due decisions provide current coverage. Draft, Scheduled, Expired, Revoked and Review required decisions do not. Revoking one overlapping decision never revokes another.

Implemented persistence

The authoritative whole-finding record remains FindingReview.riskAcceptance, an additive version-1 JSON object stored in the existing assessor_reviews.data JSONB column. It contains an append-only revisions array. Each revision contains action, complete details, sequential revision number, recorder, reason, original target occurrence ID, server-generated timestamp and approvalIdentityVerified: false.

Migration 028 adds the project-owned assessor_scoped_risk_acceptances table for device-scoped histories. Its indexed immutable target snapshot is stored with revision, timestamps and the complete append-only decision history in JSONB; project deletion cascades. Existing FindingReview.riskAcceptance records are unchanged and require no migration. Before applying 028, the canonical datastore was saved to backups/assessor-pre-028-20260921.backup; its custom-format archive catalog was readable and its SHA-256 is 0828CEEA875A00DF4D9613737445C4837D208FBD6D96EEFA988F6745FDAE4946. The canonical local datastore remains Docker project assessor-2_0, container assessor-2_0-postgres-1, database assessor, volume assessor-2_0_assessor-postgres-data, 127.0.0.1:5432. The browser never accesses PostgreSQL directly.

Writes use POST /api/v1/projects/:projectId/risk-acceptances with occurrence ID, command and expected review revision. The backend verifies project membership and validates the decision. PostgreSQL locks the occurrence and current review within the repository transaction, appends the snapshot and increments the review/repository revisions atomically. The local reference repository implements the same contract. General /reviews writes cannot introduce, replace, remove or retarget a risk acceptance history. Conflicts fail without overwriting the previous record.

Scoped reads and writes use GET and POST /api/v1/projects/:projectId/risk-acceptances/scoped. Creation accepts only a device-finding occurrence/device reference or a device-snapshot scan-run/device reference. The server verifies project membership, reconstructs targets through the shared Defender identity model, rejects unresolved or ambiguous identities, and derives the complete nonempty snapshot membership itself. Existing scoped decisions accept only revision commands: their target cannot be replaced. PostgreSQL row locks and optimistic revisions make grouped accept/revoke changes atomic. Ordinary review endpoints never write the scoped table. Project export includes both legacy and scoped histories, and application state loads scoped histories with the project workspace.

The UI reports successful storage only after the backend acknowledges the write. Disconnected/unsaved findings cannot record acceptance. Failed writes retain the dialog entries. Existing browser review caches and project snapshots can retain a copy; they are not the authority for acceptance. Exports include the complete structured review record. Existing project/scan deletion policies still apply: this is not an independent legal-hold archive.

Reimport and retention

The existing stable-identity review transfer preserves the complete whole-finding object and all original revision targets. It never matches by title or row position. If a replacement occurrence differs from the recorded target, the preserved acceptance displays Review required. A new decision can explicitly cover the replacement after reassessment. Failed or ambiguous matches retain the original review according to the reimport policy.

Scoped records are project-owned and do not transfer between projects. On a later import they provide coverage only when the exact stable Defender device key and canonical CVE definition both match a captured member. A new CVE, changed device key, unresolved identity or ambiguous identity is not carried forward. The snapshot itself never grows after creation. Existing datasets need no reimport when their retained Defender source observations can reconstruct the target; aggregate-only or older evidence without detailed CVE/device identity cannot be scoped and the action remains unavailable.

This refines preservation in docs/REIMPORT_POLICY.md: preserving a prior decision is not proof that a changed finding or new assessment is within its approved scope. Previous approvals, expiry dates and decision evidence must never be silently renewed.

Security limits and planned server extension

The current local-only application has no authenticated approver identity, organizational role registry, digital signing, independent evidence verification, trusted immutable storage or legal-hold enforcement. Distinct names/contact entries and an approval reference document an external decision; they do not prove authorization or enforce separation of duties between authenticated users. Same-origin protections and revision checks protect the application workflow, not against a database administrator. These limits remain visible in the dialog and prevent any claim of a tamper-proof or universally compliant approval.

Before organization-wide approval in the browser/server target, add:

1. SSO-bound actors and client-scoped authorization; configurable risk-owner/approver roles, thresholds, separation of duties and delegation rules.
2. Phase-14 governance tables for authenticated actors, immutable approval events and evidence records. Migration 028 is only the current project-owned scoped decision snapshot/history store; it does not provide authenticated actors, signing or legal retention. Any future migration must preserve both legacy review JSON and scoped histories without replacing historical declared identities with verified identities.
3. Evidence references with content hashes, access controls, immutable versions and an organization-approved retention/legal-hold policy. Do not add external storage or uploads without a security-model update.
4. Transactional approval/revocation endpoints, tamper-evident audit retention, server-side due/expiry queries and an explicitly configured notification/monitoring workflow.
5. Tests against a dedicated approved integration environment for concurrent approvals, permissions, clock boundaries, evidence retention and migration round-trips. An approved persistence migration requires a verified backup of the canonical datastore first.

These are acceptance criteria for the future governance extension in phase 14, not completed features. Phase 7 covers the dialog, phases 9–11 cover its storage/API contract, and phase 13 covers security validation. Existing phases are not reopened or marked complete by this scoped implementation.