Documentation
Getting Started
Enroll your first agent, verify a domain, review detections and set up remote actions, step by step.
1. Enroll your first agent#
Before you start, install osquery on the machine you want to monitor (osquery.io). The agent reads system state through it.
Then, as a Tenant Admin, open Agents and click Enroll agent. The panel walks you through four steps: download the agent with the command shown for your platform, check the download against its SHA-256 checksum, generate a one-time enrollment token (valid for 20 minutes and one machine, and shown only once), then copy the enroll and install commands.
Run the commands on the machine itself: with sudo on Linux and macOS, or in an elevated PowerShell on Windows. The install step sets the agent up as a background service that keeps running after you log out and starts again after a reboot. No config file editing is needed.
The agent appears on the Agents page once it checks in. Click its row to expand it and see four tabs: Overview (details, and Revoke for admins), Issue command, Reports (live changes the agent has reported since you opened the page) and History (every command sent to that agent).
The tiles at the top of the Agents page (Enrolled, Online, Offline, Revoked) double as filters: click one to show only those agents, or use the search box to find a host by name, agent ID or platform.
2. Verify a domain and run your first scan#
Active scans only run against domains your organization has proven it owns. As a Tenant Admin, open Verified domains, add the domain and publish the DNS TXT record Sokendi gives you; once the record is found, the domain is verified, along with all of its subdomains. Your plan sets how many domains you can verify: 3 on Standard and 15 on Pro (Enterprise: per contract). The Free plan runs passive lookups only, so it doesn't use verified domains.
On Pro and higher, active scans also need business verification. Under Settings → Verification, a Tenant Admin adds your organization's legal business name, and at least one admin must sign in with an email address on a verified domain (for example [email protected] for yourcompany.com). No ID documents are needed. The Verification tab shows what's done and what's left.
Then go to Scan, pick the verified target and a scan profile (or use the default), and start it. Results appear in Reports once the scan completes.
3. Review detections#
When an agent matches a known-bad file hash or one of its behavioral detectors fires (for example mass file encryption or a burst of failed logins), the detection appears under Threat Intel → Detections, tagged with its attack type. Mark each one Acknowledged while you look into it and Resolved when you are done, so your team can see what still needs attention.
4. Add a hash indicator (optional)#
Under Threat Intel → Hash Indicators, admins can add known-bad SHA-256 file hashes, each with an attack category. Every enrolled agent picks them up on its next policy fetch and flags a matching running process as Critical.
5. Turn on remote actions#
New organizations start with remote actions off, so agents refuse every command until a Tenant Admin enables them. On the Agents page, click Remote actions (next to Refresh). Everyone can open it to see what is allowed; only a Tenant Admin can change it.
Switch on Allow remote actions, then tick the actions your team needs. Rescan re-runs the agent's collectors on demand. Ad-hoc osquery lets analysts run read-only queries; when you tick it, choose which osquery tables can be queried (pick from Suggested tables, or click Add all for a group). Remediation lets Tenant Admins change a host; when you tick it, choose which of Kill process, Quarantine file and Disable user account are allowed.
A query only runs if every table it reads is on the list, including joins and subqueries: joining processes to users needs both. curl, curl_certificate and carves are never allowed, because they make the host send network requests or upload files.
Click Save. Agents pick up the change on their next policy check, usually within a minute or two. Turning on a remediation asks you to confirm first, and every change is recorded in the audit log.
6. Issue a remote command to an agent#
Expand an agent on the Agents page and open its Issue command tab. Choose Rescan, Ad-hoc query or Remediation. Analysts can run Rescan and Ad-hoc query; Remediation needs Tenant Admin, since it changes the host rather than just observing it.
If the last report was a while ago, run a Rescan first: process, file and account state may have changed. Under Advanced you can set a Timeout (10–3600 s), which is how long the command may wait for the agent before it expires.
After you click Issue command, the result appears under the form as Last result, with its status updating live (Pending, Acknowledged, Completed). Your query stays in the box so you can adjust it and run it again. Every command is also listed in the agent's History tab.
Remediation always asks you to confirm, showing the host, the action and the exact target. Every command is signed by the platform, and the agent checks the signature before it runs anything.
7. Find and stop a process#
Many programs run several processes (a web browser can have dozens), and you usually want the main one: stopping it stops the rest. Run an Ad-hoc query such as: SELECT pid, parent, name, cmdline FROM processes WHERE name = 'firefox'. The main process is the one whose parent is not another process with the same name; for browsers it is also the one without -contentproc in its command line.
In the results, click Kill… on that row. It fills in Remediation → Kill process with the PID; click Review remediation and confirm. Process IDs are reused, so do this right after the query rather than from an old report. Kill process stops the program immediately without letting it save anything; some programs and system processes (PID 1, the agent itself, critical Windows processes) are always refused.
8. Invite your team#
Under Team, an admin can invite teammates and give each a role (Viewer, Analyst or Tenant Admin) depending on what they need to do.