Shuffle
Security
Features
Usecases
Docs
Sign InGet Started

Search

Ctrl+K

Usability

5

  • Getting Started
  • About Shuffle
  • Tenants & Multi-Tenancy
  • Features Overview
  • API Reference

Automation

3

Security

4

Infrastructure

4

Host Monitors in Shuffle Security

8 min read
frikky
Edit on GitHub
8m to read

On this page

Overview
Using the Host Monitors dashboard
Dashboard Features
Deploying a Host Monitor
Adding a Host via the Web UI
Install Commands
Posture checks
1. Hard Drive Encryption (hdencrypted)
2. Screen Lock Enforcement (screenlock)
3. Active Monitoring (logforwarding)
Installed software & code package scanning
Installed Software Inventory
Code Package Scanner
Remote web terminal & response actions
Remote Web Terminal
Response Actions
Host Monitoring Use Cases
Cross-platform architecture
Datastore architecture: assets, software, packages & sensors
Datastore Navigation
Category Schemas
Accessing Host Data in Python Apps & Workflows
Key Revisions, Audit Trail & Rollback Protection
API & Datastore reference
Backend Endpoints
In Custom Python Apps & Workflows

Documentation for monitoring endpoint compliance, inspecting installed software and code dependencies, using the remote web terminal, and running host response actions in Shuffle Security.

Overview

Shuffle Security (shuffle.security/monitors) provides lightweight endpoint posture monitoring, software/dependency discovery, and live remote response across macOS, Windows, and Linux hosts.

Instead of deploying a separate endpoint tool that cannot talk to your incidents or vulnerabilities, Host Monitors connects your endpoints directly to your Shuffle workspace so you can verify compliance, spot vulnerable packages, and run live forensics or containment from a single UI.

  • Compliance & Posture Checks: Continuously verify that endpoints have full-disk encryption (FileVault, BitLocker, LUKS) and screen lock timeouts enabled.
  • Software & Code Dependency Discovery: Catalog installed OS applications and scan local developer repositories (package.json, requirements.txt, Cargo.toml, go.mod) to surface CVEs in Vulnerabilities.
  • Browser-Based Remote Web Terminal: Open an interactive shell on any monitored host over outbound WebSockets without opening inbound SSH or firewall ports.
  • One-Click & Automated Response Actions: Isolate compromised hosts, capture screenshots, or run diagnostic commands from the UI or directly from Shuffle workflows.
Note

Zero License Paywalls
Host Monitors is included in both Shuffle Cloud and self-hosted open-source deployments with no per-seat or per-agent license fees. Normal heartbeats and posture checks consume zero app runs; standard app runs only execute when your automation workflows trigger remote actions.


Using the Host Monitors dashboard

Navigate to /monitors to view compliance posture and manage all registered endpoints across your fleet:

Dashboard Features

  • Posture Summary Tiles: View fleet-wide counts of hosts passing compliance checks (disk encryption and screen lock), cataloged software applications, active code package scanners, and hosts with response actions enabled.
  • Monitoring Group Selector: Switch between monitoring groups in the top-right header and check live heartbeat status (healthy, stale, offline).
  • Platform Tabs & Search: Filter hosts by operating system (All, macOS, Windows, Linux) or search by hostname and IP address.
  • Host Table Columns:
    • Host: Hostname, OS platform, and primary IP address.
    • Operating System: OS release and kernel/build version.
    • Last Seen: Relative heartbeat timestamp with an online or offline status indicator.
    • Compliance Checks: Pass/fail indicators for Hard Drive Encryption and Screen Lock.
    • Installed Software: Count of discovered applications on the host.
    • Code Scanner: Status of local repository dependency scanning.
    • Actions: Launch the Remote Web Terminal or trigger predefined host response actions.
  • Host Detail Drawer: Click any host row to open a slide-out detail panel showing hardware specifications (CPU, RAM, disk, MAC address), posture check details, searchable installed software, scanned project dependencies, and remote action history.

Deploying a Host Monitor

Use the interactive panel above, or navigate to /monitors and click Add Host in the top-right header bar to generate an installer command for your endpoint.

Adding a Host via the Web UI

  1. Navigate to /monitors in Shuffle Security.
  2. Click the Add Host button in the header bar.
  3. Select an existing Monitoring Group or click New to create one (each group maps to a Runtime Location queue).
  4. Choose which capabilities to enable on the host:
    • Hard Drive Encryption (hd_encrypted)
    • Screenlock Enabled (screenlock)
    • Installed Software (installed_software)
    • Code Package Scanner (code_scanner_enabled)
    • Response Actions (response_actions)
  5. Select your target operating system (Linux, macOS, or Windows) and copy the generated command.

Install Commands

Easy Install (One-Liner)

The Add Host dialog generates a pre-authenticated one-liner for your tenant and monitoring group:

macOS & Linux:

cURL

Editable

Response

Windows (PowerShell as Administrator):

powershell

Editable

Response

Custom Install (Standalone Binary)

If you prefer to deploy the binary manually or via configuration management (Ansible, Chef, Puppet, MDM):

  1. Download the orborus binary for your OS and CPU architecture from github.com/Shuffle/orborus/releases.
  2. Run the binary with sensor mode flags:

    Bash

    Editable

    Response


Posture checks

Host Monitors continuously evaluate endpoints against baseline security controls and report compliance back to /monitors:

1. Hard Drive Encryption (hd_encrypted)

Verifies that full-disk encryption is active on the primary system volume:

  • macOS: Checks Apple FileVault 2 status.
  • Windows: Checks BitLocker protection status on the OS drive (C:).
  • Linux: Checks for LUKS encryption on root and user partitions.

2. Screen Lock Enforcement (screenlock)

Verifies that the operating system locks the display after a maximum of 15 minutes of user inactivity and requires password or biometric authentication immediately upon wake.

3. Active Monitoring (log_forwarding)

Active event and log streaming from monitored hosts is currently in development and not generally available yet.


Installed software & code package scanning

Installed Software Inventory

When Installed Software (installed_software) is enabled on a host:

  • The monitor catalogs operating system applications, packages, and binaries along with their version strings and install paths.
  • You can inspect a host's applications in the Software tab of the host detail drawer at /monitors, or click any application to view all hosts running that software at /software/<name>.

Code Package Scanner

When Code Package Scanner (code_scanner_enabled) is enabled on developer workstations or build servers:

  • The monitor scans local project directories for dependency manifests: package.json (npm/yarn), requirements.txt / Pipfile (pip), Cargo.toml (Cargo), and go.mod (Go).
  • Discovered dependencies and versions are checked against OSV.dev.
  • Vulnerable packages are linked to the host and filesystem path in Vulnerabilities, and you can inspect every host containing a specific library at /packages/<name>.

Remote web terminal & response actions

Remote Web Terminal

Open an interactive shell on any monitored host from the Actions column in /monitors, inside the host detail drawer, or at /monitors/:id/terminal:

  • Zero Inbound Ports: The monitor communicates over an outbound WebSocket connection to your Shuffle server—no inbound SSH ports, VPNs, or public IPs are required on the endpoint.
  • Live Triage & Forensics: Run diagnostic commands (ps aux, netstat, df -h, log inspection) directly in your browser and share terminal output across your team.

Response Actions

When Response Actions (response_actions) is enabled on a host, admins and authorized workflows can trigger predefined actions from the host detail panel or /monitors/response:

  • Screenshot (screenshot): Captures the current display of the active user session.
  • Isolate Host (isolate_host): Restricts network connectivity on the endpoint while keeping the Shuffle management channel alive (requires root on Linux/macOS or SYSTEM on Windows).
  • Unisolate Host (unisolate_host): Restores normal network connectivity on an isolated endpoint (requires root or SYSTEM).
  • Disable RCE (disable_rce): Permanently disables remote command execution on the host monitor daemon.
  • Windows Remote Control (remote_control): Sends automated input actions (mouse click/move, keystrokes, shortcuts) on Windows hosts.
Note

Controlled execution (restricting commands to pre-approved script files) is currently in development. You can manage which automated response actions AI agents are permitted to run at /monitors/response.

Host Monitoring Use Cases


Cross-platform architecture

Under the hood, Host Monitors runs Orborus (Shuffle's lightweight Go worker binary) in sensor mode (--sensor_mode=true) rather than requiring a separate third-party agent:

PlatformSupported VersionsMonitored Controls
macOSmacOS 12 Monterey, 13 Ventura, 14 Sonoma, 15 SequoiaFileVault 2 disk encryption, screen lock idle timeout, installed applications catalog, local repository manifests
WindowsWindows 10, Windows 11, Windows Server 2016+BitLocker drive protection, screen lock inactivity policy, installed applications, local repository manifests
LinuxUbuntu, Debian, RHEL, CentOS, Fedora, ArchLUKS volume encryption, screen lock idle timeout, system packages, local repository manifests

Each Monitoring Group in /monitors maps to an Orborus sensor queue, allowing you to segment endpoints by environment or location (e.g. production-eu, corporate-laptops, staging) while orchestrating actions from Shuffle workflows.


Datastore architecture: assets, software, packages & sensors

Host Monitors stores endpoint telemetry across four specialized datastore categories so hardware specs, application inventories, manifest dependencies, and live heartbeats remain decoupled and fast to query:

  1. shuffle-security_assets: Hardware inventory, system specifications, ownership, and network metadata.
  2. shuffle-security_software: Operating system applications, daemon versions, and installed binary catalogs across hosts.
  3. shuffle-security_packages: Code libraries and project manifest dependencies (package.json, requirements.txt, Cargo.toml, go.mod) scanned from developer repositories.
  4. shuffle-security_sensors: Monitor daemon runtime state, heartbeats, posture check baselines (hd_encrypted, screenlock), and response capabilities.

Datastore Navigation

Inspect these categories directly in the Datastore console:

Category Schemas

1. Hardware Assets (shuffle-security_assets)

Keyed by hostname or asset identifier (e.g. srv-prod-db-01 or dev-macbook-pro-14).

FieldTypeDescription
idStringUnique asset identifier (e.g. asset-srv-prod-01).
hostnameStringPrimary hostname reported by the endpoint.
osStringOperating system name and release (e.g. Ubuntu 22.04.4 LTS, macOS 15.1 Sequoia).
architectureStringCPU architecture (x86_64, arm64).
cpu_coresNumberNumber of virtual or physical CPU cores.
ram_gbNumberTotal physical memory in gigabytes.
disk_gbNumberTotal system storage capacity in gigabytes.
ipStringPrimary IPv4 address.
mac_addressStringNetwork interface MAC address.
serial_numberStringHardware or hypervisor serial number.
environmentStringEnvironment tier (production, staging, workstation).
tagsArrayOrganizational labels (e.g. ["database", "postgresql", "critical"]).
ownerStringResponsible email or team handle.
statusStringLifecycle status (active, decommissioned, maintenance).

2. Installed Software (shuffle-security_software)

Keyed by software identifier (e.g. sw_docker_engine_26, sw_openssh_server_9).

FieldTypeDescription
nameStringApplication or binary name (e.g. Docker Engine, OpenSSH Server).
versionStringDetected software release version string.
publisherStringVendor or software maintainer.
install_typeStringPackaging format (system_binary, deb_package, rpm_package, application_bundle).
install_pathStringPrimary executable path (e.g. /usr/bin/docker, /Applications/Google Chrome.app).
hosts_countNumberTotal count of fleet endpoints running this application.
associated_hostsArrayList of hostnames where this software version was detected.
last_scannedNumberUnix epoch timestamp of the most recent inventory sweep.

3. Scanned Packages (shuffle-security_packages)

Keyed by package identifier (e.g. pkg_lodash_4_17_20, pkg_requests_2_31_0).

FieldTypeDescription
nameStringPackage library name (e.g. lodash, requests, xz-utils).
versionStringExact installed version discovered in manifest.
ecosystemStringPackage ecosystem (npm, pip, cargo, go, deb, maven).
manifest_fileStringSource manifest filename (package.json, requirements.txt, Cargo.toml, go.mod).
repository_pathStringAbsolute directory path where the dependency manifest resides.
hostStringHostname of the machine running the code scanner.
has_vulnerabilityBooleanTrue if the package version matches an active OSV/CVE advisory.
advisory_idStringLinked CVE or GHSA identifier (e.g. GHSA-7867-xwm8-2v3q), or null if clean.
fixed_versionStringRecommended patched version if vulnerable.

4. Sensor Telemetry & Posture (shuffle-security_sensors)

Keyed by host sensor ID (e.g. sensor_srv_prod_db_01).

FieldTypeDescription
host_idStringUnique daemon runtime identifier.
hostnameStringHostname associated with the daemon instance.
platformStringOperating system family (linux, macos, windows).
agent_versionStringRunning Orborus sensor version.
sensor_groupStringConfigured Orborus queue group (e.g. production-eu).
statusStringDaemon heartbeat status (online, offline).
last_heartbeatNumberUnix epoch timestamp of the latest ping.
complianceObjectPosture check results: hd_encrypted, screenlock, filevault, firewall_active.
capabilitiesArrayEnabled monitor features: installed_software, code_scanner, remote_terminal, response_actions.

Accessing Host Data in Python Apps & Workflows

Python

Editable

Response

Key Revisions, Audit Trail & Rollback Protection

Every key across all four monitor categories (shuffle-security_assets, shuffle-security_software, shuffle-security_packages, shuffle-security_sensors) is stored with immutable revisions:

  • Endpoint Configuration Drift & Overwrite Protection: If a sensor re-registers or a scan is interrupted, previous software catalogs and asset records remain stored in revision history and can be restored at any time.
  • Audit Trail of Host & Package Changes: Tracks when software packages were upgraded, when new developer dependencies were introduced, and when posture compliance (hd_encrypted, screenlock) changed state.
  • Inspecting & Rolling Back Revisions:
    • Fetch revisions for any asset or package via REST API:

      API Call

      GET
      cURL
      Python
      HTTP

      Response

      No response received.

    • Roll back state in Python:

      Python

      Editable

      Response


API & Datastore reference

Backend Endpoints

  • List Sensor Groups / Environments: GET /api/v1/getenvironments (filter by sensor_group === true)

  • Execute Remote Host Action:

    API Call

    POST
    cURL
    Python
    HTTP
    JSON

    Response

    No response received.

  • Query Host from Datastore Directly:

    API Call

    POST
    cURL
    Python
    HTTP
    JSON

    Response

    No response received.

In Custom Python Apps & Workflows

Python

Editable

Response

For more details on backend API endpoints and datastore caching rules, see the API documentation.