Skip to main content

Installing The Mac Cerulean Agent

Updated

A step-by-step guide to installing and managing the Cerulean Agent on your Mac operating systems.

Overview

The Cerulean Agent provides automated data collection and configuration services for your end points and lays the framework for AgileBlue's autonomous response capabilities. The Cerulean Agent includes several enhancements and remote support capabilities not included in previous AgileBlue Management Agent versions.

Relevant Agent Versions

This guide covers the installation process for the Cerulean Agent, starting with version 2304.3.2.

For questions regarding installation of previous AgileBlue Agent versions, click here.

Supported Operating Systems

The Cerulean Agent supports the following Mac operating systems:

  • Mac OS 11 64bit and newer

Minimum System Requirements

The agent is specially designed to use minimal system resources; the requirements for the agent are simply that of the operating system installed. Special consideration should be made on virtual machine infrastructure such that the actual allocation of resources meets the operating system / user load requirements. Specifically, shared computing environments such as VDI desktops or Terminal Server / Services should have adequate resources to handle the user load. (E.g. enough physical resources that each user has sufficient resources allocated to their session.) AgileBlue cannot guarantee the complete functionality of the agent if resources do not meet recommended levels.

Networking Requirements

The Cerulean Agent, and its associated data collection services, securely sends data over the internet to the AgileBlue Cloud. To allow this, the following ports should be configured for outbound traffic on all devices and environment firewalls, routers, etc.

  • TCP Outbound Port 443
  • TCP Outbound Port 9243

Additionally, the Cerulean Agent will install the Elastic Agent, which requires the following TCP ports to be available:

  • 6791/HTTP
    • This port is leveraged for performance monitoring of the Elastic Agent
  • 6789/GCRP
    • Used for management of the Elastic Agent

Any endpoint receiving the Cerulean Agent must also be able to reach the following domains for full functionality:

  • agentapi.agileblue.com
  • data.agileblue.com
  • response.agileblue.com
  • artifacts.security.elastic.co

Anti-Virus Configuration

The Cerulean Agent performs administrative actions on your devices that some anti-virus systems may identify as malicious. To prevent anti-virus systems from quarantining or otherwise impeding the agent from performing its responsibilities, please be sure to whitelist the related files and services.

  • /usr/local/cerulean/*
  • /Library/Elastic/*

Download the Installer

When downloading the Cerulean Agent installer, you will receive a ZIP file containing two files: mac_installer3 OR mac_arm_installer3 AND config.json. Both items will important for the installation process.

  1. Open a web browser and navigate to the AgileBlue Portal
  2. Select Agent from the management section of the navigation menu

    Screenshot 2024-03-11 at 1.29.58 PM-1
  3. Click on the Mac Agent Installer (for Intel processors – most Macs older than 2021) or Mac ARM Agent Installer (for ARM processors, all Macs 2021 and newer) tile, depending on the processor your machine is running:

    mac-arm
     
  4. Take note of the API Key provided on the corresponding pop-up

    MAC-Popup

Grant Executable Privileges

Before installing the agent, you'll need to convert the installer downloaded in the previous section into an executable.

  1. Extract the required files from the .zip downloaded in the previous section
  2. Navigate to the directory containing the files via Terminal and run the command corresponding to the installer version downloaded in the previous step:
chmod +x mac_installer3
chmod +x mac_arm_installer3

Install the Agent

The Cerulean Agent can be installed locally on your Mac device via Terminal or deployed via your RMM. This section covers local installations.

  1. In the Terminal window, navigate to the directory containing your installer
  2. If the config.json file is in the same directory, run the command corresponding to the installer you've selected based on your machine's processor
    1. sudo ./mac_installer3 install
    2. sudo ./mac_arm_installer3 install
  3. Alternatively, if you do not store the config file in the same directory, you can run the full install command below (corresponding to your installer name)
  1.  
    1. sudo ./mac_installer3 install -a YOURAPIKEYHERE -u https://agentapi.agileblue.com
    2. sudo ./mac_arm_installer3 install -a YOURAPIKEYHERE -u https://agentapi.agileblue.com

Grant Full Disk Access & Allow System Extensions

In order for all portions of the agent to function, Mac devices require additional settings to be configured.

Note: If you are running a macOS older than Ventura, the specific layout of your system settings may appear differently than described in this guide. All steps remain the same.

  1. After installing the agent, click Open System Settings when the popup below appears:

    system_extension_blocked_warning_ven
  2. Select Privacy & Security

    privacy_security_ven
     
  3. In the right-hand pane, scroll to Security and select Allow on the message "System software from application "ElasticEndpoint" was blocked from loading

    allow_system_extension_ven
  4. Once the system extension has been loaded, click Allow when you receive the message below

    allow_network_filter_ven
  5. From here, navigate back to Privacy & Security in System Settings and click on Full Disk Access

    select_fda_ven
     
  6. Toggle the allow switch to "on" for the following applications:
    1. co.elastic*
    2. ElasticEndpoint
    3. cerulean-agent

*If you are running macOS older than Ventura (Catalina through Monterey), this application will instead be named co.elastic.systemextension

Confirm Installation Success

There are a couple of different methods to confirm the installation of the agent. Once installed, the agent will check-into the AgileBlue Portal within 3-5 minutes. Most importantly, you will want to verify that the following services are present on the machine:

  • Cerulean Agent
  • Cerulean Updater
  • Elastic Agent
  • Elastic Endpoint
  • For PRO subscribers, Cerulean will also automatically install the Nodeware Agent for vulnerability scanning.

Manage Your Installation

In addition to the installation commands above, the Cerulean Agent has several helpful built-in options available to you as well. When operating with sudo privileges in Terminal, you can utilize the following commands and flags to achieve the listed actions. Additionally, you can add the command help to see these commands during the installation, uninstallation, or troubleshooting processes:

sudo ./mac_installer3 help
sudo ./mac_arm_installer3 help

Available General Commands:
 

  • help
    • Help about any command
  • install
    • Installs the Cerulean Agent onto the system
  • repair
    • Repair a Cerulean Agent installation
  • uninstall
    • Uninstalls the Cerulean Agent

Available Flags:

  • -h
    • help for windows_installer3.exe
  • -v
    • Verbose output
  • -i
    • Places agent into image mode, ment for Golden Image usage
  • -s
    • Places agent into syslog mode

Agent Deployment

If you are leveraging an RMM for deployment of the Cerulean Agent, utilize the following command corresponding to your machine's processor and the installer you selected:

sudo ./mac_installer3 install -a YOURAPIKEYHERE -u https://agentapi.agileblue.com
sudo ./mac_arm_installer3 install -a YOURAPIKEYHERE -u https://agentapi.agileblue.com

Questions? Contact AgileBlue Support. 

Email: support@agileblue.com 
Phone: (216) 606-9400🚨