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
}
| Setting | Default | Meaning |
|---|---|---|
serverUrl | Address of the server. Use https:// in production. | |
agentKey | The key of the agent, from its registration. Keep the file readable only by administrators. | |
heartbeatInterval | 60s | How often the agent reports that it is alive. |
inventoryInterval | 6h | How often the agent sends its complete inventory. |
insecureSkipVerify | false | Skip the check of the server's certificate. Only for test systems. |
scanPaths | empty | Extra directories to catalog. See below. |
fimPaths | empty | Files and directories the file integrity scan hashes. Empty turns the scan off. See below. |
fimInterval | 1h | How often the agent sends the file integrity scan. |
packageHooks | true | Install 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/pacmanand/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). NoscanPathsis 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/homebrewor/usr/local. NoscanPathsis 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, aDPkg::Post-Invokeafter each dpkg call. - pacman:
/etc/pacman.d/hooks/vop-inventory.hook, aPostTransactionhook. - dnf 4:
/etc/dnf/plugins/post-transaction-actions.d/vop-inventory.action. It needs thepost-transaction-actionsplugin 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.