64 lines
8.5 KiB
Markdown
64 lines
8.5 KiB
Markdown
# Accepted Risk: decision record and storage contract
|
||
|
||
Status: implemented local documentation workflow; authenticated organizational approval remains a 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](https://csrc.nist.gov/pubs/sp/800/37/r2/final) and the [NIST RMF Authorize step](https://csrc.nist.gov/Projects/risk-management/about-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.
|
||
|
||
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.
|
||
|
||
## Implemented persistence
|
||
|
||
The authoritative record is `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`.
|
||
|
||
No SQL migration is needed for this implementation. 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.
|
||
|
||
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 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.
|
||
|
||
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. Dedicated `risk_acceptances`, `risk_acceptance_revisions`, `risk_acceptance_approvals` and `risk_acceptance_evidence` tables with immutable event IDs, project/occurrence foreign keys, actor IDs and server timestamps. Migrate current JSON history 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.
|