1. Overview and concepts

What Lawliet is made of, in operator terms, and the four ideas that every later chapter relies on: roles, four-eyes approval, the licence, and the air-gapped operating model.

Read this chapter once before you install. It has no procedures that change anything.

1.1 What runs where#

Lawliet has two parts:

• The server. One Linux host that runs the platform in Docker containers. Operators use it through a web console in the browser. You install and look after it with one command, ./lawliet, in the directory where you unpacked the bundle.
• The agents. A small program on each monitored host (Linux, Windows, macOS). It collects what the platform needs and carries out the actions operators request.

The containers on the server#

The real container names start with the Compose project name, which is lawliet unless you chose another one at install time (see Installation): lawliet-postgres, lawliet-backend, and so on.

The two serving modes#

A plain-HTTP install can be moved to HTTPS later with sudo ./lawliet tls on, and an HTTPS install can be switched to plain HTTP with sudo ./lawliet tls off. Agents keep working in both directions. See TLS and certificates.

How agents talk to the server#

Agents are pull-only. Nothing ever connects to an agent.

• Each agent opens an outbound connection to the server every 15 seconds (its heartbeat). It sends what it collected and receives the commands waiting for it.
• A command an operator queues is therefore delivered at the agent's next heartbeat, not instantly.
• No listening port is opened on a monitored host, and no inbound firewall rule is needed on any endpoint.
• An agent that has not sent a heartbeat for 5 minutes is shown as offline.

Every command the server sends is signed. The agent refuses a command that is more than 10 minutes old or more than 60 seconds in the future. This is why clocks matter: a host whose clock has drifted refuses every command while still looking online. Run NTP on the server and on every agent host.

What the server reaches out to#

Nothing, unless you configure it. The shipped server makes no outbound connection at all: no licence check-in, no update check, no telemetry. Optional features that do reach out are listed in Security hardening of the server, and each is off until an operator configures it.

1.2 Roles and permissions#

Every console user has exactly one role. A role is a named set of permissions. You can add grants (extra permissions) and denials (removed permissions) for one user; a denial always wins.

Roles are managed under Settings > Access control, users under Settings > Users. The full procedures are in Users, roles and approvals.

The built-in roles#

The permissions#

Permissions are grouped as the role editor shows them.

Rules that always apply:

• Nobody can change their own role or permissions.
• The last active Super administrator cannot be demoted, disabled or deleted.
• An API key is governed only by the scope chosen for the key, never by a role.

1.3 Four-eyes approval (dual control)#

Some actions are critical. While dual control is on, a request to perform a critical action does not run at once. It is held until a second person with the right to approve it signs it off. Then the person who asked runs it.

The critical actions#

The defaults of a fresh install: dual control is on, Super administrators act alone is off, a reason is required, a pending request expires after 60 minutes without a decision, and an approved request must be executed within 15 minutes.

The flow, in short#

1. The requester makes the change in the console as usual and, when asked, types a reason.
2. The console says the request was sent for approval. Nothing has changed yet.
3. An approver opens Approvals > Waiting for me, reads the request and presses Approve or Reject (a rejection needs a comment).
4. The requester opens Approvals > My requests and presses Execute now within the execution window. The action runs once.

What makes it a control:

• Nobody approves their own request, whatever roles they hold.
• The approval covers exactly the request that was reviewed. A changed request is refused.
• An approval is used once.
• Changing users, roles or the policy is itself critical, so one officer cannot promote themselves or switch the control off first.

The first day: one approver#

A fresh install has one account. Nobody can approve their own request, so until a second approver exists every critical action of an approver runs on that one signature. Each such action is written to the audit trail as dual_control_bypassed with reason no_second_approver, and every console page shows the banner Four-eyes is inactive until a second approver exists.

The banner disappears as soon as a pair of approvers exists who can approve each other's user and policy changes: a second Super administrator, or an LSO and an RSO. Creating that pair is the last step of Installation.

What four-eyes does not cover#

./lawliet on the server runs as root (or as a member of the docker group, which is equivalent). It can read the database and .env, so console approvals do not apply to it: installing a licence with ./lawliet licence, building an offline agent package with ./lawliet agent-package, or resetting the administrator password with ./lawliet passwd needs no second signature. Shell access to the server is therefore the most privileged access there is. Limit it to the people who would hold the Super administrator account. See Security hardening of the server.

1.4 The licence#

• A licence key is a single line that starts with LAWLIET-. It is checked on the server against the vendor's signature. Licensing never needs network access.
• A licence is normally issued for one installation. Each installation has an installation fingerprint (32 hexadecimal characters). You send the fingerprint to your vendor and receive a key that works on that installation only.
• The fingerprint is kept in the lawliet_config Docker volume. It survives restarts, updates, rollbacks and database restores. It changes on a new server, or after ./lawliet uninstall (which deletes the volumes). Either is a new installation that needs a new licence.
• The licence decides which modules open and how many agents may enrol. When all agent seats are in use, the next enrolment is refused.
• Without a valid licence you can sign in and finish the first-login steps (password, two-factor), and the console shows the activation screen. Nothing else opens.
• When a licence expires, the platform pauses until a renewed licence is installed. Your data is untouched.
• The newest-issued valid licence always wins. An older key cannot replace a newer one.

Where you see it:

How to install a licence: Installation, step 2.10.

1.5 The air-gapped operating model#

Lawliet is built to run on a network with no route to the internet.

What crosses the boundary, and in which direction:

1.6 Words used in this guide#