Agent reference

Command reference

The agent has two programs:

• sec-agent: collects the inventory, connects to SEK Systems and carries out approved jobs. It also has commands to inspect and change the local situation.
• sec-supervisor: starts the agent from slot A or B and switches back when an update does not come up healthy.

Run the commands as root on Linux (sudo) and in PowerShell as Administrator on Windows. Commands that only read (such as policy and role status) also work without root if the files are readable, but the state directory is root-only.

Note

Never start sec-agent run by hand next to the service: the service already runs the agent. The commands below are for inspection and local changes.

#Overview

Global option for every sec-agent command: --log <filter> sets the log detail (for example --log debug); logs go to standard error. The same can be set with the environment variable SEC_LOG.

#version

sec-agent --version

Prints sec-agent <version>, for example sec-agent 0.3.60. The console shows the same version per host.

#policy

sudo sec-agent policy

Shows the effective local policy: what the agent will actually allow, after defaults. Example:

source:            /etc/sec/policy.toml
profile:           patch
allowed_actions:   ["app.install_msi", "app.upgrade", "config.set", "firewall.block_public", "firewall.restrict", "module.blacklist", "os.install_msu", "os.update_kb", "package.repair", "package.upgrade", "registry.set", "service.restart", "service.stop", "sysctl.set"]
deny_packages:     []
deny_units:        ["sec-agent*", "sek-agent*"]
local_windows:     1 (local time)
max_jobs_per_hour: 10
dry_run_only:      false
allowed_roles:     ["agent"]
self_update:       true
sha256:            2e6de5a8…

The sha256 is the hash of the policy file. The console shows the policy each agent reports (Agents → host → Local policy), so you can compare. Options: --policy <file> to show another file, --state-dir <dir>.

There is no command to edit the policy: edit the file as root or Administrator. The agent picks up a change within seconds. See Local policy.

#role

sudo sec-agent role status
sudo sec-agent role allow relay
sudo sec-agent role allow probe --cidr 192.168.10.0/24 --cidr 192.168.20.0/24
sudo sec-agent role deny probe
sudo sec-agent role deny probe --clear-cidrs

Besides being an agent, a host can take on an extra role. SEK Systems can ask for a role, but the host must allow it locally first.

• role status prints the policy path, the allowed roles, the probe segments, the roles SEK Systems requested, and per requested role whether the local policy allows it (ok, or refused (<reason>) -> sec-agent role allow <role>).
• role allow <role> adds the role to allowed_roles in the policy file. For probe, --cidr adds the segments the probe may test (at most 16 per command, /8 or narrower; IPv6 /16 or narrower). The probe role does nothing without at least one segment.
• role deny <role> removes the role. For probe, the segments stay in the file unless you add --clear-cidrs.

allow and deny need root. They validate the change, then replace the file atomically and print the result, for example /etc/sec/policy.toml: allowed_roles = ["agent", "relay"] (the running agent applies it within 30 s). The agent reports the change to SEK Systems with its cause (role_allow or role_deny); you can be notified of local policy changes (Settings → Notifications).

#collect

sudo sec-agent collect           # summary
sudo sec-agent collect --json    # the full inventory, exactly as it would be sent

Collects the inventory once, prints it, and sends nothing. The summary lists the host, number of packages, services, listening ports, containers, language and image packages, software outside the package manager, and whether a reboot is required. Use --json to see exactly what the agent reports about this host; see also What the agent collects.

#update-check

sudo sec-agent update-check --update-repo https://console.sek.systems/repo/tuf/

Checks whether a newer agent release is available, using the local trust anchor, and prints the result as JSON. It never downloads into a slot and never switches. For each mirror that fails it says why: dns, tls, timeout, refused, connect, blocked, http or tuf (signature or metadata problem). Use it when the console reports that self-update is not possible, or to test the network path. Without --update-repo it only tries the mirrors from the signed configuration that SEK Systems sent.

#keys

sudo sec-agent keys status

Shows how the agent's identity and keys are stored on this host: for example sealed with the TPM (Linux, Windows) or Windows DPAPI, or as files that only root or SYSTEM can read.

keys unseal exists for support cases only (before a deliberate downgrade to a much older agent); do not use it otherwise. The same goes for the storage subcommands: use them only when SEK Systems support asks you to.

#enroll

Only needed for a manual installation; the installation line runs it for you.

sudo SEC_ENROLL_TOKEN='<token>' sec-agent enroll --server https://console.sek.systems --profile patch

Enrollment tokens are created under Agents → Add agent → Manual steps (advanced). Errors from the server:

#install and uninstall (Windows)

The PowerShell installation line runs sec-agent.exe install for you. To remove the agent:

$slot = (Get-Content "C:\Program Files\SEC\current.txt").Trim()
& "C:\Program Files\SEC\$slot\sec-agent.exe" uninstall              # removes everything
& "C:\Program Files\SEC\$slot\sec-agent.exe" uninstall --keep-state # keeps C:\ProgramData\SEC

See Uninstall the agent.

#sec-supervisor status

sudo sec-supervisor status --dir /opt/sec-agent

& "C:\Program Files\SEC\sec-supervisor.exe" status

Prints the supervisor state as JSON: active (the running slot), trial (an update being tried), last_failure (the last update that was rolled back) and last_commit (the last accepted update). The default directory is /opt/sec-agent on Linux and C:\Program Files\SEC on Windows. See Agent updates.

#Exit codes