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
  • Optional Two-Factor Authentication
  • 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.

Two-factor authentication, when enabled by an administrator, applies only to interactive username/password logins. API key authentication is not challenged with 2FA.

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 threats
  • 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 threats
  • create scopes, if current policy allows scope creation
  • run scans
  • view scan results
  • view scan logs
  • retest vulnerability Threats
  • confirm new Threats, mark false positives, and decide review outcomes
  • 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 threats
  • move active Threats into remediation
  • accept risk for active Threats
  • submit in-progress Threats for review
  • view reports
  • generate reports
  • download reports

Not allowed:

  • access scans
  • start scans
  • cancel scans
  • retest vulnerability Threats
  • confirm new findings
  • mark false positives
  • mark Threats fixed
  • create scopes
  • approve scopes
  • reject scopes
  • manage settings
  • manage users
  • manage integrations
  • access organizations not assigned to them

Client is read-only outside the customer vulnerability workflow lane.

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
Create manual asset Yes Yes No
View asset graph Yes Yes Yes
Update asset lifecycle Yes Yes No
Bulk approve assets Yes Yes No
Update asset criticality Yes Yes No
Run manual plugin on enabled asset Yes Yes No
View threats Yes Yes Yes
Create manual Threat Yes Yes No
Change Threat status Yes Yes No
Change vulnerability exploit flag Yes Yes No
Retest vulnerability Threat 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 Yes
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
View Audit Log 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
  • Threats
  • Reports
  • Threat comments and mentionable users

Access depends on role and organization membership.

Threat Discussion Rules

Action Admin Hacker Client
Read internal Threat comments Yes Yes No
Read client-visible Threat comments Yes Yes Yes
Create internal Threat comments Yes Yes No
Create client-visible Threat comments Yes Yes Yes
Edit own comments Yes Yes Yes
Mention users in internal comments Admin/Hacker targets Admin/Hacker targets No
Mention users in client-visible comments Assigned org users Assigned org users Assigned org users

Mention notifications are created only for users who can read the resulting comment.

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
  • Threats
  • 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.