Skip to content

docs: Risk Acceptances 2.0, and the risk-acceptance parts of Rules Engine 2.0 - #15632

Open
devGregA wants to merge 16 commits into
devfrom
sc-14181_risk_acceptances_2_docs
Open

docs: Risk Acceptances 2.0, and the risk-acceptance parts of Rules Engine 2.0#15632
devGregA wants to merge 16 commits into
devfrom
sc-14181_risk_acceptances_2_docs

Conversation

@devGregA

Copy link
Copy Markdown
Contributor

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.md gains a Risk Acceptances 2.0 section covering:

  • The lifecycle — proposed, under review, approved, rejected, active, expired, and which moves are legal from each. Risk Acceptances created before the feature read as active, which is what they are.
  • Who can do what — requesting an exception and deciding one are separate permissions, so the person who asks is not automatically the person who agrees. Includes the rule that the requester cannot be their own approver, and the system setting that relaxes it.
  • Extending an expired acceptance — an expiration date exists because somebody wanted the risk looked at again, so by default extending one goes back through review. Explains the 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.
  • A read-only auditor — how to build the persona with a custom role holding only Risk Acceptance View, what it can read, and why no built-in role changes.
  • Requested exceptions in your metrics — why a Finding awaiting a decision stays active and counted, and how it is told apart from work nobody has looked at.
  • The record of what was accepted — the durable acceptance history that survives expiry and reimport.
  • Standing acceptances — matching criteria, and that matching stops when the acceptance stops being active.
  • The review thread — decisions and comments as one time-ordered conversation.
  • Notifications and webhooks — which events fire, who they go to, and the webhook payload carrying the state change itself rather than a sentence to parse.
  • Reports — the approval chain columns, and why they are empty for acceptances made before the workflow existed.
  • Backlog metrics — what each number means, including the distinction between overdue (past its date and still suppressing Findings) and expired.
  • API — the state and transition endpoints, the request-an-exception endpoint, and the acceptance-history endpoint.

automation/rules_engine_2/building_rules.md and node_reference.md gain 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

  • Every behaviour described here is either already in the open-source code or is Pro behaviour reached through the documented API; the docs tree covers both, as it does today for other Pro features.
  • Sections state the flag-off behaviour wherever it differs, since the feature ships default-off.
  • No screenshots — the pages describe behaviour in words.

devGregA and others added 15 commits August 11, 2026 21:12
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>
@devGregA devGregA added this to the 3.3.0 milestone Aug 12, 2026
@github-actions github-actions Bot added the docs label Aug 12, 2026
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant