huntress_install_macos.sh - limehawk/rmm-scripts GitHub Wiki

huntress_install_macos.sh

Installs the Huntress security agent on macOS systems with RMM integration.

Overview

This is the official Huntress deployment script for macOS systems, designed for use with RMM platforms. It downloads and installs the Huntress agent with proper organization and account key association. The script includes comprehensive error handling, validation, and logging capabilities.

Purpose

Automates the deployment of the Huntress macOS agent through RMM platforms. The script validates credentials, downloads the official installer from Huntress, and executes the installation with appropriate organization affiliation. It supports both command-line parameters and hardcoded default values for flexibility in deployment scenarios.

Prerequisites

  • macOS system
  • Root/sudo privileges
  • Internet connectivity to reach huntress.io
  • Valid Huntress account key
  • Organization key for agent affiliation

Configuration

Required Inputs

  • accountKey (or defaultAccountKey) - Your Huntress account secret key

    • 32-character hexadecimal string
    • Obtained from Huntress portal's "download agent" section
    • Can be passed via --account_key parameter or set as $defaultAccountKey

  • organizationKey (or defaultOrgKey) - Organization identifier

    • User-specified name or description
    • Used to affiliate agent with specific organization
    • Can be passed via --organization_key parameter or set as $defaultOrgKey

Settings

  • rmm - Name of RMM platform (default: "Superops.ai")

    • Helps Huntress support team track deployment methods

  • install_system_extension - Install system extension after agent installation

    • Default: false
    • Requires MDM configuration to avoid security prompts
    • See Huntress KB for MDM setup instructions

Behavior

  1. Validates root privileges
  2. Processes command-line arguments (--account_key, --organization_key)
  3. Falls back to default values if parameters not provided
  4. Validates account key format (32-character hex pattern)
  5. Masks account key in logs for security (shows first 4 and last 4 characters)
  6. Downloads official installer script from huntress.io
  7. Validates account key with Huntress servers
  8. Executes installation with provided credentials
  9. Optionally installs system extension (if enabled)
  10. Logs all operations to /tmp/HuntressInstaller.log

Security Notes

  • Account keys are partially masked in logs (shows XXXX************************XXXX)
  • Downloads installer only from official Huntress domain (huntress.io)
  • Validates account key before proceeding with installation
  • All operations logged to /tmp/HuntressInstaller.log
  • Requires root privileges for system-level agent installation

Exit Codes

  • 0: Success - Huntress agent installed successfully
  • 1: Failure - Invalid credentials, download failure, or installation error
  • 2: Failure - Invalid command-line options

Example Output

=========== INSTALL START AT 20250101-123000 ===============
=========== Superops.ai Deployment Script | Version: 1.0 ===============
--organization_key parameter present, set to: MyOrganization
Provided Huntress key: 1234************************abcd
Provided Organization Key: MyOrganization
=============== Begin Installer Logs ===============
Installing Huntress Agent...
=========== INSTALL FINISHED AT 20250101-123045 ===============

Version History

  • 1.0 - Official Huntress deployment script for macOS with RMM integration

Links