Skip to content

Authentication and Authorization Model

Overview

The platform implements an enterprise-style authentication and authorization model with:

  • First Admin Setup
  • Pending User Approval
  • Role-Based Access Control (RBAC)
  • Organization-Scoped Access Control
  • Backend-Enforced Authorization

Frontend visibility restrictions are convenience features only. All authorization decisions are enforced server-side before business logic runs.

First Admin Setup

Initial deployment

If the users table is empty:

GET /api/v1/setup/status

returns:

{
  "setup_required": true
}

The platform displays the First Administrator Setup page.

First administrator creation

POST /api/v1/setup/admin

creates the first user with:

role = admin
status = active

The operation is allowed only once. Subsequent attempts return:

409 Conflict

First administrator creation is protected by a database transaction that checks the user count and creates the administrator only when the count is zero. This prevents concurrent setup requests from creating multiple first administrators.

User Registration Flow

Registration

Public registration accepts:

  • name
  • email
  • password

Role selection is not allowed. Any role value provided by the client is ignored by the backend.

New users are created with:

status = pending

Pending state

Pending users:

  • cannot authenticate
  • cannot access the platform
  • require administrator approval

User Statuses

Status Description Can Login
pending Waiting for approval No
active Approved user Yes
rejected Registration rejected No
disabled Disabled by administrator No

Roles

Administrator

Administrators have full platform access.

Capabilities:

  • access all organizations
  • manage users
  • approve/reject/disable users
  • assign roles
  • assign organizations
  • manage system settings
  • manage integrations
  • create/update/delete organizations
  • run scans
  • manage vulnerabilities
  • access all reports

No organization membership is required for administrators.

Hacker

Hackers can access only organizations assigned by an administrator.

Allowed inside assigned organizations:

  • view dashboard
  • view assets
  • view asset graph
  • view vulnerabilities
  • create scopes, if current policy allows scope creation
  • run scans
  • view scan results
  • view scan logs
  • retest vulnerabilities
  • change vulnerability status
  • generate reports
  • download reports

Not allowed:

  • manage users
  • assign roles
  • assign organizations
  • access admin endpoints
  • manage global settings
  • access organizations not assigned to them

Client

Clients can access only organizations assigned by an administrator.

Allowed inside assigned organizations:

  • view dashboard
  • view assets
  • view asset graph
  • view vulnerabilities
  • view reports
  • download reports

Not allowed:

  • access scans
  • start scans
  • cancel scans
  • retest vulnerabilities
  • change vulnerability status
  • create scopes
  • approve scopes
  • reject scopes
  • manage settings
  • manage users
  • manage integrations
  • access organizations not assigned to them

Client is a read-only role.

Organization Membership Model

Admin

Administrators can access all organizations automatically.

Hacker

Hackers must be assigned to organizations through organization_members.

Client

Clients must be assigned to organizations through organization_members.

If membership does not exist, the backend returns:

403 Forbidden

Organization Visibility

Role Visible Organizations
admin All organizations
hacker Assigned organizations only
client Assigned organizations only

If no organizations are assigned, the UI shows:

No organizations assigned. Contact administrator.

Permission Matrix

Action Admin Hacker Client
View all organizations Yes No No
View assigned organizations Yes Yes Yes
Create organization Yes No No
Update organization Yes No No
Delete organization Yes No No
View dashboard Yes Yes Yes
View assets Yes Yes Yes
View asset graph Yes Yes Yes
View vulnerabilities Yes Yes Yes
Change vulnerability status Yes Yes No
Retest vulnerability Yes Yes No
View scans Yes Yes No
Start scan Yes Yes No
Cancel scan Yes Yes No
View scan logs Yes Yes No
Create scope Yes Yes* No
Approve scope Yes No No
Reject scope Yes No No
Generate report Yes Yes No
View reports Yes Yes Yes
Download reports Yes Yes Yes
Manage users Yes No No
Approve users Yes No No
Reject users Yes No No
Disable users Yes No No
Assign roles Yes No No
Assign organizations Yes No No
Manage integrations Yes No No
Access admin API Yes No No
Access unassigned organization Yes No No

* if current policy allows scope creation.

Backend Authorization

Authorization is enforced on the backend.

Checks are performed through RBAC middleware. Organization-scoped endpoints validate:

  • user role
  • organization membership

before executing business logic.

Administrators bypass organization membership checks. Hackers and clients must have an organization_members row for the target organization.

ID-Based Access Validation

Routes using resource identifiers first resolve the owning organization_id and then verify user access rights.

This applies to routes using:

  • scan_id
  • scope_id
  • vulnerability_id
  • asset_id
  • scheduled_scan_id

This prevents unauthorized access through direct API calls to resources outside the user's assigned organizations.

Endpoint Groups

Public

GET /api/v1/setup/status
POST /api/v1/setup/admin
POST /api/v1/auth/register
POST /api/v1/auth/login

Admin Only

/api/v1/admin/*

Admin-only endpoints include user approval, rejection, disabling, role assignment, and organization assignment.

Organization Scoped

Organization-scoped endpoint groups include:

  • Organizations
  • Assets
  • Scans
  • Scopes
  • Vulnerabilities
  • Reports

Access depends on role and organization membership.

Frontend Visibility Rules

Frontend visibility follows the same role model but is not the security boundary.

Admin

Administrators see all tabs.

Hacker

Hackers see operational tabs for assigned organizations.

Client

Clients do not see:

  • Scans
  • Settings
  • User Management
  • Mutation Actions
  • Start Scan buttons
  • Retest buttons

Clients see:

  • Dashboard
  • Assets
  • Asset Graph
  • Vulnerabilities
  • Reports

Security Considerations

  • Role values from the frontend are ignored during registration.
  • Pending users cannot receive JWT access.
  • Middleware blocks pending, rejected, and disabled users.
  • First administrator creation is transaction-safe.
  • Backend authorization is mandatory even if frontend controls are hidden.
  • Organization membership is validated before access to organization-scoped resources.