Installing agents

What the agent is

The Holistra agent is a single binary that runs as a background service: systemd on Linux, launchd on macOS and a native service on Windows. It makes outbound HTTPS requests to your Holistra server and nothing else. It opens no ports, and the server never connects to it.

Once approved, it:

• reports the host as an asset, and any web service answering on ports 80, 443, 3000, 8000 or 8080 on the host's LAN address (hourly by default);
• reports installed software once a day, which the server matches against vulnerability data;
• reports device facts and security posture every six hours (disk encryption, firewall, antivirus, Secure Boot, automatic updates and more);
• reports its attack surface with the device facts: what starts automatically, local accounts and administrators, SSH keys, sudo rules, browser extensions and trusted root certificates;
• runs remediation and compliance scripts that your Admins or Security Engineers dispatch, and reports their output;
• updates itself to new signed releases, and rolls back by itself if a new version cannot reach the server.

It does not scan other machines or collect files.

Requirements

The endpoint needs outbound HTTPS to your Holistra server. Nothing needs to be opened inbound.

Install from the dashboard

Open Agents → Enroll. It shows a one-line command per operating system with your server address, your organisation's enrolment token and the server's job-signing key already filled in. Copy the command for the platform and run it on the endpoint. The commands look like this:

curl -sL "https://<your-server>/api/agents/install/linux?token=<enrolment-token>" | sudo bash
curl -sL "https://<your-server>/api/agents/install/macos?token=<enrolment-token>" | sudo bash

Invoke-WebRequest -Uri "https://<your-server>/api/agents/install/windows?token=<enrolment-token>" -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Each installer:

1. saves the server's TLS certificate, so agents keep verifying TLS against self-signed or internal-CA servers;
2. downloads the agent, checks its SHA-256 checksum and only then moves it into place (it retries and resumes on slow links, and installs nothing if the download stays broken);
3. writes the agent's settings to a configuration file only root or SYSTEM can read;
4. registers the service and starts it.

Running an installer again upgrades in place and keeps the agent's identity. To roll out to many machines, run the same command through your usual tooling (for example SCCM, PDQ or Ansible), or share the /enroll link the Agents page offers, which shows the commands and downloads for that token.

Approve the agent

A newly enrolled agent is pending. It can check in, but it reports nothing and receives no jobs until an Admin or Security Engineer approves it on the Agents page. The sidebar shows a count and the dashboard shows a banner while agents are waiting.

• Revoke is the kill switch. It takes effect at once, and approving again restores the same agent.
• Delete removes the agent's record but keeps its job history. To stop a machine for good, uninstall the agent first, then delete it.
• An agent shows as Offline when it has not checked in for five minutes.

What you see for each agent

Click an agent's hostname to open its device page: hardware, system, network interfaces, security posture, installed software (searchable), listening ports, attack surface and that agent's jobs. Refresh now asks the agent to report its facts and software straight away.

Software vulnerability matching

Installed packages are matched against the public OSV vulnerability database for Debian, Ubuntu, Alpine, Red Hat Enterprise Linux, Rocky Linux, AlmaLinux and SUSE/openSUSE. Each vulnerable package becomes a finding with its CVE, severity, fixed version and KEV/EPSS context, and closes by itself once a later inventory shows it fixed. Only package names, versions and the distribution are sent to OSV, never hostnames, addresses or other data about you.

Windows hosts are checked by their OS build against Microsoft's Security Update Guide, which raises findings for missing security updates. macOS applications, Windows programs, Homebrew and Fedora packages are listed but not matched, because there is no reliable public vulnerability data for them. Every OS is also checked for end of vendor support, and Linux hosts for a pending reboot into a patched kernel.

Posture and attack-surface findings

A failing posture check (for example, disk encryption off) opens a finding on the host with fix guidance for its operating system, and a passing check closes it. Admins can also turn on drift findings under Settings → System: the agent then raises a finding when a new persistence item, SSH key, administrator, sudo rule, browser extension or root certificate appears. Expected changes can be marked as such on the device page.

Check-in and collection settings

Under Settings → Agent updates → Check-in and collection, Admins set how often every agent checks in and collects data. Changes apply at each agent's next check-in.

Keeping agents up to date

The Agents page shows each agent's version. An outdated agent shows Update now. The agent downloads the new release, checks its checksum and its release signature, tests the new binary, swaps it in and restarts. If the new version cannot reach the server, the agent restores the previous one by itself and reports the update as rolled back.

Under Settings → Agent updates, Admins can switch the organisation to automatic updates and set:

• Hold at version: never update beyond a given version;
• Maintenance window: the days and hours (UTC) when updates may start;
• Rings: canary agents update first, standard agents follow after the canary period, and excluded agents only update by hand. If a canary's update fails, standard agents wait.

Remediation scripts and their safeguards

From a finding, an asset or a scan, an Admin or Security Engineer can send a script to the affected agents, either from the built-in script library or written by hand. Scripts run as root or SYSTEM, one at a time per agent, with a time limit. Output and exit code appear under Agents → Recent jobs, where a running script can also be stopped.

• Every job is signed by your server. The agent checks the signature against the key it received at install time, and refuses jobs that were altered, meant for another agent or organisation, already run, or more than 24 hours old.
• Auditors cannot dispatch scripts, and pending or revoked agents never receive them.
• A preview lists exactly which agents a dispatch will reach before anything is sent.

Rotating the enrolment token

Agents → Rotate token (Admin only) replaces the enrolment token and lets you choose how long the new one lasts: 1, 7, 30 or 90 days, or no expiry. The old token stops working at once. Agents that are already enrolled are not affected; only install commands, enrol links and packages that embed the old token stop working.

Rotate it when it may have leaked, when you see pending agents you don't recognise, when someone who had it leaves, after a mass rollout, and on a regular schedule.

Uninstalling

On the agent's device page, Uninstall sends a signed job: the server revokes the agent and the agent removes its own files and service. Then delete the agent on the Agents page. To remove it by hand:

sudo systemctl disable --now aetherion-agent
sudo rm /etc/systemd/system/aetherion-agent.service /usr/local/bin/aetherion-agent
sudo rm -rf /var/lib/aetherion /etc/aetherion /usr/local/etc/aetherion

sudo launchctl unload -w /Library/LaunchDaemons/com.aetherion.agent.plist
sudo rm /Library/LaunchDaemons/com.aetherion.agent.plist /usr/local/bin/aetherion-agent
sudo rm -rf "/Library/Application Support/Aetherion" /usr/local/etc/aetherion

Stop-Service AetherionAgent
sc.exe delete AetherionAgent
Remove-Item -Recurse "C:\Program Files\Aetherion", "$env:ProgramData\Aetherion"

Files, services and logs

The agent's service, file and setting names still use the product's earlier technical name. They will be renamed in a later release.

Running aetherion-agent --facts as root or Administrator prints the device report the agent would send. For common errors, see Troubleshooting.