Defines how to audit an RBAC model for effective permissions, tenant scope, drift, denied paths, and privileged changes without treating role labels as proof of enforcement.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Audit the policy actually evaluated at enforcement points. Build an effective-permission graph from versioned role grants, resource scope, conditions, and assignments; compare it with an approved policy baseline and exercise deny cases.
Scope
- Role, permission, assignment, scope, policy-version, decision-log, and audit-evidence records.
- Automated drift detection plus representative allow and deny verification.
- Privileged policy-change review and break-glass visibility.
Outside this block
- Choosing between RBAC, ABAC, or relationship-based authorization for a new system.
- Using audit logs as the enforcement mechanism.
Contract
- Every authorization decision resolves subject, action, resource, tenant or organization scope, and policy version.
- Deny is the default when no grant matches or policy data is unavailable.
- Audits expand inherited roles and conditions to effective permissions before comparison.
- The suite includes cross-tenant, removed-role, stale-session, and direct-object-reference deny cases.
- Policy changes record actor, approved change, before/after digests, and deployment version.
- Audit evidence avoids sensitive resource content and is protected from alteration by ordinary administrators.
Implementation guidance
- Generate a policy snapshot from the same source consumed by production enforcement.
- Replay sampled decisions against the deployed policy version, using pseudonymous subject and resource identifiers.
- Separate audit-log read access from policy mutation access.
- Require two-person review or equivalent protected workflow for privileged-role expansion.
Failure handling and safeguards
- If the deployed policy digest differs from the approved snapshot, fail the audit and surface the exact changed grants.
- If decision logging is unavailable, fail closed for required evidence rather than assuming decisions were correct.
- Break-glass use creates a high-severity event and an expiry-bound assignment.
Verification and operations
- Track unauthorized-allow findings, unexpected denies, policy drift duration, orphan roles, privileged assignment age, and break-glass use.
- Run baseline comparison on every policy deployment and full deny-path tests on a schedule.
- Review logs for adequate context and excess personal or sensitive data.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.