Review Lifecycle¶

Overview¶

When an access grant's decay score crosses a configurable threshold, Verity generates a review — a structured decision workflow that routes evidence to the right person, tracks response time against SLAs, and executes the outcome safely.

Reviews are the human decision point in the access-decay pipeline. Verity does not blindly revoke access; it provides evidence and asks the people closest to the resource to make an informed decision.

stateDiagram-v2
    [*] --> PENDING : Score threshold crossed
    PENDING --> IN_REVIEW : Reviewer opens packet
    IN_REVIEW --> DECIDED : Reviewer submits decision
    DECIDED --> EXECUTED : Remediation completes
    EXECUTED --> [*]

    IN_REVIEW --> ESCALATED : SLA breached
    ESCALATED --> IN_REVIEW : Escalation assignee opens
    PENDING --> ESCALATED : No response after reminder

    DECIDED --> FAILED : Remediation error
    FAILED --> DECIDED : Retry / manual fix

What Triggers a Review?¶

Reviews are created through three mechanisms:

Score Threshold (Automatic)¶

The primary trigger. When a grant's decay score crosses the configured threshold (default: 50), the Review Generator creates a review automatically.

Scheduled Campaign¶

Organisations that require periodic certification (e.g., SOX compliance) can configure scheduled campaigns that generate reviews for all grants matching a filter — regardless of decay score.

Scheduled campaigns complement continuous scoring; they ensure 100 % coverage even for grants that Verity's model has not yet flagged.

Manual Request¶

Any authorised user can request a review of a specific grant, identity, or resource through the API or dashboard. This is useful for:

• Investigating a specific user during an incident
• Reviewing all access to a resource before decommissioning
• Ad-hoc audits requested by compliance

The Evidence Package¶

Every review includes an evidence package — a self-contained bundle of data that gives the reviewer everything they need to make an informed decision without having to investigate independently.

Review Routing¶

Reviews must reach the person with the best context to make the decision. Verity uses a three-tier routing model:

graph TD
    RG["Review Generated"]

    RG --> T1{"Resource owner<br/>defined?"}
    T1 -->|Yes| RO["Route to<br/>Resource Owner"]
    T1 -->|No| T2{"Team lead<br/>identifiable?"}
    T2 -->|Yes| TL["Route to<br/>Team Lead"]
    T2 -->|No| SEC["Route to<br/>Security Team"]

    RO --> SLA["SLA Timer Starts"]
    TL --> SLA
    SEC --> SLA

    SLA --> T3{"Response within<br/>reminder window?"}
    T3 -->|Yes| DECIDE["Reviewer Decides"]
    T3 -->|No| REM["Send Reminder"]
    REM --> T4{"Response within<br/>escalation window?"}
    T4 -->|Yes| DECIDE
    T4 -->|No| ESC["Escalate to<br/>Next Tier"]
    ESC --> SLA

    style RG fill:#536dfe,color:#fff,stroke:none
    style RO fill:#448aff,color:#fff,stroke:none
    style TL fill:#448aff,color:#fff,stroke:none
    style SEC fill:#448aff,color:#fff,stroke:none
    style DECIDE fill:#4caf50,color:#fff,stroke:none
    style ESC fill:#f44336,color:#fff,stroke:none

Tier 1: Resource Owner¶

The person or team listed as the owner of the target resource. This is typically populated from the upstream system's metadata (e.g., the repository owner in GitHub, the resource group owner in Azure).

Tier 2: Team Lead¶

If no resource owner is defined, the review routes to the team lead of the user whose access is under review.

Tier 3: Security Team¶

The fallback. If neither a resource owner nor a team lead can be identified — or if escalation is triggered — the review routes to the configured security team.

SLA Tracking¶

Every review is backed by a Temporal workflow that enforces time-bound SLAs:

Temporal Workflow¶

sequenceDiagram
    participant RG as Review Generator
    participant TW as Temporal Workflow
    participant RV as Reviewer
    participant NT as Notifications
    participant RM as Remediation

    RG->>TW: StartWorkflow(review_packet)
    TW->>NT: SendNotification(reviewer, packet)
    TW->>TW: Timer: reminder_window

    alt Reviewer responds before reminder
        RV->>TW: SubmitDecision(approve/revoke/reduce)
        TW->>RM: ExecuteDecision(action)
    else Reminder fires
        TW->>NT: SendReminder(reviewer)
        TW->>TW: Timer: escalation_window
        alt Reviewer responds
            RV->>TW: SubmitDecision(decision)
            TW->>RM: ExecuteDecision(action)
        else Escalation fires
            TW->>NT: Escalate(security_team)
            TW->>TW: Timer: max_review_time
        end
    end

Decision Options¶

Reviewers choose from four actions:

Review States¶

Every review transitions through a well-defined state machine:

Bulk Reviews¶

Large organisations may have thousands of reviews generated simultaneously — for example, after onboarding a new connector or running a scheduled campaign. Review fatigue is a real risk.

Verity mitigates this with smart batching:

Grouping¶

Reviews are grouped by:

1. Reviewer — A single person sees all their reviews in one batch.
2. Resource — Reviews for the same resource are grouped together.
3. Risk level — CRITICAL reviews surface first.

Bulk Actions¶

Reviewers can apply a decision to multiple reviews simultaneously:

• "Revoke all access for users who haven't logged in for 180+ days."
• "Approve all access for users in the same team who are still active."

Fatigue Detection¶

Verity monitors reviewer behaviour for signs of rubber-stamping:

Next Steps¶