Roles and permissions
HarborGuard uses a role-based access control model. Every member, API key, and personal access token resolves to exactly one role at request time. The API enforces roles with a strict numeric hierarchy plus per-resource checks.
Role hierarchy
The middleware that wraps every API route uses a numeric hierarchy. A handler that requires minRole: admin admits Owner and Admin only.
| Role | Level | Description |
|---|---|---|
| Owner | 100 | Full control including billing, ownership transfer, and organization deletion. |
| Admin | 80 | Manage members, registries, SSO, policies, notification channels, API keys. |
| Developer | 60 | Run scans, triage vulnerabilities, manage exceptions. |
| CI / Service Account | 50 | API-only role intended for pipelines. Trigger scans, upload results, read status. |
| Auditor | 40 | Read everything, plus access to compliance reports and audit log export. |
| Viewer | 20 | Read-only access to scans, images, and vulnerabilities. |
A user has exactly one organization role. API keys carry their own role, configured at creation time.
Permission matrix
Cells list the actions the role can perform on the resource domain. view is read; create, edit, and delete are obvious; admin includes destructive operations like rotating credentials or deleting the organization.
| Domain | Owner | Admin | Developer | CI | Auditor | Viewer |
|---|---|---|---|---|---|---|
| Scans | admin | admin | create, view, edit | create, view | view | view |
| Images | admin | admin | view, edit | view | view | view |
| Vulnerabilities | admin | admin | view, edit (triage) | view | view | view |
| Exceptions | admin | admin | create, view, edit, revoke | view | view | view |
| Registries | admin | admin | view | view | view | view |
| Reports | admin | admin | create, view | view | create, view, export | view |
| Audit log | view, export | view, export | view (own actions) | - | view, export | - |
| Notification channels | admin | admin | view | - | view | view |
| Members and teams | admin | admin | view | - | view | view |
| SSO and SCIM | admin | admin | - | - | view | - |
| API keys | admin | admin | - | - | - | - |
| Personal access tokens | self | self | self | - | self | self |
| Billing | admin | view | - | - | view | - |
| Organization (transfer, delete) | admin | - | - | - | - | - |
Notes on enforcement:
- "Triage" edits cover vulnerability status, assignee, and SLA acknowledgement; Developers cannot edit a vulnerability's CVE metadata.
- The Auditor role exists specifically to satisfy SOC 2 and ISO 27001 separation-of-duties requirements: read everything plus full audit log export, but no mutation rights.
- The CI role is rejected from session-based UI routes. It is only useful via API key.
- Personal access tokens inherit the creating user's role at issuance time and are re-evaluated against the user's current role on every request.
Custom roles
The Auditor role is the only built-in role flagged as customizable; it can be cloned to create custom roles in Settings -> Roles -> New role. Custom roles must specify allowed actions per domain using the same matrix above.
Custom roles cannot grant rights above their parent. A clone of Developer cannot grant admin on Registries.
Changing a member's role
Admins change roles from Settings -> Members. The change takes effect on the member's next request. Existing sessions are not invalidated, but role checks are evaluated per-request, so the new role applies immediately even within an active session.
Role changes are recorded as member.role_changed audit events.