Host Monitors in Shuffle Security

Datastore Navigation

Access these categories directly in the Datastore console:

• Assets Console: /admin/datastore?category=shuffle-security_assets (Shuffle Core Datastore)
• Software Inventory: /admin/datastore?category=shuffle-security_software (Shuffle Core Datastore)
• Scanned Packages: /admin/datastore?category=shuffle-security_packages (Shuffle Core Datastore)
• Sensor Telemetry: /admin/datastore?category=shuffle-security_sensors (Shuffle Core Datastore)
• Manual UI Navigation: Go to Admin -> Datastore -> select desired category.

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).

2. Installed Software (shuffle-security_software)

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

3. Scanned Packages (shuffle-security_packages)

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

4. Sensor Telemetry & Posture (shuffle-security_sensors)

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

Accessing Host Data in Python Apps & Workflows

# 1. Check endpoint posture baseline
sensor = self.get_cache("sensor_srv_prod_db_01", category="shuffle-security_sensors")
if sensor:
    compliance = sensor.get("compliance", {})
    if not compliance.get("hd_encrypted"):
        print(f"Non-compliant host: {sensor.get('hostname')} lacks disk encryption")

# 2. Correlate vulnerable packages with host assets
package = self.get_cache("pkg_lodash_4_17_20", category="shuffle-security_packages")
if package and package.get("has_vulnerability"):
    target_host = package.get("host")
    asset = self.get_cache(target_host, category="shuffle-security_assets")
    print(f"Alert: {package.get('name')} {package.get('version')} is vulnerable on {target_host} (Owner: {asset.get('owner')})")

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 automatically stored with immutable revisions.

• Endpoint Configuration Drift & Overwrite Protection: If a sensor re-registers, a network glitch reports empty installed software, or a package manifest scan is truncated mid-flight, previous software catalogs and asset configurations are never permanently lost. Historical states can be queried and restored at any time.
• Audit Trail of Host & Package Changes:
  • Provides a tamper-resistant historical log showing when software packages were upgraded, when new developer dependencies were introduced, and when posture compliance (hd_encrypted, screenlock) changed state.
  • Links every state change to the specific Orborus execution ID, daemon ping, or administrative user session.
• Inspecting & Rolling Back Revisions:
  • Fetch revisions for any asset or package via REST API:

    API Call

    GET

    cURL

    Python

    HTTP

    CopyTest

    curl -X GET 'https://uk.shuffle.security/api/v2/datastore/category/shuffle-security_assets/{hostname}/revisions' \
      -H 'Authorization: Bearer <api_key…'

    Response

    Close

    No response received.

  • Roll back state in Python:
    python

    # Fetch package revisions to see previous version or recover dropped data
    pkg_revisions = self.get_cache_revisions(key="pkg_lodash_4_17_20", category="shuffle-security_packages")
    if len(pkg_revisions) > 1:
        # Revert to known-good baseline
        self.set_cache(
            key="pkg_lodash_4_17_20",
            value=pkg_revisions[1]["value"],
            category="shuffle-security_packages"
        )
    

Deploying a Host Monitor

Adding a Host via the Web UI

1. Navigate to /monitors in Shuffle Security.
2. Click the "+ Add Host" button in the top-right header bar.
3. Select or create a Monitoring Group (each group links to an Orborus queue and runtime location).
4. Choose the checks to enable:
   • 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 platform (Linux, macOS, or Windows) and installation method (Easy Install or Custom Install).

Install Commands

Easy Install (One-Liner)

The Add Host dialog generates an automated installation command pre-configured with your instance URL, queue, and authentication header:

macOS & Linux:

curl -X GET 'https://uk.shuffle.security/api/v1/orborus?base_url=<SHUFFLE_URL>&sensor_mode=true&queue=<QUEUE>' \
  -H 'Auth: <AUTH_KEY>'

Windows (PowerShell as Administrator):

powershell -ExecutionPolicy Bypass -Command "& {iex (irm 'https://shuffler.io/api/v1/orborus?base_url=<SHUFFLE_URL>&sensor_mode=true&queue=<QUEUE>&os=windows' -Headers @{'Auth'='<AUTH_KEY>'})}"

Custom Install (Binary)

You can also download the standalone orborus binary directly from the official releases:

1. Download the latest binary for your architecture from github.com/Shuffle/orborus/releases.
2. Execute the binary with sensor mode flags:
   bash

   ./orborus \
     --base_url="https://<your-shuffle-instance>" \
     --sensor_mode=true \
     --queue="<QUEUE_NAME>" \
     --org_id="<ORG_ID>" \
     --auth="<AUTH_KEY>" \
     --software_list_enabled=true \
     --hd_encrypted_check=true \
     --screenlock_check=true \
     --code_scanner_enabled=true \
     --response_actions=full
   

Posture checks

Host Monitors continuously evaluate endpoints against defined posture controls:

1. Hard Drive Encryption (hd_encrypted)

Verifies full-disk encryption is active on the system drive:

• macOS: Queries Apple FileVault status.
• Windows: Checks BitLocker drive encryption 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 screen after a maximum of 15 minutes of user inactivity:

• Checks system policies and inactivity timeouts.
• Verifies that a password or biometric authentication is required 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 inventory

When installed_software is enabled, the monitor catalogs applications and packages installed on the machine:

• Records application names and version strings.
• Helps identify unapproved software or outdated binaries across developer laptops and servers.
• Results appear in the Software tab of the host detail drawer at /monitors.

Code package scanner

When code_scanner_enabled is active, the monitor inspects local project directories on the host:

• Scans package manifests: package.json (npm/yarn), requirements.txt / Pipfile (pip), Cargo.toml (Cargo), and go.mod (Go).
• Evaluates discovered dependencies against OSV.dev.
• Automatically populates findings in Vulnerabilities, recording the affected hostname and filesystem path.

Remote web terminal

Shuffle Security provides an embedded Remote Web Terminal accessible from the host detail panel or directly at /terminal:

• Zero Inbound Ports: The monitor maintains an outbound WebSocket connection to the Shuffle server. You do not need to open inbound SSH ports or configure public IPs.
• Live Diagnostics: Run diagnostic commands (ps aux, df -h, network checks) directly from the web browser to investigate alerts.

Response actions

When response_actions is set to full, administrators can execute remote commands on the endpoint from the web terminal, predefined action chips, or automated workflows:

Predefined Actions

• Screenshot (screenshot): Captures the current display of the active user session.
• Isolate Host (isolate_host): Restricts network connectivity while keeping the management channel alive (requires root on Linux/macOS or SYSTEM on Windows).
• Unisolate Host (unisolate_host): Restores network connectivity (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.

The Host Monitors dashboard

The fleet interface at /monitors displays all registered hosts:

Dashboard Features

• Posture Tiles: Summary counts of hosts passing compliance checks (disk encryption and screenlock), total discovered software applications, active code package scanners, and hosts with response actions enabled.
• Platform Tabs & Search: Filter hosts by operating system (All, macOS, Windows, Linux) or search by hostname and IP address.
• Host Table:
  • Host: Hostname, platform, and IP address.
  • Operating System: OS distribution and kernel/build version.
  • Last Seen: Relative heartbeat timestamp with an online (green) or offline (gray) status dot.
  • Compliance Checks: Indicators for Hard Drive Encryption and Screenlock.
  • Installed Software: Count badge of cataloged applications.
  • Code Scanner: Status of project dependency scanning.
  • Actions: Open the Web Terminal or trigger host actions.
• Host Detail Drawer (HostDetailPanel): Clicking any host opens a panel showing hardware specifications (CPU, RAM, MAC address), compliance breakdown, software list, scanned project dependencies, and action triggers.

API & Datastore reference

Host monitor records, heartbeats, and compliance data are stored in Shuffle Core's Datastore under the shuffle-security_sensors category (and hardware asset specifications in shuffle-security_assets).

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

  CopyTest

  curl -X POST 'https://<instance>/api/v1/apps/sensors/run' \
    -H 'Authorization: Bearer $SHUFFLE…' \
    -H 'Content-Type: application/json' \
    -d '{
    "app_id": "sensors",
    "app_name": "sensors",
    "name": "run_action",
    "parameters": [
      {
        "name": "action",
        "value": "uname -a"
      },
      {
        "name": "hosts",
        "value": "<HOSTNAME>"
      },
      {
        "name": "sensor_group",
        "value": "<SENSOR_GROUP>"
      }
    ]
  }'

  Response

  Close

  No response received.

• Query Host from Datastore Directly:

  API Call

  POST

  cURL

  Python

  HTTP

  JSON

  CopyTest

  curl -X POST 'https://<instance>/api/v1/orgs/<org_id>/get_cache' \
    -H 'Authorization: Bearer $SHUFFLE…' \
    -H 'Content-Type: application/json' \
    -d '{
    "category": "shuffle-security_sensors",
    "key": "<HOST_ID>",
    "org_id": "<ORG_ID>"
  }'

  Response

  Close

  No response received.

In Custom Python Apps & Workflows

# Retrieve host telemetry directly from the datastore
host = self.get_cache("host_id_123", category="shuffle-security_sensors")

# Check compliance state
if host:
    compliance = host.get("compliance", {})
    if not compliance.get("hd_encrypted"):
        print(f"Warning: Host {host.get('hostname')} does not have disk encryption enabled")

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