Documentation

Reference

Roles and permissions reference

The built-in roles, what each can and cannot do, which pages and API routes need only a signed-in account, and the sign-in, MFA and session rules the server enforces.

Covers YuviRed 1.0 for Windows. Everything here is read from the server's own tables and code; the source of each fact is in the comments.

Two layers: console role and system role

The Team / Users page lets an administrator pick one of three roles for an account: Admin, Analyst or View Only. Behind those three, the server keeps five system roles, each a list of permissions. The console pick maps to a system role like this:

Console role (Role column)System role givenDescription from the server
Adminadministrator"Full operational access. Cannot manage licensing."
Analystsecurity_analyst"Day-to-day triage: alerts, policies, endpoints, reports."
View Onlyread_only"View-only access across the platform."
(not in the console)super_admin"Full access to every capability, including license and role management."
(not in the console)developer"API and integration access: AI providers, prompt templates, MCP servers."

Three consequences to know:

  1. The first account is the owner (super_admin). First-run setup creates it, and it is the only account that holds the license.manage permission. An account you create with the Admin role is administrator and cannot activate a license, import a license file or redeem an activation code: the buttons show, but the request fails with Missing required permission: license.manage. Sign in with the first account to manage the license. (The license screen says: "Only a YuviRed administrator can activate this server. Sign in with the administrator account created when YuviRed was installed.")
  2. Changing the role of an existing user replaces all of that user's role assignments with the new one.
  3. super_admin and developer and custom roles cannot be assigned from the console. They are set only through the API route POST /api/v1/rbac/assign, which needs roles.manage. The five system roles cannot be deleted. A user with no role assignment at all is treated as the system role that matches the user's console role.

The console hides some menu items by console role (Admin only: Blocklist, Agent Deployment, Adoption Requests, Configuration, Legal, Help, Team / Users, Debug / Reset, System Logs; Analyst and Admin: Enforcement; Artifact Analysis shows only to accounts holding artifact.read). The hiding is a convenience. The server checks the permission on every request, and that check is what counts.

Permissions by role

38 permissions exist (counted from the server's permission catalogue; the "What it allows" column says where the console checks each one, which is more specific than the server's one-line description). Y means the role holds it. SA = super_admin, AD = administrator (console Admin), AN = security_analyst (console Analyst), RO = read_only (console View Only), DV = developer.

PermissionWhat it allowsSAADANRODV
users.readView user accountsYY---
users.manageCreate, edit, deactivate, delete users; reset passwords; turn off another user's MFA; end sessionsYY---
roles.manageCreate and assign rolesYY---
policies.readView policiesYYYY-
policies.writeCreate, edit, enable or disable policies; classify AI toolsYYY--
alerts.readView alerts, Prompt Monitoring events and Prompt Protection policyYYYY-
alerts.writeChange alert status, add notes, create and change incidents, export prompt eventsYYY--
endpoints.readRead-only endpoint extras (credential rotation status, rollout status, server identity)YYYY-
endpoints.manageRemove, decommission and reactivate endpoints; deployment tokens; Add Computer; adoption requests; credential rotationYY---
endpoints.operateRefresh a computer now; collect agent logsYYY--
blocklist.manageManage the blocklist; export the denylistYYY--
config.readView platform configurationYYYYY
config.writeChange configuration, including secrets; save the Prompt Protection policy; classifications; blocklist feed tokenYY---
ai_providers.readView AI provider recordsYY-YY
ai_providers.writeAdd or edit AI provider records and keysYY--Y
prompt_templates.manageManage prompt templatesYY--Y
audit.readView and export the audit logYY-Y-
license.manageView and change license information: activate, import, redeem a code, confirm a moved serverY----
reports.readGenerate and view your own reportsYYYYY
reports.manageSee, download and delete reports other people madeYY---
debug.accessDebug / Reset, System Logs, system status, data resetYY---
tools.manageDelete and merge AI tools; manage the AI Tool CatalogYY---
dlp.view_raw_contentView decrypted original prompt samples (every view is audited)YY---
response.readRequest and view enforcement (response) actionsYYY--
response.enforceApprove, reject, run, recall, roll back, disable, archive, delete actionsYY---
ams.readView the AMS agent registry, governance records and riskYYYY-
ams.manageEdit AMS governance (owner, purpose, approval, pause); refer agents to AIDRYY---
ams.messageSend messages to AI agent sessionsYY---
ams.approveApprove or deny one pending AI agent tool callYY---
ams.policyChange the AMS control policy and connectorsYY---
ams.stopStop, hold, release, pause, resume and cancel AI agent workYY---
ams.bulkAct on several AI agents at once (each act also needs its own permission)YY---
deployment.readView deployment campaignsYYYY-
deployment.manageCreate or change campaigns; mint bootstrap credentialsYY---
metrics.scrape_mintMint, rotate and revoke credentials for the unattended metrics feedYY---
artifact.readView Artifact Analysis results and provider statusYYYY-
artifact.analyzeStart, authorize and cancel an artifact analysisYYY--
artifact.manageDelete artifact history; test providers; read or change Artifact Analysis settingsYY---

In plain words

  • Admin (administrator) holds every permission except license.manage.
  • Analyst (security_analyst) triages: it reads and changes alerts, policies, the blocklist and incidents, can refresh a computer and collect its logs, can request (but never approve or run) an enforcement action, can run artifact analyses and read reports. It cannot change configuration, manage users, remove endpoints, view the audit log, see original prompt samples or act on AI agents beyond reading them.
  • View Only (read_only) reads: policies, alerts, endpoints, configuration values, AI provider records, reports, the audit log, AMS, deployment campaigns and artifact results. It changes nothing.
  • Developer holds no security-data permissions (no alerts, endpoints, policies or AMS). It reads configuration and reports and manages AI provider records and prompt templates.

What needs only a signed-in account

Some pages and routes check that you are signed in but do not check any permission. Any signed-in user, of any role (including View Only and Developer), can read these.

Plain statement: any signed-in user can read endpoint identity and raw telemetry. That means the list of endpoints (host name, user, IP address, operating system, agent version, risk), one endpoint's detail, and its raw telemetry rows (processes, network connections, browser AI visits, extensions, software, local AI, DNS names, AI agent signals), up to 1000 rows per request. Treat every account, including View Only, as having that access. Create accounts accordingly.

Routes that need only a signed-in account:

AreaRoutes (/api/v1/...)
EndpointsGET /endpoints, GET /endpoints/{id}, GET /endpoints/{id}/telemetry, GET /endpoints/{id}/extension-changes, GET /extension-changes
AI tools and catalogGET /tools, GET /tools/{id}/usage, GET /tool-catalog, GET /tool-catalog/freshness, GET /tool-catalog/{id}
Classification, policy, blocklistGET /classifications, GET /classifications/{id}, GET /policies, GET /blocklist
DashboardsGET /dashboard/stats, GET /topology, GET /reports/summary, GET /reports/executive, GET /behavior/summary, GET /network/summary, GET /network/provider-ip-ranges
IncidentsGET /incidents, GET /incidents/{id}
LicenseGET /license, GET /license/capacity, GET /license/activation
NotificationsGET /notifications/status
RolesGET /rbac/roles, GET /rbac/permissions, GET /rbac/users/{id}/permissions, GET /rbac/users/{id}/roles
Your own accountPOST /auth/logout, GET /auth/me, POST /auth/change-password, GET /auth/mfa/status, POST /auth/mfa/disable, POST /auth/mfa/recovery-codes/regenerate

Everything else in the console routes needs a named permission (above). The agent and extension routes (register, check-in, configuration, gateway, extension download) are not for people: they use a deployment token, an endpoint credential or a gateway credential instead of an account. A few routes need nothing (the health and version routes, sign-in and setup).

Multifactor authentication (MFA)

  • What it is: a second sign-in step with a 6-digit code from an authenticator app (time-based one-time password), or a one-time recovery code.
  • Who must use it: the roles listed in the setting Require multi-factor sign-in for (Configuration, Security & Access). The default is Admin. The console offers Admin and Analyst; View Only can never be required, whatever the setting says. A user in a required role who has not enrolled is sent straight to enrolment at sign-in, including the first account at the end of first-run setup. Console role is what counts: admin covers both super_admin and administrator.
  • Everyone else: any user may enrol or disable MFA for their own account from the account menu (Authentication / MFA, Recovery Codes). Turning it off needs a current code. Regenerating recovery codes needs a current code and replaces the old set.
  • Recovery codes: 10 codes of 10 characters, shown once, each works once. A new set replaces the old.
  • Time limit: the step between password and code (and forced enrolment) lasts 2 minutes. If it ends the console says: "This sign-in step has ended. It lasts 2 minutes, and a newer sign-in or a restart of YuviRed also ends it. Sign in again."
  • Wrong codes: a wrong code counts as a failed sign-in on the same budget as a wrong password. In addition, more than 20 wrong or repeated code attempts for one account in an hour trigger a back-off with the message Too many failed codes for this account. Retry in Ns. (HTTP 429). It slows guessing; it does not lock the account for good.
  • Lost phone and no recovery codes: an administrator with users.manage turns that user's MFA off (the shield icon on Team / Users); the user enrols again at next sign-in.
  • Single sign-on: SSO users skip the server's own code step. By default the identity provider must prove it performed MFA for roles that require it (setting Require provider MFA for roles that require MFA, default On). Turning that off lets SSO sign-ins bypass the requirement.

Passwords

  • At least 12 and at most 72 bytes; at least 3 of 4 character classes (lowercase, uppercase, digit, symbol); at least 6 different characters; must not contain the user's own name or email name, or a commonly guessed word (including leet-speak forms such as P@ssw0rd); must not equal the current password or any of the last N (setting Prevent password reuse, default 5, range 0 to 24). Existing passwords are never re-checked.
  • The same rules apply at first-run setup, Add User, Reset Password and Change Password.
  • No scheduled expiry. A password change is forced only when an administrator sets it (reset with a required change, or require password change). Until the user changes it, every call except changing the password is refused with HTTP 403 password_change_required.
  • A password an administrator issues as temporary stops working 72 hours after it was set. The sign-in is then refused exactly like a wrong password ("Invalid credentials"), and counts as a failed attempt.

Sign-in lockouts

RuleValueWhat the user sees
Per source address and account8 failed attempts inside a rolling 5 minutes blocks that pair until the window drains.HTTP 429 Too many failed login attempts. Please wait and try again.
Per account from any address30 failed attempts inside a rolling hour. A time-based cool-down, never a permanent lock. A successful sign-in does not clear it. A sign-in from the server computer itself (loopback) is exempt, so someone at the server can always sign in.Same 429 message.
Wrong password and unknown userSame answer for both.HTTP 401 Invalid credentials
AuditFailed sign-ins are audited, capped at 120 rows a minute per source address.

On YuviRed Lite there is no Redis, so these counters live in the service's memory. A restart of the YuviRed service clears them. Because the per-account ceiling counts failures from every address, a person on the network who keeps failing can hold an account out of network sign-in for up to an hour; sign in at the server itself to get around it.

Sessions

  • Length: a sign-in issues a token valid for 480 minutes (8 hours). After that the console shows the dialog Session Expired ("Your session has ended and background updates have been paused. Log in again to resume monitoring.") with Log In Again.
  • Ended early by: Sign Out, a password change (your other sessions end), an administrator's reset, deactivating or deleting the user, and an administrator's revoke-sessions.
  • Lite limit: Lite has no Redis, so the list of ended sessions is kept in memory. A restart of the YuviRed service forgets sign-outs, session endings after a password change and revoke-sessions: such a session works again until its own 8 hours run out. Deactivating or deleting a user still ends their sessions after a restart, and a required password change survives a restart.
  • Active Sessions in the account menu is disabled: this build does not list individual sessions.
  • A session also stops working while the server is locked for licensing (HTTP 402; see statuses-and-errors.md). Signing in, the account routes (your own password and MFA), the license screen, first-run setup and rolling back a response action (so a browser block applied earlier can still be lifted) keep working.
  • Neither the session length nor the lockout numbers can be changed from the console.