docs: Risk Acceptances 2.0, and the risk-acceptance parts of Rules Engine 2.0 - #15632
Open
devGregA wants to merge 16 commits into
Open
docs: Risk Acceptances 2.0, and the risk-acceptance parts of Rules Engine 2.0#15632devGregA wants to merge 16 commits into
devGregA wants to merge 16 commits into
Conversation
A risk acceptance has had one state: as soon as it existed, its findings were accepted. That describes an organization where one person decides. It does not describe one where somebody requests an exception, somebody else approves it, and an auditor later asks who agreed to what and why. Documents the beta feature that adds that shape: the six states and which moves are allowed between them, why an active acceptance is expired rather than rejected, the split between the permission to request and the permission to decide, what happens to findings while a request is undecided, and the durable per-finding record that outlives the membership. Also documents the two endpoints -- state and transition -- including when a reason is required and what the refusals mean. Written against the behaviour as built, so it describes the flag being off as the default and unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…he history Four endpoints the first pass did not cover, because they did not exist yet: the one that asks for an exception without accepting anything, and the three that read a history the live membership cannot answer from. The request endpoint's existence needs explaining rather than just listing -- it is there because creating a Risk Acceptance the ordinary way accepts its Findings immediately, and an Active one deliberately cannot move back to Proposed, so create-then-transition is not a route to a request. Also states the visibility rule on the Finding-side history: Risk Acceptance visibility is a separate grant, so reading a Finding does not show you the exceptions raised against it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…es this Three additions for behaviour that now exists: the requester cannot approve or activate their own request (and the setting that relaxes it for a one-person approval chain), the Exception Requested badge on Finding rows, and where to find the request action and the Finding's Acceptance History tab. Says why rejecting your own request is still allowed -- it is a withdrawal, and needs nobody's agreement -- because that asymmetry looks like an oversight otherwise. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The feature that answers "we accepted this base-image CVE once, stop asking us again on every asset and rescan" -- which adding Findings by hand cannot, because the Findings arrive with the next scan. Documents the criteria shape, every matchable attribute, and the three rules that make it safe to leave on: active-only, in-scope-only, and refusing criteria that have a scope but nothing to match (which would mean "every Finding in this product"). Says explicitly that an acceptance with no criteria behaves exactly as before, because that covers every acceptance an upgrading install already has. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…itor Two additions: `ids` can be left empty and are filled in from the Findings the acceptance already covers -- which cannot widen anything, since that is where it is already accepting -- and where to edit criteria in the UI. Says what the editor asks for (breadth, not ids) because that is the difference between a one-click scope and hunting through a list of thousands of assets. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both routes, because there are two and only documenting one would make the other look like a loophole: the reinstate endpoint, and changing the expiration date on an expired Risk Acceptance, which reinstates it as a side effect. Says what is still an ordinary edit, so the rule does not read as "expired Risk Acceptances are read-only". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Five condition paths a rule can use once both features are on, with what each one says rather than just its name -- the useful ones are not obvious from the field names alone. Calls out two things a rule author would otherwise discover by accident: days_to_expiry goes negative once the date has passed (so "expired 3 days ago" is expressible, and "expiring within 7 days" does not silently also match everything long overdue), and the fields describe the earliest acceptance when a Finding is in several. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…payload Two events, who each one goes to, and why activation/expiry/reinstatement are deliberately silent -- that last one reads as an omission otherwise. Shows the webhook body, because the point of the payload is that a subscriber gets the state change rather than a sentence to parse. Says plainly that notifications are reinforcement: the state change is visible on the Risk Acceptance regardless, and a failed send does not undo a decision. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…hat needs attention Two behaviours a reader cannot guess. An expired Risk Acceptance no longer goes straight back into force: the expiration date exists because somebody wanted the risk looked at again, so extending it is another review. The page says what the 409 means, that the older reinstate route refuses for the same reason rather than being a way around it, and which setting turns it off. The two new list filters get a section because they answer questions people already ask this data: what lands on somebody's desk this week, and what have we accepted on this host -- the latter being what gets asked when a host is decommissioned or turns up in an audit. Also records the boundary that keeps the two systems honest: the setting governs what a person may ask for through the API, while open source stays the authority on whether an acceptance has expired. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Says what the thread is (decisions and comments in one time-ordered conversation), why it is one list rather than two panels, and the two things a reader would otherwise have to discover: the comments are ordinary Risk Acceptance notes, so older ones are already there and new ones show up everywhere else those notes do, and line breaks survive. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… rule action The behaviour a reader cannot guess: over the limit the Finding is not accepted and not dropped either -- it becomes a Risk Acceptance awaiting review, still active and still counted. Includes the two asymmetries (an unrecognisable severity is treated as over the limit, an unrecognisable limit is ignored) and what happens with the feature flag off. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Explains what each number means and, more importantly, which question it answers -- particularly the two that are easy to confuse: `overdue` is past its date and still suppressing findings, which is not the same set as `expired`, and `average_days_to_decision` counts only decided requests so that filing a new one cannot improve the figure. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four new Risk Acceptance report columns, and the two things a reader would otherwise misread: they are empty for acceptances made before the workflow existed (deliberately, rather than falling back to a typed field), and moves that are not decisions are ignored so the column names whoever agreed rather than whoever last touched the record. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The RA page described these from the risk acceptance side, but a rule author looks in the rules docs. Adds the acceptance condition paths to Referring to Finding data, and the severity limit to the Accept Risk node reference, each cross-linking to the Risk Acceptances 2.0 page. Says the two things that are not guessable: over the limit a Finding is neither accepted nor dropped but sent for review, and with the feature off the condition fields read empty so a rule matches nothing rather than acting on a lifecycle the install does not use. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A custom role holding Risk Acceptance View and nothing else, rather than any change to the built-in roles. Says what such a role can read, that every write is refused, that visibility stays scoped to the auditor's own Assets, and that a plain Reader is unaffected -- acceptance visibility is a separate grant from Finding visibility on purpose. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The relative form resolved one directory short from /automation/rules_engine_2/<page>/ and the link checker failed the build. Every other cross-reference in the tree is absolute; match it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation for Risk Acceptances 2.0, the Pro exception-management lifecycle, plus the risk-acceptance parts of the Rules Engine 2.0 reference.
Docs only — no code changes.
What is documented
triage_findings/findings_workflows/PRO__risk_acceptance.mdgains a Risk Acceptances 2.0 section covering:409, that the older reinstate route refuses for the same reason rather than being a way around it, and the setting that turns the requirement off.Risk Acceptance View, what it can read, and why no built-in role changes.overdue(past its date and still suppressing Findings) andexpired.automation/rules_engine_2/building_rules.mdandnode_reference.mdgain the risk-acceptance parts of the rules engine: the acceptance condition paths, and the Accept Risk action's severity limit — including what happens to a Finding over that limit, and that the condition fields read empty when the feature is off so a rule matches nothing rather than acting on a lifecycle the install does not use.Notes for review