Roles & Permissions (RBAC)
ShieldAgent enforces role-based access control across the platform. This page documents the built-in roles and the permission matrix.
Overview
Every authenticated request is checked against the caller's role within the target tenant. Permissions follow a resource:action pattern (e.g. agent:write). Platform admins have full access across all tenants. Tenant-scoped roles are assigned per-tenant, so a user can be an auditor in one tenant and a tenant_admin in another.
Built-in Roles
ShieldAgent ships with six system roles. Custom roles are not yet supported — assignments use these built-in roles.
| Role | Scope | Description |
|---|---|---|
| platform_admin | Platform | Full platform access across all tenants. Reserved for ShieldAgent operators. |
| tenant_admin | Tenant | Full management of one tenant: users, settings, billing, all sub-resources. |
| security_operator | Tenant | Monitoring, incident triage, alert management, risk review. |
| auditor | Tenant | Read-only access to compliance reports, audit trail, and export. |
| aiops_engineer | Tenant | Agent lifecycle, MCP server management, policy authoring. |
| viewer | Tenant | Read-only dashboard and summary data. |
Permission Matrix
The matrix below shows every permission and which roles include it. platform_admin and tenant_admin have all permissions and are omitted for readability.
| Permission | Description | sec_op | auditor | aiops | viewer |
|---|---|---|---|---|---|
| agent:read | View / list agents | ✓ | ✓ | ✓ | ✓ |
| agent:write | Create or update agents | — | — | ✓ | — |
| agent:delete | Remove agents | — | — | ✓ | — |
| agent:configure | Modify agent settings | — | — | ✓ | — |
| policy:read | View / list policies | ✓ | ✓ | ✓ | ✓ |
| policy:write | Create or update policies | — | — | ✓ | — |
| policy:delete | Remove policies | — | — | ✓ | — |
| audit:read | View audit trail events | ✓ | ✓ | ✓ | — |
| audit:export | Export audit data | — | ✓ | — | — |
| compliance:read | View compliance reports | ✓ | ✓ | — | — |
| compliance:write | Create or update compliance records | — | — | — | — |
| compliance:export | Export compliance data | — | ✓ | — | — |
| risk:read | View risk scores and trending | ✓ | ✓ | ✓ | ✓ |
| risk:configure | Modify risk thresholds | ✓ | — | ✓ | — |
| incident:read | View incidents | ✓ | ✓ | — | — |
| incident:write | Create or update incidents | ✓ | — | — | — |
| incident:triage | Acknowledge, assign, or resolve | ✓ | — | — | — |
| mcp_server:read | View MCP server registrations | ✓ | — | ✓ | ✓ |
| mcp_server:write | Create or update MCP servers | — | — | ✓ | — |
| mcp_server:delete | Remove MCP servers | — | — | ✓ | — |
| alert:read | View alerts | ✓ | ✓ | ✓ | ✓ |
| alert:write | Create or update alert rules | ✓ | — | ✓ | — |
| alert:delete | Remove alert rules | — | — | — | — |
| alert:triage | Acknowledge or resolve alert events | ✓ | — | — | — |
| review:read | View pending reviews | ✓ | ✓ | ✓ | — |
| review:triage | Approve or reject reviews | ✓ | — | — | — |
| user:read | View user accounts | — | — | — | — |
| user:write | Create or update users and roles | — | — | — | — |
| user:delete | Remove user accounts | — | — | — | — |
| tenant:read | View tenant settings | ✓ | ✓ | ✓ | ✓ |
| tenant:write | Modify tenant settings / billing | — | — | — | — |
| export:read | View export configurations | — | ✓ | — | — |
| export:write | Create or update export configs | — | — | — | — |
| dashboard:read | View aggregated dashboard data | ✓ | ✓ | ✓ | ✓ |
Managing Roles in the Dashboard
Invite users and assign roles directly from the dashboard:
- 1Go to Settings → Team in the left sidebar.
- 2Click Invite User and enter their email address.
- 3Choose a role from the dropdown (viewer, auditor, aiops_engineer, security_operator, or tenant_admin).
- 4Click Send Invite — the user receives an email and is assigned the role upon accepting.
- 5To change an existing user's role, find them in the Team list and click their current role to open the role picker.
Role Assignment
Roles are assigned per user per tenant. A user can hold different roles in different tenants, allowing flexible access control across your organization.