Skip to content

Agent Lock — protect the server from Vesana

Formerly “local approval”

The feature is now called Agent Lock. Commands, files and behaviour are unchanged.

Vesana distributes scripts, commands and log sources centrally to agents and collectors. That is convenient, but it also means: whoever takes over Vesana (stolen admin account, compromised Vesana server) can run code on every monitored server.

With Agent Lock the server decides for itself what may run on it. Code delivered by Vesana only runs if it has been approved on the host. Monitoring keeps running.

  • Host only: turning it on or off and approving works exclusively with a command on the server itself. Vesana only displays the state.
  • Approval by fingerprint: each approval covers exactly one content (SHA-256 over kind, interpreter and content). If someone changes a single character in Vesana, the changed version only runs after it is approved again.
  • Nothing breaks: after a change, the last approved version keeps running until the new one is approved.

What is locked — and what keeps running

Needs approval Keeps running without approval
Agent: script checks (agent_script, including "local path"), command checks (agent_custom) All built-in checks: CPU, RAM, disk, services, processes, event log/journald checks, containers, ping, certificate, deep analysis
Agent: log sources (file, journald, Windows event log, auditd)
Collector: API scripts (kind "Collector script", run on the collector machine), SSH scripts and SSH commands on devices, plugins Collector: ping, port, HTTP, SNMP, SSL, the fixed SSH checks (CPU/RAM/disk/process/service), discovery

In addition, always (even without the lock): adjustable script values only reach the script as VESANA_* variables.

Turning it on

During installation: in the install dialog, tick "Protect this server from Vesana". The command then carries VESANA_LOCK=1 (Linux) or -Lock (Windows); the lock is active from the first start, nothing is approved yet.

Later (as root or in an administrator PowerShell):

sudo vesana-agent lock

& 'C:\Program Files\Vesana Agent\vesana-agent.exe' lock

sudo /opt/vesana-collector/vesana-collector lock

sudo /opt/vesana-active-collector/vesana-active-collector lock

Collector and active collector run from the root-owned file under /opt; the service account, which also runs scripts from Vesana, cannot replace it. Older installations still ran from a file under /var/lib/… owned by the service account — run the installer once more there; it switches over and removes the old file. The collector refuses lock as root from a file the service account could replace.

lock shows what Vesana currently runs on the host and asks whether to take it over. With Y, everything keeps running as before — only new or changed items wait for approval. lock status --show shows the contents first. The lock takes effect within seconds, without a restart.

Approving

When a check is added in Vesana or a script changes, the check shows "Waiting for approval on the host" (and the host header shows the Agent Lock chip with the number of waiting items).

sudo vesana-agent lock approve

approve shows each waiting item — for a new version, the diff against the approved one — and asks for each (j/y, a = all remaining, q = cancel).

What is shown is exactly what gets approved:

  • Control characters, terminal sequences and bidirectional overrides are written out visibly (lock status --show and lock approve); if an item contains such characters, a warning appears above it. Names stay on one line.
  • If two versions differ only in whitespace or line endings, the diff does not call them "the same" but marks the characters (␠ space, ⇥ tab, ␍ carriage return).

More commands:

Command Effect
lock status state, number of approvals, waiting items
lock approve --all all waiting items at once (shows them, asks once)
lock approve --all --yes without asking — for your own automation
lock approve --sha256 <fp>[,<fp>…] approve exactly these contents
lock prune remove approvals nothing uses anymore
unlock turn the lock off (approvals are kept)

Blanket approval

approve --all --yes approves whatever Vesana currently sends — unseen. Running it automatically on a schedule (e.g. cron) effectively turns the lock off. Every blanket approval appears in the host history in Vesana.

Many servers at once

When a script that runs on many locked servers changes:

  1. Run lock approve on one server and review the diff.
  2. At the end, approve prints a line such as vesana-agent lock approve --sha256 3f9a….
  3. Run that line on the other servers — via SSH loop, Ansible, GPO or PowerShell remoting. It approves exactly this content only. If Vesana delivered something different to a server, the fingerprint does not match and nothing is approved.

The overview under Admin → Agents & Collectors → Agent Lock shows which version is waiting on which servers.

Your own scripts on the host

Scripts that only exist on the server are added as before via the "local path" script mode. With the lock active, additionally:

  • Path and interpreter need an approval (otherwise Vesana could point the path at any file).
  • The file and its directories must only be writable by root or administrators — the agent runs them as root/SYSTEM. Otherwise the check reports what to do (e.g. chmod go-w …).

Plugins and collector scripts

  • Plugins (plugin_local) only run with an absolute path while the lock is active. Program and arguments are approved; for plugins that Vesana syncs into the collector's plugin folder, the file content as well — also when such a plugin is only passed as an argument to another plugin (e.g. negate <plugin>). A private copy of exactly the checked bytes is then executed — swapping the file between check and start runs nothing unchecked.
  • API scripts run locally on the collector machine and therefore have their own kind ("Collector script"). An approval of the same script for SSH does not count for it.

An approved journald or event log source reads exactly the approved units or channels — regardless of how the server spells them. An approval for a single service cannot be used to read the whole system journal or other event log channels.

The agent reads log files as root. It follows a symbolic link in a log path (including a linked directory) only if the link belongs to root or if its target belongs to the same user as the link. Otherwise it does not read the file and writes a message with path and reason to the agent log. Nothing changes on Windows.

Limits

Agent Lock prevents a taken-over Vesana from running code on the server. It does not prevent:

  • monitoring data and approved logs from being read,
  • checks from being turned off or alerts from being falsified,
  • approved scripts from running with different values (VESANA_*) or at a different pace. Scripts should therefore never execute values as code (no eval, no Invoke-Expression).

A taken-over Vesana cannot replace the agent or collector binary itself: self-updates are signed by the vendor and checked before they are installed (see Signed updates). For the collector, the binary under /opt belongs to root; an update replaces it only through a root helper that verifies the signature again.

Vesana itself has a second barrier in front of this: by default, anyone who changes scripts or commands must confirm their identity first (see Confirm script changes). That protects against a hijacked login session. Against a taken-over server, only Agent Lock helps.

Where approvals are stored

Location
Agent (Linux) /var/lib/vesana-agent/lock/
Agent (Windows) C:\ProgramData\Vesana\Agent\lock\ (SYSTEM + administrators only)
Collector /etc/vesana-lock/collector/
Active collector /etc/vesana-lock/active-collector/

If the approval file is damaged, the lock stays active and nothing that needs approval runs; lock status shows why, lock reset --yes recreates it.