Business rules catalog
A reference for every "if X then Y" rule that runs in the background and changes something a customer sees. If a status flips, an email lands, a scan stops, or a finding moves on its own, the rule is documented here.
These rules are not configurable per tenant unless the row says so. They run on the same schedule for every workspace.
Agent fleet rules
Heartbeat windows govern when the Online / Offline badge changes on Settings → Agents and when the team gets paged. Email recipients are users whose role includes the Create, rotate, and revoke agent tokens permission.
| Rule | Window | What changes |
|---|---|---|
| Agent shown as Offline in the dashboard | No heartbeat for more than 20 minutes (two missed cycles at the 10-minute heartbeat rate) | The agent row badge flips from Online to Offline. No email yet. |
| First Agent Offline email | Agent has been Offline for more than 1 hour | One email per agent to every user with Create, rotate, and revoke agent tokens. The agent is marked alerted so the system stops re-paging on each 5-minute pass. |
| Daily "still offline" reminder | Agent stayed Offline, and 24 hours have passed since the last reminder | One follow-up email per agent. Repeats every 24 hours until the agent comes back. |
| Agent restored email | Agent heartbeats again after a prior offline alert | One all-clear email per agent. The alerted flag clears so a future outage starts the cycle fresh. |
| Install token expiry | Token unused for 60 minutes | Token can no longer install an agent. Generate a new one from Settings → Agents → New Token. |
The heartbeat check runs every 5 minutes. A new outage will trigger its first email between 60 and 65 minutes after the last heartbeat.
See Retrievy Agent fleet for the agent management workflow.
Security exception rules
Security exceptions are time-bound. The system reminds the team before an exception expires and reopens findings when it does.
| Rule | Trigger | What changes |
|---|---|---|
| Expiring exception reminder | An exception's expiry date is exactly 7 days away | One email per affected finding to every user authorized to see that finding. The email runs once per exception. |
| Expired exception cleanup | An exception's expiry date has passed | The exception record is deleted. Every affected finding flips from Risk Accepted back to Open, with the audit trail entry showing the change came from an expired exception. |
| Global rule cascade on expiry | An expired exception had Global rule scope | Every sibling finding that shares the same check rule and was riding on the same exception flips back to Open at the same time. |
| Project item restoration | An expired exception had frozen a remediation project item | The project item returns to Pending, so the team sees it back on the project board. |
The reminder job runs daily at 08:00 in the workspace timezone. The cleanup job runs daily at midnight in the workspace timezone, plus an hourly sweep so a finding does not stay frozen until the next overnight pass.
See Security Exceptions for the registry workflow.
Drift alert rules
Drift alerts batch related cloud or on-prem changes into one email instead of paging on every event.
| Rule | Window | What changes |
|---|---|---|
| Roll-up window | 30 minutes from the first drift event in a data source | Every drift event detected within the window is grouped into one notification. |
| Send delay | Up to 5 minutes after the window closes | The dispatcher runs every 5 minutes, so a window closing at 14:30 mails between 14:30 and 14:35. Maximum delay from the first event to the email is 35 minutes. |
| Per-window dedupe | Each roll-up window is marked notified before the email goes out | The same window is never mailed twice. Retrievy drops one notification rather than risk an alert storm if something fails mid-send. |
| Mutation cap per email | Up to 60 mutation rows per window | If the window has more, the email lists the first 60 sorted as removed first, then added, then modified, and ends with a "+N more" summary. |
| Drift history retention | 7 days | Drift events and closed windows older than 7 days are purged daily at midnight in the workspace timezone. |
Drift alert recipients are users whose role includes the Create, rotate, and revoke agent tokens permission, the same group that receives heartbeat alerts.
Scan rules
A scan that never finishes blocks the queue and freezes the dashboard. These rules clean up stuck work.
| Rule | Threshold | What changes |
|---|---|---|
| Stuck Pending scan | Scan sat in Pending for more than 30 minutes without progress | The scan flips to Failed with the message "Scan timed out while pending in queue." Findings from the previous successful scan stay in place. |
| Stuck Running scan | Scan in Running or processing payloads for more than 4 hours | The scan flips to Failed with the message "Scan exceeded maximum execution time (4h)." |
| Concurrent scanner cap | One scan per workspace on Essentials, three on Advanced and Build Your Own | Additional scans queue until a slot frees up. |
| Queue priority | Best effort on Essentials, Standard on Advanced and Build Your Own | Best effort scans run when the platform has spare capacity. Standard scans take precedence. |
| Daily scheduled scan | Once per day at 23:00 in the workspace timezone | The platform queues one scan per eligible data source. |
The cleanup pass runs every 5 minutes. A stuck scan will be failed between 30 and 35 minutes after it stalled (or between 4 hours and 4 hours 5 minutes, for the long timeout).
For the per-plan numbers, see Plan feature matrix.
Assignment rules
When a teammate claims a finding, takes it on for verification, or sits on it too long, the assignment service decides who owns the work next. The rules below apply to every finding on the Kanban Triage board and inside remediation projects.
| Rule | Threshold | What changes |
|---|---|---|
| Stale claim auto-release | A claimed finding sat in Pending Verification for longer than the Claim timeout setting (default 14 days) | The claim releases. The finding returns to unassigned. The prior owner receives a "Stale claim released" notification. |
| Auto-claim on Mark as Fixed | An unassigned finding is marked fixed by a user, and the workspace has Auto-claim on Mark as Fixed enabled (default on) | The actor becomes the claimant before the status flips to Pending Verification. |
| Team collapse on commit | A shared finding (multiple co-assignees) gets claimed by one user | All other co-assignees are removed and notified that the work was taken on. |
| Project auto-assign | A finding is added to a remediation project | If the project has one assignee, the finding commits to them. If it has more than one, the finding becomes shared across the project's team. |
| Project member added | A new member joins an active project | The new member becomes a co-assignee on every still-active finding in that project. Committed findings stay with their current owner. |
| Project member removed | A member is removed from a project | The member is removed as co-assignee from that project's findings, unless another active project that links the same finding also lists them. |
| Deactivated user cleanup | A workspace user is deactivated | Every committed and shared claim held by that user is released, so the work does not stay locked. |
| Manual override release | A user with the Force-release or reassign someone else's claim permission reassigns or releases a finding | The previous claimant is notified that the claim moved, with the reason recorded in the audit trail. |
The stale claim sweep runs hourly per workspace. The Claim timeout is editable on Settings → Assignment.
See Hardening Kanban for the board where these rules play out and Remediation Projects for project ownership.
Status transition rules
The status of a finding is controlled by a small set of allowed transitions. Manual transitions to a Resolved badge are blocked. Resolution must come from a scanner re-check ("trust but verify").
| From | To | Trigger |
|---|---|---|
| Open | Pending Verification | A user clicks Mark as Fixed on the finding. |
| Reopened | Pending Verification | A user clicks Mark as Fixed on the finding. |
| Open or Reopened | Risk Accepted | A user completes the Accept Risk flow and a Security Exception record is created. |
| Pending Verification | Open | The current claimant clicks Release claim without marking the finding fixed. |
| Pending Verification | Resolved (Verified) | The next scan ran the check and found the issue gone. |
| Pending Verification | Reopened | The next scan ran the check and the issue is still present. Reopen count increments. SLA clock resets per severity. |
| Open or Reopened | Resolved (Automated) | The next scan ran the check and found the issue gone without anyone marking it fixed (resource deleted, auto-remediated upstream). |
| Resolved (Verified) or Resolved (Automated) | Reopened | The next scan detected the issue came back. |
| Risk Accepted | Open | The exception was revoked from the registry, or its expiry passed and the cleanup job ran. |
Manual flips to Resolved (Verified) or Resolved (Automated) are rejected at the service boundary. The scanner is the only actor that can write a Resolved badge.
See Findings lifecycle for the full state diagram and how each transition affects the Retrievy Index.
Plan eligibility rules
Scheduled work is gated by the workspace's billing state. A workspace whose subscription is not in a scan-eligible state does not consume scan capacity, but its data stays intact so cleanup, retention, and exports continue to run.
| Billing state | Scheduled scans | Snapshots, cleanup, retention | Sign-in |
|---|---|---|---|
| Active (paid and current) | Run | Run | Allowed |
| Trialing (trial active) | Run | Run | Allowed |
| Canceling (canceled, end of cycle pending) | Run until cycle end | Run | Allowed |
| Past due (payment failed, in dunning) | Paused | Run | Allowed (read-only) |
| Paused | Paused | Run | Allowed (read-only) |
| Canceled (in 30-day grace) | Paused | Run | Allowed (read-only with Reactivate Subscription banner) |
| Disputed (chargeback in progress) | Paused | Run, exports blocked | Allowed (read-only) |
| Unpaid (dunning exhausted) | Paused | Run | Blocked |
| Expired | Paused | Run, exports blocked | Blocked |
| Purged | Paused | Stopped | Blocked |
The billing-state filter runs in the scheduler when it dispatches the daily scan job. Exception cleanup, drift cleanup, snapshots, and retention pruning ignore the filter and run for every workspace, so data continues to age out cleanly during a grace window.
See Plans and pricing for the full flow when payment fails, including the 30-day reactivation window.