Exception Approval Workflow

Audience: security and release-governance owners who request, approve, or audit policy exceptions, and developers working on the Policy exception subsystem (src/Policy).

Reconciliation status (verified against src/Policy): This flow was rewritten to match the implemented exception subsystem. The implementation provides two related surfaces:

1. Exception Objects — /api/policy/exceptions (lifecycle CRUD + governed state machine). Code: StellaOps.Policy.Engine/Endpoints/Gateway/ExceptionEndpoints.cs and the StellaOps.Policy.Exceptions library.
2. Exception Approval Requests — /api/v1/policy/exception (gate-level multi-approver workflow). Code: StellaOps.Policy.Engine/Endpoints/Gateway/ExceptionApprovalEndpoints.cs, StellaOps.Policy.Engine/Services/ExceptionApprovalRulesService.cs, and the ExceptionApprovalRequestEntity / ExceptionApprovalRuleEntity persistence models.

Both surfaces are mapped by the Policy Engine (Program.cs: MapExceptionEndpoints()

• MapExceptionApprovalEndpoints()). The separate Policy Gateway host was withdrawn; the Engine serves its routes. Org-role concepts such as “Team Lead”, “Security Team”, and “CISO” are not system actors — they exist only as configurable approver role strings in gate-level rules (code-owner, delivery-manager, product-manager, ciso).

Automatic expiry and expiry-warning emission are implemented as in-process hosted BackgroundService workers (ExceptionExpiryWorker, ExceptionLifecycleWorker); expiry warnings are emitted to the unified audit/Timeline emitter (IExceptionNotificationService, disabled by default), not the standalone src/Notify module. See Expiration & Lifecycle. (A prior reconciliation pass incorrectly stated these were absent.)

Overview

The Exception Approval Workflow describes how StellaOps handles policy exception requests, from submission through gate-level approval, time-limited validity, and expiry. Exceptions are first-class auditable entities (not suppression files or UI toggles) with full lifecycle tracking, immutable event history, and deterministic evaluation.

Business Value: Maintain security governance while allowing controlled, time-bounded exceptions for legitimate business needs, with a complete audit trail and enforced separation-of-duty.

Actors

No external Scheduler/JobEngine dependency: expiry and lifecycle transitions run as in-process hosted workers in the Policy services (not as JobEngine jobs). Expiry warnings are emitted to the unified audit/Timeline emitter, not to the standalone src/Notify channel-dispatch module (no email/Slack templates exist). See Expiration & Lifecycle and Not Implemented / Roadmap.

Prerequisites

• Caller authenticated with the appropriate scope (see Authorization).
• Tenant context present (all endpoint groups call RequireTenant()).
• For the gate-level workflow: approval rules exist for the tenant, or the built-in per-gate defaults apply.

Authorization

Scopes are sourced from the canonical catalog (StellaOps.Auth.Abstractions/StellaOpsScopes.cs). Note the two surfaces use different scopes.

Exception Objects (/api/policy/exceptions)

Exception Approval Requests (/api/v1/policy/exception)

Exception Object Model

An exception object (ExceptionObject) is a versioned, append-only-audited entity.

Status (lifecycle)

Proposed → Approved → Active → Expired
                       Active → Revoked
       Proposed/Approved/Active → Revoked   (early termination / rejection)

Type

Reason code (ExceptionReason)

false_positive, accepted_risk, compensating_control, test_only, vendor_not_affected, scheduled_fix, deprecation_in_progress, runtime_mitigation, network_isolation, other.

Scope (ExceptionScope)

At least one constraint must be set; multiple constraints combine with AND.

Gate-Level Approval Rules

The approval-request workflow (/api/v1/policy/exception) routes each request to a gate level (G0–G4). If no tenant-specific ExceptionApprovalRuleEntity is configured (and enabled), these built-in defaults apply (ApprovalRequirements.GetDefault):

Notes:

• Unparseable gate level defaults to G1; unparseable reason code defaults to other.
• Requested TTL is rejected if it exceeds the gate’s MaxTtlDays.
• G0 requests with MinApprovers == 0 are auto-approved at creation (CanAutoApproveAsync).
• A global MinJustificationLength (default 10) is enforced on every request.

Flow Diagram (gate-level approval request)

┌──────────────────────────────────────────────────────────────────────┐
│         Exception Approval Request Workflow (gate-level)               │
└──────────────────────────────────────────────────────────────────────┘

┌───────────┐                 ┌──────────────────────┐     ┌──────────────┐
│ Requester │                 │ Policy Engine         │     │  Approver(s) │
└─────┬─────┘                 └──────────┬───────────┘     └──────┬───────┘
      │ POST /request                    │                        │
      │  (justification, gate level,     │                        │
      │   scope, ttl, evidence)          │                        │
      │─────────────────────────────────>│                        │
      │                                  │ Resolve requirements   │
      │                                  │ (tenant rule || default)│
      │                                  │ Validate TTL/rationale/ │
      │                                  │ evidence/controls       │
      │                                  │───┐                     │
      │                                  │<──┘                     │
      │                                  │ If G0 / MinApprovers==0 │
      │                                  │ → auto-approve          │
      │                                  │ Persist + audit         │
      │ 201 Created (EAR-…, status,      │                         │
      │   warnings)                      │                         │
      │<─────────────────────────────────│                        │
      │                                  │                         │
      │                                  │  GET /pending           │
      │                                  │<────────────────────────│
      │                                  │  (approver inbox)       │
      │                                  │  POST /{id}/approve     │
      │                                  │<────────────────────────│
      │                                  │ Validate action:        │
      │                                  │  - not already approved │
      │                                  │  - self-approval rule   │
      │                                  │  - in required list     │
      │                                  │  - role coverage        │
      │                                  │ Record approval; when   │
      │                                  │ MinApprovers met →      │
      │                                  │ status = Approved       │
      │                                  │                         │
      │                                  │  POST /{id}/reject       │
      │                                  │  (mandatory reason)      │
      │                                  │<────────────────────────│
      │                                  │                         │

Step-by-Step (gate-level approval request)

1. Create approval request

POST /api/v1/policy/exception/request (scope exceptions:request).

Request body (CreateApprovalRequestDto):

{
  "exceptionId": "EXC-… (optional link to an exception object)",
  "justification": "Upgrading lodash breaks the auth flow; need time to refactor.",
  "rationale": "Vulnerability requires prototype pollution not reachable in our usage.",
  "gateLevel": "G3",
  "reasonCode": "scheduled_fix",
  "evidenceRefs": ["sha256:…"],
  "compensatingControls": ["WAF rule blocking exploitation vectors"],
  "ticketRef": "JIRA-1234",
  "vulnerabilityId": "CVE-2024-1234",
  "purlPattern": "pkg:npm/lodash@*",
  "artifactDigest": null,
  "imagePattern": "docker.io/myorg/auth-service:*",
  "environments": ["production"],
  "requiredApproverIds": ["alice", "bob"],
  "requestedTtlDays": 14,
  "metadata": { "team": "auth" }
}

Server behaviour:

• Generates requestId = EAR-{yyyyMMdd}-{8 hex}.
• Resolves requirements (tenant rule if present and enabled, else gate default).
• Validates 1 ≤ TTL ≤ MaxTtlDays (days), rationale length, evidence/compensating-control presence, justification length, and required-approver count.
• Sets requestExpiresAt = now + 7 days (approval window, enforced at approve) and exceptionExpiresAt = now + requestedTtlDays.
• Auto-approves when the gate requires 0 approvers (G0).
• Records audit entry requested (sequence 1).

Response: 201 Created with the full ApprovalRequestDto (includes status, gateLevel, requestExpiresAt, exceptionExpiresAt, and any validation warnings, e.g. “No scope constraints specified.”).

2. Approver inbox

GET /api/v1/policy/exception/pending (scope exceptions:approve) returns requests where the caller is a required approver and has not yet approved.

3. Approve

POST /api/v1/policy/exception/{requestId}/approve (scope exceptions:approve).

ValidateApprovalActionAsync enforces:

• Request must be Pending or Partial.
• Caller must not have already approved.
• Self-approval rejected unless the gate allows it.
• The approval happens before exceptionExpiresAt and before requestExpiresAt. At or after either instant the approve answers 400 and the request is unchanged; the requester submits a new request. Nothing moves such a request to Expired: it stays listed as Pending until it is rejected or cancelled.
• If requiredApproverIds is non-empty, caller must be in it.
• Required roles are tracked toward completion.

When MinApprovers is reached (and outstanding required roles cleared), the request transitions to Approved. Optional comment is captured.

4. Reject

POST /api/v1/policy/exception/{requestId}/reject (scope exceptions:approve). Requires a non-empty reason. Only Pending/Partial requests can be rejected; transitions to Rejected (terminal). The reason is surfaced to the requester.

5. Cancel

POST /api/v1/policy/exception/{requestId}/cancel (scope exceptions:request). Only the original requestor may cancel (returns 403 otherwise); returns 400 if already resolved; 204 No Content on success.

6. Audit & rules

• GET /api/v1/policy/exception/{requestId}/audit — ordered audit trail (exceptions:read).
• GET /api/v1/policy/exception/rules — tenant approval rules (exceptions:read).

Step-by-Step (exception object lifecycle)

The /api/policy/exceptions surface manages the exception object directly.

Example: create exception object

{
  "type": "vulnerability",
  "scope": {
    "vulnerabilityId": "CVE-2024-1234",
    "purlPattern": "pkg:npm/lodash@*",
    "environments": ["production"]
  },
  "ownerId": "auth-team",
  "expiresAt": "2025-01-28T14:30:00Z",
  "reasonCode": "scheduled_fix",
  "rationale": "Upgrade breaks the auth flow; WAF mitigation in place while we refactor.",
  "evidenceRefs": ["sha256:…"],
  "compensatingControls": ["WAF rule deployed"],
  "ticketRef": "JIRA-1234",
  "metadata": { "team": "auth" }
}

Exception Enforcement (policy evaluation)

An exception object is effective only while its status is active and the current time is before expires_at (ExceptionObject.IsEffectiveAt). Where an exception object takes effect today:

• Release promotion gate: no effect. The Policy pack evaluation that Release Orchestrator calls for a promotion (PolicyRuntimeEvaluator) reads no exception object, so an exception object neither allows nor blocks a promotion, an approval or a deployment. The override for a release gate is Release Orchestrator’s own signed, time-limited gate exception, which its guard re-checks at approve and again at dispatch.
• Findings exposure. Findings reads active exception objects through the list route (HttpPolicyExceptionExposureReader).
• Lifecycle routes. Approve, activate and extend refuse an object whose expires_at has passed, whether or not the expiry worker has stored it as expired.

The library evaluator IExceptionEvaluator.EvaluateAsync (StellaOps.Policy.Exceptions) has no consumer in the product. Its only caller, the exception recheck build gate, and the exception adapter for runtime evaluation (AddPolicyExceptionIntegration) were never registered by the Policy Engine host and were withdrawn on 2026-10-11 (SPRINT_20261007_028 CCP-073). Given a FindingContext (artifactDigest, purl, vulnerabilityId, policyRuleId, environment, tenantId), the evaluator:

1. Queries active exceptions for the scope (GetActiveByScopeAsync).
2. Filters to those that truly match the context (exact match for digest / vuln ID / rule ID; wildcard PURL match; environment membership; tenant binding) and are IsEffectiveAt(now) (status Active and not past expires_at).
3. Orders matches by a specificity score (artifact digest 100 > exact PURL 50 > vuln ID 40 > policy rule 30 > wildcard PURL 20 > environment 10). The most specific match is the primary.
4. Returns HasException, all matching exceptions, the primary reason/rationale, and the union of evidence references.

Recheck Policy & Evidence Requirements (implemented, optional)

The StellaOps.Policy.Exceptions library defines additional governance primitives that an exception object may carry:

• RecheckPolicy(RecheckConditionType: ReachGraphChange, EPSSAbove, CVSSAbove, UnknownsAbove, …) — conditions that trigger re-evaluation. When triggered, the recommended RecheckAction can Block an exception (IsBlockedByRecheck) or RequireReapproval (RequiresReapproval).
• EvidenceHook(EvidenceType: FeatureFlagDisabled, BackportMerged, CompensatingControl, …) — mandatory/optional evidence requirements with freshness (MaxAge) and trust-score (MinTrustScore) constraints, validated by EvidenceRequirementValidator.

These are part of the model and library services only. The create and update requests carry no recheckPolicy and no route, worker or gate evaluates recheck conditions (the unregistered exception recheck build gate was withdrawn on 2026-10-11), so a triggered condition changes nothing today. See Recheck Policy Reference.

Expiration & Lifecycle

• Exceptions are time-bounded by expires_at (object) / exceptionExpiresAt (approval request). Object expiry is capped at 1 year at creation.
• An object stops being effective at its expires_at instant (IsEffectiveAt(now)), and from that instant approve, activate and extend refuse it, on the routes and in ExceptionService alike. The stored status changes to expired only when an expiry sweep next runs (the expiry worker hourly by default), so a list filtered on status=active can still return a lapsed object until then. The repository exposes GetExpiredActiveAsync() (active rows past expiry, every tenant), GetExpiredActiveAsync(tenantId) (one tenant) and GetExpiringAsync(horizon) / the /expiring endpoint (proactive surfacing).
• The approval workflow refuses an approval at or after the request’s exceptionExpiresAt and refuses a TTL below one day, so it does not materialize an object that has already lapsed.
• One expiry path. Every expiry goes through one audited transition (ExceptionExpiryWorker.ExpireAsync): the object moves from active to expired with the next version and one Expired history event by system:expiry-worker, in one repository transaction, whichever worker runs it (see the worker table below). When both workers reach the same object, the version check lets one of them write it; the other writes nothing and the object has one Expired event. Nothing else moves an object to expired. The model factory ExceptionEvent.ForExpired (actor "system") has no production caller, and the schema function policy.mark_expired_exceptions() (baseline migration; every tenant, actor system, database clock) has no caller.

Background workers (verified)

Expiry is not only lazy: two in-process hosted BackgroundService workers run the status sweep and warnings. Both are registered with AddHostedService<…>():

Earlier drafts claimed “no Scheduler job is wired” and that the “7-day / 1-day reminders” were not implemented. Both claims are incorrect against current source — see the worker table above. What does not exist is an external JobEngine/Scheduler job: this work runs as in-process hosted services in the Policy Engine.

Lifecycle notifications (verified)

IExceptionNotificationService (interface in StellaOps.Policy.Engine/Services/Gateway/ExceptionService.cs) has these hooks. Only the expiry worker’s warning is fired today: the other five are fired by ExceptionService, which no route or worker calls (see the note below).

The registered implementation is AuditExceptionNotificationService, which emits an AuditEventPayload (module policy, resource type exception) to the unified audit/Timeline emitter (IAuditEventEmitter). It is disabled by default (ExceptionNotificationOptions.Enabled = false; section Policy:Exceptions:Notifications) — when disabled it logs and skips emission. There is no email/Slack/channel dispatch through the standalone src/Notify module; these notifications are audit/Timeline events only.

Note: ExceptionService (IExceptionService) is registered in the Policy Engine but has no caller. The minimal-API handlers documented under exception object lifecycle operate directly on IExceptionRepository and therefore do not emit these notifications; the audit history (/history) is recorded via the repository. ExceptionService applies the same rules as the routes: every call names the tenant, another tenant’s exception answers NotFound, and approve, activate and extend refuse an exception at or after its expires_at.

Data Contracts

Exception object (response — ExceptionResponse)

interface ExceptionResponse {
  exceptionId: string;          // EXC-…
  version: number;
  status: 'proposed' | 'approved' | 'active' | 'expired' | 'revoked';
  type: 'vulnerability' | 'policy' | 'unknown' | 'component';
  scope: {
    artifactDigest?: string;
    purlPattern?: string;
    vulnerabilityId?: string;
    policyRuleId?: string;
    environments: string[];
  };
  ownerId: string;
  requesterId: string;
  approverIds: string[];
  createdAt: string;
  updatedAt: string;
  approvedAt?: string;
  expiresAt: string;
  reasonCode: 'false_positive' | 'accepted_risk' | 'compensating_control'
            | 'test_only' | 'vendor_not_affected' | 'scheduled_fix'
            | 'deprecation_in_progress' | 'runtime_mitigation'
            | 'network_isolation' | 'other';
  rationale: string;
  evidenceRefs: string[];
  compensatingControls: string[];
  ticketRef?: string;
  metadata: Record<string, string>;
}

Approval request (response — ApprovalRequestDto)

interface ApprovalRequestDto {
  requestId: string;            // EAR-yyyyMMdd-XXXXXXXX
  id: string;                   // GUID
  tenantId: string;
  exceptionId?: string;
  requestorId: string;
  requiredApproverIds: string[];
  approvedByIds: string[];
  rejectedById?: string;
  status: 'Pending' | 'Partial' | 'Approved' | 'Rejected' | 'Expired' | 'Cancelled';
  gateLevel: 'G0' | 'G1' | 'G2' | 'G3' | 'G4';
  justification: string;
  rationale?: string;
  reasonCode: string;           // ExceptionReasonCode enum name
  evidenceRefs: string[];
  compensatingControls: string[];
  ticketRef?: string;
  vulnerabilityId?: string;
  purlPattern?: string;
  artifactDigest?: string;
  imagePattern?: string;
  environments: string[];
  requestedTtlDays: number;
  createdAt: string;
  requestExpiresAt: string;
  exceptionExpiresAt?: string;
  resolvedAt?: string;
  rejectionReason?: string;
  version: number;
  updatedAt: string;
  warnings: string[];
}

Approval rule (response — ApprovalRuleDto)

interface ApprovalRuleDto {
  id: string;
  name: string;
  description?: string;
  gateLevel: 'G0' | 'G1' | 'G2' | 'G3' | 'G4';
  minApprovers: number;
  requiredRoles: string[];
  maxTtlDays: number;
  allowSelfApproval: boolean;
  requireEvidence: boolean;
  requireCompensatingControls: boolean;
  minRationaleLength: number;
  enabled: boolean;
}

Error Handling

Observability

The specific metric/log-event names below are illustrative and not verified against an emitted-telemetry catalog. The approval-request endpoints are decorated with .Audited("policy", "<action>", resourceType: "exception_approval_request") (create / approve / reject / cancel), so those actions emit standard audit events; structured information logs (e.g. “Exception request {RequestId} approved by {ApproverId}”) are emitted by the handlers.

Audit actions (verified)

Exception-object events (Created, Updated, Approved, Activated, Extended, Revoked, Expired, EvidenceAttached, CompensatingControlAdded, Rejected) are persisted as ExceptionEvent audit entries and exposed via the /history endpoint.

Not Implemented / Roadmap

The following items appeared in earlier drafts of this flow but are not present in src/and should be treated as roadmap, not current behavior:

• Exception types temporary / extended / permanent / emergencywith fixed max durations (30/90/indefinite/7 days). The implemented object types are vulnerability / policy / unknown / component; duration limits come from gate-level MaxTtlDays, not a type/duration table.
• Severity-driven approval matrix routing to Team Lead → Security Team → CISO. The implemented routing is by gate level (G0–G4) with configurable role strings (code-owner, delivery-manager, product-manager, ciso).
• External Scheduler/JobEngine job for expiry. Implemented as in-process hosted BackgroundService workers instead (ExceptionExpiryWorker, ExceptionLifecycleWorker) — see Background workers. Automatic deactivation (active → expired) and 7-/3-/1-day expiry warnings are implemented; a distinct “mid-point review” reminder is not.
• Notify-module dispatch for approval/expiry emails or Slack (approval_url, #security-approvals). Expiry warnings are emitted, but to the unified audit/Timeline emitter (IExceptionNotificationService → AuditExceptionNotificationService, disabled by default) — see Lifecycle notifications. There is no email/Slack channel dispatch through the standalone src/Notify module.
• scope.images / scope.tenants arrays on the exception object. The object scope is artifactDigest / purlPattern / vulnerabilityId / policyRuleId / environments (+ tenantId). An imagePattern field exists only on the approval-request entity, not on the exception object scope.
• Object statuses pending / rejected. The object state machine uses proposed / approved / active / expired / revoked; pending / rejected belong to the separate approval-request status set.
• Renewal request as a distinct API. The implemented mechanism is POST /api/policy/exceptions/{id}/extend on an active object.

Related Flows

• Policy Evaluation Flow — exception enforcement during evaluation
• Multi-Tenant Policy Rollout Flow — policy/tenant context