Skip to main content

Users, roles and scopes

Every person who signs in is a user. A user holds one or more roles, and a role is a set of permissions. A scope limits which clusters and nodes the user sees. The user has the union of the permissions of its roles, and the scope applies to every page and every API call.

Roles​

Two roles are built in and kept up to date by the server at every start:

RolePermissions
adminEvery permission, for every cluster and node.
viewerRead the inventory, agents, scans, reports, alerts and CPE mappings.

Create more roles on the Settings page, in Roles, with a checklist of permissions. Give each role a description that says who it is for, for example Read-only access for the platform team.

The permissions are listed in the permissions reference. In short:

PermissionLets a user
inventory.viewSee findings, dependencies, assets and the dashboard.
agents.viewSee agents and agent releases.
agents.manageRegister, change and remove agents, create tokens, roll out updates.
scans.viewSee scan runs, task runs and the scheduled tasks.
scans.runStart a scan.
tasks.manageChange the schedule of a task and run it now.
reports.viewView and download reports and templates.
reports.manageCreate, change and delete reports and templates.
alerts.viewSee alert channels, rules and events.
alerts.manageChange alert channels and rules.
cpe.viewSee the NVD dictionary status and the CPE mappings.
cpe.manageImport the NVD dictionary and change the mappings.
settings.manageChange the NVD, AI and automatic agent update settings.
users.manageCreate, change and delete users, and assign roles and scopes.
findings.triageRecord decisions on findings, and set their owner and ticket.
roles.manageCreate and change roles.

A user who holds users.manage or roles.manage can only grant what they hold themselves, and cannot widen a scope beyond their own. Nobody can make themselves an administrator this way.

Local users​

On the Settings page, in Users, select Add user. Enter the e-mail address, a name, an initial password of at least eight characters, the roles, and the scope. The user can change the password on the Account page.

An administrator can change the roles and scope of any user at any time. An administrator cannot demote their own account; another administrator has to do that.

Scope​

A scope is either every cluster and node, or a list of clusters and a list of nodes. A row is visible when its cluster is in the list, or its node is in the list.

  • A node is the host name of the agent that reported the row. The node agent and the host agent of one Kubernetes node are one node.
  • A host without a cluster is reached through its node only.

The scope applies to findings, dependencies, assets, agents, the dashboard, exports, reports and the MCP tools. Alert rules and channels, scan runs and settings are not scoped: they follow the permissions only. Registering an agent needs an unrestricted scope, because the scope cannot be checked before the agent reports.

Identity-provider accounts​

An account from an identity provider is created on its first sign-in and matched by its e-mail address. Its roles and scope come from the groups it belongs to, at every sign-in. The mapping is a JSON list, given in OIDC_GROUP_MAPPINGS or SAML_GROUP_MAPPINGS:

[
{"group": "vop-admins", "roles": ["admin"], "all": true},
{"group": "vop-prod-viewers", "roles": ["viewer"], "clusters": ["prod"]},
{"group": "vop-node-watch", "roles": ["viewer"], "nodes": ["talos-worker-3"]}
]

A user in several groups gets the union of their roles and scopes. When mappings are configured, a user in no mapped group cannot sign in, and loses the roles it had. Without mappings, a new provider user gets the viewer role for every cluster and node, and existing users keep what they have. See Single sign-on for the setup.

The old settings OIDC_ADMIN_GROUPS and SAML_ADMIN_GROUPS still work and make the members administrators. Use the mappings for new setups.