15. Users, roles, two-factor, API keys, approvals and the audit trail

This chapter covers who can sign in, what each person may do, which actions need a second person (four-eyes), service-account API keys, and the audit trail.

The Settings group in the sidebar is shown to administrator-level roles (super administrator, LSO, RSO, administrator, or a custom role holding user, role or policy management). Approvals is shown to everyone: a requester of any role needs to see what they are waiting on.

15.1 First sign-in of a local account#

Every local account goes through two steps before it can use the console:

1. Change the password. Always required for the account created at install. Passwords are at least 12 characters.
2. Enrol two-factor authentication. The page shows three steps:
   1. Scan with an authenticator app (any TOTP app).
   2. Save your recovery codes (ten codes; each works once). Store them offline.
   3. Enter the 6-digit code from the app.

Two-factor is required by default (REQUIRE_TWO_FACTOR=true in .env). While it is required, a user cannot turn it off. Directory accounts always need it.

At sign-in, a user who lost the phone can click Use a recovery code and type one of the saved codes. An administrator can reset a user's two-factor (15.2); the user enrols again at the next sign-in.

15.2 Users#

Settings > Users.

Required permission: View users to see; Manage users to change. Four-eyes: yes for creating, deleting, disabling a user and changing a role or permissions (critical action "Change users").

Procedure: create a user#

1. Under Add an account, enter username, email, full name and password, and choose the role.
2. Click Create user.
3. With dual control on: "Sent for approval. The change takes effect once it is signed off and executed." Have it approved and executed from Approvals.

What you see: "User created successfully". The user signs in, changes the password and enrols two-factor (15.1).

The user table#

Columns: User, Role, Status (active / inactive), 2FA (enabled / disabled), Permissions (count, with +grants / -denials), Actions.

With dual control on, each change below is held: "Sent for approval. The change takes effect once it is signed off and executed." Have it approved, then run it from Approvals > My requests > Execute now (15.6).

Procedure: change a user's role, or disable or re-enable a user#

Risk: a disabled user is signed out and cannot sign in; a role change takes effect on the user's next request. Rollback: change it back the same way.

1. Open Settings > Users and find the user in the table.
2. To change the role, choose the new role in the Role column.
3. To disable the account, untick the box in the Status column (it then reads inactive); tick it to re-enable the account.
4. Press Save in the row's Actions.
5. What you see: "Updated <user>". Your own row has these controls disabled ("Your own role and status cannot be changed here.").

Disable rather than delete when the person may come back, or when you want the account kept as a named record.

Procedure: grant or deny single permissions#

1. In the user's row, press Adjust in the Permissions column.
2. For each permission choose As role, Grant or Deny. A denial wins over the role and over a grant.
3. Press Save permissions (Cancel discards). You see "Updated permissions for <user>". The column shows the count with +grants / -denials.

Procedure: reset a user's two-factor#

Use this when a user lost the authenticator and the recovery codes.

1. Press Reset 2FA in the user's row. For your own account the browser asks first: "Resetting your own 2FA signs you out of all sessions. Continue?"
2. What you see: "2FA reset for <user>". The user enrols a new authenticator at the next sign-in (15.1).

Procedure: delete a user#

Risk: the account is removed; the audit trail keeps every record of what it did. Rollback: create the account again (15.2); it is a new account with no history.

1. Press Delete in the user's row.
2. Confirm "Delete <user>?".
3. What you see: "Deleted <user>" and the row disappears.

Procedure: a user forgot their password#

The console has no field for an administrator to set another user's password.

• Outbound email configured: the user presses Forgot? on the Sign in page, enters the Email on your account and presses Send link. "If an account uses that address, a reset link is on its way. It expires in one hour." The link opens the Reset password page: enter New password and Confirm password and press Reset password. "Password reset completed. Redirecting to login..." An expired link shows "Invalid or expired reset token."; request a new one.
• No outbound email (the sign-in page says "Email is not configured on this deployment. Ask an administrator to reset your password."): an administrator deletes the account and creates it again with a temporary password (procedures above), hands the password over by a safe channel, and the user changes it at once (next procedure). The installation administrator is reset on the server instead: sudo ./lawliet passwd (3.17).

Procedure: change your own password#

The console has no menu entry for this; open the page by its address.

1. Sign in, then open https://<server>/change-password in the same browser.
2. The page Change your password asks for Current password, New password and Confirm new password. The new password needs at least 12 characters, both entries must match, and it must differ from the current one; the rules are ticked as you type.
3. Press Set password. It shows Saved.

If it fails: "Could not change the password." or the server's reason (for example a wrong current password). Directory accounts change their password in the directory, not here.

Rules the server enforces:

• Nobody can change their own role, status or permissions, or delete their own account.
• The last active super administrator cannot be demoted, disabled or deleted.
• While directory sign-in is on, at least one active local super administrator must exist.

15.3 Roles and permissions#

Settings > Access control > Roles.

Required permission: Manage roles. Four-eyes: yes (critical action "Change roles").

Built-in roles:

Permissions are grouped as the editor shows them: Overview, Fleet, Compliance, Investigation, Logs, Network, Administration. The Fleet permissions used in this part of the guide:

Procedure: create a custom role#

1. Settings > Access control > Roles > New role (or select a role and Copy this role).
2. Enter Name, the key (lower case letters, digits and underscores, starting with a letter, for example soc_lead; it cannot be changed later) and Description.
3. Tick the permissions. Grant all / Clear work per group.
4. Click Create role (or Save role when editing). Approve and execute if held.

Procedure: change or delete a custom role#

Permission: Manage roles. Four-eyes: yes ("Change roles").

1. Open Settings > Access control > Roles and select the role in the list.
2. To change it, tick or untick permissions (Grant all / Clear per group), change the name or description, and press Save role. You see "Saved <role>." (or "Sent for approval"). The key cannot be changed.
3. To delete it, move every user off it first (15.2), then press Delete role and confirm "Delete the role "<role>"? Users must be moved off it first." You see "Deleted <role>." It is refused while anyone holds it or the dual-control policy names it.

Built-in roles cannot be deleted, and the Super administrator cannot be edited. To vary a built-in role, press Copy this role and change the copy.

15.4 Dual control (four-eyes)#

Settings > Access control > Dual control.

Required permission: Configure dual control. Four-eyes: always while dual control is on (cannot be switched off).

With dual control on, a critical action does not run when requested. It waits until a second person in an approving role signs it, then the requester executes it.

Policy settings:

Critical actions and their default:

Who approves whom is resolved in this order: approvers picked per action in the Critical actions table; then the pairing for the requester's role (default: LSO approved by RSO, RSO by LSO); then Fallback, any other role (default: super administrator). The approver also needs the Approve critical actions permission. Nobody approves their own request.

Click Save policy (or Discard changes). A policy that would lock everyone out is refused.

The first day: before a second approver exists#

A fresh install has one account. While no two active approvers exist who could sign for each other, an approver's critical action runs on one signature, and every page shows the banner "Four-eyes is inactive until a second approver exists." Each such action is recorded in the audit trail as dual_control_bypassed with reason no_second_approver.

To end it:

1. Sign in as the super administrator.
2. Create the second approver: a second super administrator, or an LSO and an RSO.
3. Have them sign in, change their password and enrol two-factor.
4. Review the dual_control_bypassed events in the audit trail.

From the first approving pair on, four-eyes applies to everyone, the super administrator included (unless "Super administrators act alone" is turned on).

15.5 What an approval binds#

• The approval covers exactly the reviewed request: method, path, query and a hash of the body. A changed request is refused.
• It is single use. A failed action leaves it usable.
• A pending request expires after the decision window; an approved one must be executed within the execution window.
• The approver's rights are judged when they decide.

15.6 Approvals#

Approvals has three tabs:

Columns: Action, Requested by, Reason, Approvers, Status, Asked, Expires.

Procedure: approve or reject (the approver)#

Required permission: Approve critical actions, in a role allowed to approve the requester.

1. Open Approvals > Waiting for me and click the request.
2. Read What it does, Reason and What will run (the request, with passwords and keys hidden). For a connection test, its checklist is shown.
3. Enter a Comment (required to reject).
4. Click Approve ("Approved. The requester can now execute it.") or Reject.

Procedure: execute (the requester)#

1. Open Approvals > My requests and click the approved request.
2. Click Execute now within the execution window. It runs once, with your own rights. ("Approved. Execute it within the execution window set in the policy; it runs once.")
3. Withdraw request cancels a request you no longer need.

Notes:

• An offline package's result says it is ready to download from Environment > Hosts > Install agent > Offline package within the hour.
• A request that carried an uploaded file (for example a platform update) cannot keep the file; return to its own screen and submit it again under the same approval.

15.7 API keys (service accounts)#

Settings > API keys. For scripts and pipelines, so they do not borrow a person's password.

Required permission: Manage API keys. Four-eyes: yes for create and revoke (critical action "Change API keys").

Procedure: issue a key#

1. Under Issue a new key, fill in:

   Field	What to enter
   Name	The job that uses it, for example "nightly CI compliance gate"
   Scope	Read only (dashboards, reporting), Run scans (read plus start compliance scans), Ingest findings (read plus submit findings to the review queue)
   Expires in (days)	Required; at most 365
   Description (optional)	Who owns it and where it runs

2. Click Create key. Approve and execute if held.

3. Copy this key now - it will not be shown again. Only a hash is stored.

Use it as a bearer token:

curl -H "Authorization: Bearer lwk_..." https://<server>/api/v1/agents/stats

A key's rights are its scope only; roles do not apply to it. A key is not asked for a second factor, so keep it as secret as a password and give it the shortest useful expiry.

Issued keys shows Key, Scope, Status, Expires, Last used, Calls. Show revoked includes revoked keys.

Procedure: revoke a key#

A key cannot be edited or extended. To change its scope or expiry, issue a new key, move the job to it, then revoke the old one.

1. Open Settings > API keys and press Revoke on the key's row.
2. The browser asks: "Revoke "<name>" (<prefix>...)? This takes effect immediately and cannot be undone. Give a reason for the audit trail:". Type a reason of at least 5 characters and press OK. Approve and execute if held.
3. What you see: "Revoked "<name>". Any caller using it is refused on its next request." The key stays listed under Show revoked; keys are never deleted.

15.8 Audit trail#

Settings > Audit trail.

Required permission: View the audit trail (auditors, administrators). Records are never edited or removed, and survive the deletion of the account that caused them.

1. Choose the range: Last 24 hours, Last 7 days, Last 30 days, All time.
2. Filter by action, resource, user and outcome (Failed only, Succeeded only).
3. Columns: When, Who, Action, Resource, Source, Outcome. Click a row for Event id, Who, Action, Resource, Source address, Outcome and Recorded details.

Useful resources for this part of the guide: agent, enrolment_code, ad_write, directory_signin, deployment credentials and jobs, approvals.

The trail is a hash chain. To verify it has not been altered, an auditor calls GET /api/v1/logs/audit/verify (permission View the audit trail). If it reports a break, report it as described on the security disclosure page.

More detail: access control reference, two-factor reference and API keys reference.