Sign in
Edge

Create an operator-defined shadow exception (EDGE-143.6)

Changed on

Persists an operator-signed exception declaration that suppresses future ShadowAgent findings matching its scope predicate (source_type + source_id + risk_level + signal_set). Matching is applied at finding emit time: matching findings are stamped with exception_id, false_positive_reason="operator_exception", and status=managed_skip; they are excluded from default-filter list queries.

Q8 step-up auth: when scope_risk_level is "high", the caller MUST hold the admin legacy role OR the shadow.exception.high_risk permission. Failure returns 403 with code step_up_required and details.required = "mfa_recent|signed_admin_token". The persisted Exception records which factor satisfied the gate so SIEM rules can pivot on the auth tier at the time of action.

expires_at MUST be in the future and within 90 days (§10.3 "longer requires re-affirmation").

post/api/v1/edge/shadow/exception

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/api/v1/edge/shadow/exception
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

X-Tenant-IDstring required

Tenant isolation header (required on all protected routes).

Request body

expires_atstring date-time required

MUST be in the future and within 90 days of now.

reasonstring
scope_source_type'local' | 'kubernetes' | 'ci' | 'network' required
scope_source_idstring
scope_signal_setstring[]
scope_risk_level'low' | 'medium' | 'high' | 'critical' required

Response

Exception accepted and persisted.

exception_idstring required

Opaque id with shadow_exc_ prefix.

tenant_idstring required
created_bystring required

Authenticated principal at create time. Not trusted from the wire body.

created_atstring date-time required
expires_atstring date-time required

Maximum 90 days from creation (longer requires re-affirmation per §10.3).

reasonstring

Free-text operator rationale, up to 512 bytes.

scope_source_type'local' | 'kubernetes' | 'ci' | 'network' required
scope_source_idstring

Optional detector instance id; further narrows scope.

scope_signal_setstring[]

At most 16 detector signal names; any-of overlap with a finding's signal_set satisfies the predicate.

scope_risk_level'low' | 'medium' | 'high' | 'critical' required
status'active' | 'revoked' | 'expired' required
step_up_factor'mfa_recent' | 'signed_admin_token' | 'none' required

Auth tier that satisfied the Q8 step-up gate at create time. "signed_admin_token" when the legacy admin role matched; "mfa_recent" when the explicit shadow.exception.high_risk permission matched; "none" when the gate was not required.

revoked_bystring
revoked_atstring date-time
revocation_reasonstring

Changes