Docs menu ▾
Node setup
Everything Genos puts on a host, and every setting you can change there. For a first install, follow the Quickstart; come here for detail.
What lives on a host
| Path | What | Created by |
|---|---|---|
/var/lib/genos-inventory/baseline.json |
Record of the one completed scan. Its presence stops any rescan | Scanner |
/etc/genos/agent.toml |
Where the daemon reports, and the server's pin | You |
/etc/genos/agent.ed25519 |
The host's private signing key (32 random bytes, mode 0600) |
You |
/var/lib/genos-inventory/agent_state.json |
The agent_id from enrollment and the last sequence number |
Daemon |
/usr/local/sbin/genos-daemon |
The enforcer daemon | cargo xtask install |
genos-daemon.service |
systemd unit; restarts the daemon on failure | cargo xtask install |
/etc/genos/policy.wasm + .sig + policy-ed25519.pub |
Grant policy and its signature (optional) | You |
/etc/genos/approver-ed25519.pub |
Key that signs grant requests (optional) | You |
/run/genos/grant.sock |
Socket for grant requests | Daemon |
Scanner
The scanner is one script, genos_scanner_enforcer/dist/scanner.sh. It downloads a pinned scanner
tarball from GENOS_SERVER, refuses it if the SHA-256 doesn't match, scans the host as root
reading metadata only, and uploads the report to GENOS_SERVER/baseline.
sudo GENOS_SERVER=<server>[:port] bash dist/scanner.sh
| Variable | Effect |
|---|---|
GENOS_SERVER |
Server to download from and report to. Required without a terminal |
GENOS_DEMO_ENFORCER=1 |
After a complete scan, record /etc/sudoers.d's identity and start genos-daemon. Needed for the enforcer demo |
GENOS_ALLOW_INCOMPLETE=1 |
Upload even when some probes fail. Such a scan is marked incomplete and never becomes a baseline |
Needs: Linux, root, python3 ≥ 3.10, curl, tar. Tested on Ubuntu 24.04.
It runs once. After a complete scan, the scanner refuses to run on that host again. To redo a
host, it has to be treated as a fresh install: delete /var/lib/genos-inventory/baseline.json on
the host and the host's baseline on the fleet server
(how).
If the upload fails, the report is kept in /var/lib/genos-inventory/ and the script prints a
curl command to resend it. Resend; don't rescan.
Agent config
/etc/genos/agent.toml, mode 0600:
server_url = "https://genossec.com"
server_spki_pin_sha256 = "7Ewfp4DcyhOyfn2DiwB0WJMTOvzW7K3ljtW+ytlwf2U="
enrollment_token = "genos_enr_..."
heartbeat_secs = 30
event_batch_max = 256
| Key | Required | Meaning |
|---|---|---|
server_url |
Yes | HTTPS origin only: no path, query or credentials |
server_spki_pin_sha256 |
Yes | Base64 SHA-256 of the server certificate's public key. The daemon checks the certificate normally and requires this pin |
enrollment_token |
First start | One-time token from flask create-token. Not needed once agent_state.json exists; delete it after the first start |
heartbeat_secs |
No (30) | Seconds between heartbeats. The server learns each node's interval, so changing it is safe |
event_batch_max |
No (256) | Most decisions per message |
The pin above is genossec.com's at the time of writing. Check the current one with the command in Quickstart step 3. It stays the same across certificate renewals because the server reuses its key; see Certificate pin.
The signing key is any 32 random bytes:
sudo sh -c 'head -c 32 /dev/urandom > /etc/genos/agent.ed25519' && sudo chmod 600 /etc/genos/agent.ed25519
It never leaves the host. If it's lost or replaced, the node can't sign as itself any more; it
needs a new token and a fresh enrollment (delete agent_state.json first).
Daemon
sudo systemctl status genos-daemon
sudo journalctl -u genos-daemon -f
| Log line | Means |
|---|---|
reporter initialized |
Config and key loaded; enrolled or already enrolled |
telemetry reporter not active: … |
It enforces, but won't report. The reason follows (missing config, bad pin, enrollment refused) |
enforcing; draining decisions |
Hooks are attached and blocking |
DENY create in protected dir … |
A write was blocked |
heartbeat send failed: … |
One heartbeat didn't arrive. Repeats make the node go red |
The daemon needs the scan record from a demo-mode scan (GENOS_DEMO_ENFORCER=1). It refuses to
start if /etc/sudoers.d was replaced since the scan. Stopping the daemon detaches the hooks:
nothing is enforced until it starts again.
Catalog
The catalog is the list of threat vectors the scanner checks. genossec.com publishes it:
export GENOS_CATALOG_URL=https://genossec.com/dashboard/catalog
export GENOS_CATALOG_SHA256=<from the dashboard's Catalog page>
With the pin set, the scanner refuses any catalog that differs by a single byte. The dashboard's Catalog page shows the current values, ready to copy.
These variables apply to the scanner package in genos_inventory/scanner, which downloads the
catalog at run time. The current dist/scanner.sh (0.3.0) carries its own copy of the catalog and
ignores them.