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.Gateway/Endpoints/ExceptionEndpoints.cs, 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.Gateway/Endpoints/ExceptionApprovalEndpoints.cs, StellaOps.Policy.Engine/Services/ExceptionApprovalRulesService.cs, and the ExceptionApprovalRequestEntity / ExceptionApprovalRuleEntity persistence models.

Both surfaces are mapped by both the Policy Engine and the Policy Gateway (Program.cs: MapExceptionEndpoints() + MapExceptionApprovalEndpoints()). 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); lifecycle notifications 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). Lifecycle notifications 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/Gateway │     │  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 TTL ≤ MaxTtlDays, rationale length, evidence/compensating-control presence, justification length, and required-approver count.
• Sets requestExpiresAt = now + 7 days (approval window) 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.
• 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)

IExceptionEvaluator.EvaluateAsync is invoked during policy evaluation with a FindingContext (artifactDigest, purl, vulnerabilityId, policyRuleId, environment, tenantId). It:

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.

Effective verdict: a finding that would otherwise FAIL passes if (and only if) a matching, currently-effective exception applies.

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; surfacing them through the public HTTP API is partial — treat fields like recheckPolicy / evidenceRequirements as advanced/optional rather than required inputs.

Expiration & Lifecycle

• Exceptions are time-bounded by expires_at (object) / exceptionExpiresAt (approval request). Object expiry is capped at 1 year at creation.
• Expiry is enforced lazily at evaluation time via IsEffectiveAt(now) (a finding is only suppressed if the exception is Active and not past expires_at). The repository exposes GetExpiredActiveAsync() (active rows past expiry) and GetExpiringAsync(horizon) / the /expiring endpoint (proactive surfacing).
• The audit model includes a system-actor Expired event (ExceptionEvent.ForExpired, actor "system").

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 Gateway and Policy Engine.

Lifecycle notifications (verified)

IExceptionNotificationService (interface in StellaOps.Policy.Gateway/Services/ExceptionService.cs) is invoked on exception-object lifecycle transitions and by the expiry worker:

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: the ExceptionService lifecycle methods above are wrapped by the service layer. The minimal-API handlers documented under exception object lifecycle operate directly on IExceptionRepository and therefore do not themselves emit these notifications; the audit history (/history) is still recorded via the repository in both paths.

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). Exception lifecycle notifications 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