Skip to main content

Agent configuration

The host agent reads a JSON file at start. The install command writes it for you; use this page to change it or to set up an agent by hand.

The file​

{
"serverUrl": "https://vulnerability-operator.example.internal",
"agentKey": "vopa_...",
"heartbeatInterval": "60s",
"inventoryInterval": "6h",
"insecureSkipVerify": false
}
SettingDefaultMeaning
serverUrlAddress of the server. Use https:// in production.
agentKeyThe key of the agent, from its registration. Keep the file readable only by administrators.
heartbeatInterval60sHow often the agent reports that it is alive.
inventoryInterval6hHow often the agent sends its complete inventory.
insecureSkipVerifyfalseSkip the check of the server's certificate. Only for test systems.
scanPathsemptyExtra directories to catalog. See below.
fimPathsemptyFiles and directories the file integrity scan hashes. Empty turns the scan off. See below.
fimInterval1hHow often the agent sends the file integrity scan.
packageHookstrueInstall the package-manager hooks on Linux. See below.

Run the agent with its file:

vop-agent -config /etc/vop/vop-agent.json

Other options: -version prints the version of the binary, -request-scan asks a running agent for an inventory now, and -remove-hooks deletes the package hooks. On Windows the file is C:\vop\vop-agent.json, and the agent runs as the vop-agent service:

sc create vop-agent binPath= "C:\vop\vop-agent.exe -config C:\vop\vop-agent.json" start= auto
sc failure vop-agent reset= 0 actions= restart/5000
sc start vop-agent

The restart action is needed for self-updates: after an update the agent exits and the service manager starts the new binary. On Linux, run the agent under systemd with Restart=always; a self-update re-executes the new binary in place, so the process ID is kept.

Environment variables can override the file. The useful ones are VOP_SERVER_URL, VOP_AGENT_KEY, VOP_SCAN_PATHS (a comma-separated list), VOP_PACKAGE_HOOKS and VOP_MANAGED_UPDATES.

What the agent reads​

Without scanPaths the agent reads the package databases of the host, and does not walk the disk:

  • Linux: /var/lib/dpkg, /var/lib/rpm, /var/lib/pacman and /lib/apk/db, in the way the Wazuh syscollector does.
  • Windows: the installed programs in the uninstall keys of the registry, and the packages that winget installed (winget export, when winget is on the agent's path). No scanPaths is needed. The agent runs as a service, so winget must work under the system account; otherwise only the registry is reported.
  • macOS: the application bundles in /Applications, and the Homebrew formulas under /opt/homebrew or /usr/local. No scanPaths is needed.

To catalog application directories, such as the dependencies of a language project, add them:

{ "scanPaths": ["/opt/app"] }

Scanning / is slow and uses a lot of memory, so list the directories you need. On Windows, scanPaths with C:\ catalogs files as well as the registry.

Package hooks (Linux)​

On Linux the agent hooks into the package managers, so the inventory follows a change within seconds rather than at the next interval. The hooks are written when the agent starts, and again on each start, so an updated agent refreshes them:

  • apt: /etc/apt/apt.conf.d/99vop-inventory, a DPkg::Post-Invoke after each dpkg call.
  • pacman: /etc/pacman.d/hooks/vop-inventory.hook, a PostTransaction hook.
  • dnf 4: /etc/dnf/plugins/post-transaction-actions.d/vop-inventory.action. It needs the post-transaction-actions plugin of dnf-plugins-core.

After a transaction the hook runs vop-agent -request-scan. That only touches a trigger file, so the package manager never waits for a scan. The agent collects the inventory once the file has been quiet for five seconds, so one transaction gives one inventory.

To turn the hooks off, set "packageHooks": false or VOP_PACKAGE_HOOKS=false, and run vop-agent -remove-hooks. Change the setting first, or the next start writes the hooks again.

Not covered: dnf 5, zypper, yum 3 (RHEL 7), apk, and Windows and macOS. A container gets no hooks, including the host agent of the Kubernetes chart: a container cannot reach the package managers of its node.

File integrity monitoring​

The agent hashes every regular file under fimPaths and sends the list to the server. The server keeps the list of the previous scan and records each file that was added, changed (content or permissions) or deleted. The first scan only sets the baseline, so it records no changes. Symbolic links are not followed.

{
"fimPaths": ["/etc", "/usr/local/bin"],
"fimInterval": "1h"
}

The changes are read through the API: GET /api/v1/agents/{id}/fim-events returns the newest 500 changes of an agent. The scan runs on host agents only, and it is not real time: a change is seen at the next scan.

Containers​

A host agent that runs in a container is marked as one and does not update itself. Changes to a file in an image are lost on the next start. Roll out a new image instead; see Kubernetes agents.