The 24/7 watch

An investigation answers the question you asked. The watch answers the one nobody thought to ask: did anything about this machine change that should not have? A new administrator, a new thing that starts at boot, a port newly open to the network, a program running from a temporary folder. Those are what an intruder leaves behind, and they show up as changes long before they show up as damage.

It works in real time. The agent, running as a service, asks the operating system to tell it when the places that matter change, and reports each change as it happens: in the console within a few seconds, with an email for anything serious.

What it hears as it happens#

Each of these is a notification from the operating system, or a cheap check every few seconds where no notification exists. When one fires, the agent re-reads only that part of the machine, compares it with its baseline and sends what changed.

Changes that land together, such as an installer writing a dozen files, are sent together, so one install is one report. The machine’s page lists what its agent is subscribed to, and guardyn-agent service status prints the same on the machine.

Who signs in, and how hard the machine is working#

Besides what changes, the watch reports what happens: each one an event on the machine’s page, sent once, and something a hook in Settings → Alerts can send on.

Load is measured every ten seconds and disks every minute, from the same readings the analyst’s resource tool uses; a spike that is over in a minute is not an event. Agent 0.10.0 and later.

Every address in an alert says where it is: the country and whose network it belongs to (a hosting company, a home provider), or that it is on the machine’s own local network. That comes from files kept on guardyn’s server and refreshed monthly, so no address is ever sent to anyone to be looked up. IP locations by DB-IP (CC BY 4.0).

Privilege, accounts, services, files and deploys#

Agent 0.11.0 and later also report these, each an event a hook can send on. Most are read from the system’s own logs as they are written (the journal on Linux, the event logs on Windows), so nothing new runs on the machine to produce them.

The full check#

On start, and every hour after, the agent also runs every check it has and compares the whole machine with its baseline. It is the backstop: it covers what no notification reports (disk encryption, SIP, Secure Boot), anything that changed while the machine was off or the service stopped, and anything a notification missed. A change made while the agent was not running is not lost: it is still a difference from the baseline.

How it decides#

With rules and a baseline, never a model, so it spends no credits. The agent reduces what it reads to facts (one per thing that matters, named the same way every time) and compares them with the facts from its last accepted report. It sends what changed, and the signals its rules raised. The server keeps track of which signals each machine has already shown, so you hear about a signal once, when it first appears.

New processes get the rules the full process check uses: an executable in a folder anyone can write to, one that is not validly signed (checked once it has run for a couple of seconds, so a compiler’s helpers are not each a signature check), a command line shaped like a reverse shell or an encoded payload, and a document, browser or web server starting a shell. The same program from the same place is reported once an hour at most, and no machine sends more than 30 process alerts an hour, the last of them saying that more are being held back: a build that starts a thousand helpers is not a thousand alerts. Critical ones always go.

The first full check takes the baseline. Whatever it finds is the machine as it was when the watch started: it is listed on the machine’s page, and only what is high or critical becomes a finding. You do not get fifty alerts for the state the machine was already in.

Turning it on#

Install the agent as a service on the machine (the installation guide has all three platforms):

sudo guardyn-agent service install

On a paid plan the watch starts on its own once the service connects, and changing plan turns it on or off with nothing to reinstall. Real time needs agent 0.9.0 or later; an older agent checks on an interval until it is updated.

On every plan, Free included, the service keeps the machine connected, so it can be investigated at any time without anyone at it.

What each change is worth#

Something that starts automatically and points at an unsigned binary is high, whatever else is true of it. Protections switching off is high: antivirus, realtime protection, firewall, disk encryption, secure boot, SIP, Gatekeeper, automatic updates. Ways in switching on is medium: remote login, remote desktop, screen sharing.

Some things are left out on purpose, because they change on their own and would bury everything else. macOS’s own launch jobs on the sealed system volume are left out, and SIP being on is what protects them. So are listeners on loopback, which nothing on the network can reach, and the file hashes of programs signed by Apple or Microsoft, which change on every patch day. Their signature is still checked, so one swapped for an unsigned binary still shows up.

Where you hear about it#

• In the console, as it happens: everything at medium and above becomes a finding, marked as raised by the 24/7 watch, with what changed and what the agent noticed. Open pages update without a reload, and anything high or critical also shows as a notice wherever you are in the console. On a machine that allows emergency actions, a finding or an event on its timeline offers an owner or admin the ones that fit it.
• By email: the workspace’s owners and admins get a message when something at high or above is new (one per report, so changes that land together are one email), and one when a machine’s watch starts.
• In Slack: paste your Slack app’s bot token in Settings → Alerts and save (a link there creates the app with its permissions filled in). Events then go to the channel for their kind (#guardyn-security, #guardyn-signins, #guardyn-health, #guardyn-load, #guardyn-deploys, #guardyn-files), made the first time something goes there or joined if your team made it first. The people you list (by the emails they use in Slack), or else the workspace’s owners and admins, are added to each channel so it shows in their Slack; that needs the app’s users:read.email permission, which the link includes. Each alert comes with a picture card that says at a glance how bad it is and what happened, drawn by guardyn and uploaded into your Slack, shared in no channel; that needs files:write, which the link includes too, and without it alerts come as words only. Every value worth copying stays in the words. Nobody is mentioned, and rules choose which events go there, as for any other place. On a plan with guardyn actions, once the app’s signing secret is pasted in too, an alert about a machine that allows emergency actions carries a button for each one that fits: see From Slack.
• Through your own mail or WhatsApp: in Settings → Alerts, an owner or admin adds an SMTP server (TLS required, the password encrypted at rest), a SendGrid account (an API key allowed only to send mail, encrypted at rest) or a WhatsApp number (a phone linked once by QR code, like WhatsApp Web, and the numbers to alert), and rules that choose which events go to each, from what severity, and from which machines. Different people can get different things: one place per group of people, each with its own rules. If a place stops delivering, owners and admins are told by email, once, and what its rules held is sent once it works again.
• About WhatsApp: it works the way WhatsApp Web does, which WhatsApp does not officially support for automated messages and may answer by blocking the number. Link a number kept for alerts, not a personal one; the link can read that account’s chats, and it is kept on guardyn’s server, readable only by the service that sends. Messages are paced and capped at 120 an hour.
• A finding someone resolved that happens again is reopened and sent again. One marked a false positive stays closed.

What leaves the machine#

Only what changed, the signals raised, and a line naming what the agent noticed (the path that changed, or the event in the log): a few kilobytes per report. The baseline, which is the machine’s whole inventory, stays on the machine in watch-baseline.json in the agent’s state folder. Every report is written to the machine’s own audit log, which guardyn-agent audit prints. Nothing it finds is acted on by itself: where a machine allows emergency actions, an owner or admin decides each one. See guardyn actions.

The events above carry what they need and no more: a command run with sudo, with anything shaped like a password or token masked and at most 160 characters; a changed file’s path, owner and SHA-256, never its contents; commit ids and branch names; and for a GitHub Actions job the repository, workflow, run, actor, commit and branch. Of a job’s environment only those GITHUB_ values are read, never its secrets.

When it goes quiet#

A machine where nothing happens sends nothing but its hourly full check, so silence is normal. What the console watches for is the service itself, and the fleet and the machine’s page say the same thing about it: watching live while the service is connected, and reconnecting for the few minutes after its connection drops. Six minutes without it, a server says stopped reporting and its owners and admins are emailed; a laptop or desktop, which sleeps, says asleep or offline, noted on its timeline only. A machine that is connected but whose full check is overdue says watch stalled. On the machine itself:

guardyn-agent service status

It prints whether the service is running, what the watch is subscribed to, the last full check, the last thing it reported and the last error, if there was one. A report that could not be delivered is not lost: the baseline only moves once the server has accepted a report, so the agent keeps trying, and the next attempt carries the same changes.