Scopes and Roles

Canonical Reference: For the complete, authoritative list of 90+ scopes with role bundles and configuration examples, see authority-scopes.md.

This document defines the scope taxonomy and how scopes map to roles across StellaOps. It is intentionally cross-cutting and does not attempt to list every module-specific scope; module dossiers and gateway contracts are the source of truth for per-surface requirements.

Terms

Scope: an OAuth2/OIDC scope string granted to a client/user token and enforced by the gateway and services.
Role: a human-friendly grouping of scopes, assigned per tenant (often via RBAC in Authority/Console).
ABAC claims: optional attribute filters that constrain a token further (e.g., environment, namespace, project).

Scope Naming Conventions

Scopes follow a predictable pattern:

<area>:<verb>
Verbs are small and consistent: read, write, approve, simulate, audit, admin.

Examples that appear across current contracts and module dossiers:

Vulnerability Explorer: vuln:view, vuln:investigate, vuln:operate, vuln:audit
Exception governance: exception:read, exception:write, exception:approve
Policy: policy:read, policy:simulate
VEX ingestion: vex.read, vex.admin

Typical Role Shapes (Tenant-Local)

Exact role names vary per deployment, but the intent is stable:

Viewer: read-only access to findings/evidence for a tenant.
Operator: can triage findings and create workflow objects (comments, assignments, exports).
Approver: can approve/reject workflow objects that change gating (exceptions, waivers) for a tenant.
Auditor: can access audit exports, histories, and verification surfaces.
Admin: tenant administration (RBAC, client credentials, quotas, configuration).

Enforcement Model (Where Scopes Are Checked)

Authority issues tokens and embeds scopes (and optional ABAC claims).
Gateway (when present) performs consistent scope enforcement and tenant routing.
Services validate tenant context and enforce scope checks at endpoint boundaries.
Service-to-service calls may use short-lived, sender-constrained tokens (OpTok/DPoP/mTLS) in addition to scopes.

References

Tenancy model and isolation: docs/security/tenancy-overview.md
Exceptions API entry point: docs/api/exceptions.md
Policy + Exceptions gateway contract: docs/api/gateway/policy-exceptions.md

2.4 KiB Raw Blame History