AlienVault® USM Anywhere™

AlienVault Agent Installation on macOS Hosts

Role Availability Read-Only Analyst Manager

To install the AlienVault Agent, you must run a script accessible from your USM Anywhere environment. When you run the installation on an Apple macOS host system, the script downloads a .pkg file directly from USM Anywhere and the agent automatically registers with your USM Anywhere environment. The installation process also configures a default set of paths to automatically support File Integrity Monitoring.

You can generate a script that is specific to a selected assetAn IP-addressable host, including but not limited to network devices, virtual servers, and physical servers. and your USM Anywhere environment, or generate a bulk deployment script that you can use to install the agent on multiple macOS host systems.

Prerequisites

Before you install the AlienVault Agent on a macOS host system, make sure that

  • You are running macOS Sierra 10.12 or later.
  • Your macOS has a minimum of 4 GB memory and 2 CPU cores.
  • You have login credentials for the host system with sudoA program for UNIX-like computer operating systems that allows users to run programs with the security privileges of another user, by default the superuser. privileges.
  • Your firewall is configured to allow ongoing outbound connectivity from the host system using the HTTPS application protocol over port 443 to these USM Anywhere endpoints:

    prod-api.agent.alienvault.cloud

    api.agent.alienvault.cloud

    <AWS region>-agent-entrypoint.alienvault.cloud

  • For endpoints that rely on the Amazon Web Services (AWS) region, the endpoint to use depends on the AWS region where your USM Anywhere instance is deployed. See the table below for details. If you are unsure, consult your administrator who set up your USM Anywhere domain.

    Note: AT&T Cybersecurity does not own the IP addresses of these endpoints. While relatively stable, they are subject to change by AWS.

    AlienVault Agent Endpoints by AWS Regions
    Region Endpoint
    Asia Pacific (Tokyo)

    ap-northeast-1-agent-entrypoint.alienvault.cloud

    Asia Pacific (Mumbai)

    ap-south-1-agent-entrypoint.alienvault.cloud

    Asia Pacific (Sydney)

    ap-southeast-2-agent-entrypoint.alienvault.cloud

    Canada (Central)

    ca-central-1-agent-entrypoint.alienvault.cloud

    EU (Frankfurt)

    eu-central-1-agent-entrypoint.alienvault.cloud

    EU (Ireland)

    eu-west-1-agent-entrypoint.alienvault.cloud

    EU (London)

    eu-west-2-agent-entrypoint.alienvault.cloud

    South America (São Paulo)

    sa-east-1-agent-entrypoint.alienvault.cloud

    US East (N. Virginia)

    us-east-1-agent-entrypoint.alienvault.cloud

    US West (Oregon)

    us-west-2-agent-entrypoint.alienvault.cloud

AlienVault Agent Installation on a Single Host System

For a macOS host system that is already identified as an asset in your USM Anywhere environment, you can install the AlienVault Agent using a generated Terminal script to run on that macOS host system. You can generate this script for the specific asset from the Agents page or from the Asset Details page for the asset.

Note: If a single host system is not in your Asset inventory through discovery by a deployed USM Anywhere Sensor, you can manually add the asset using its IP address or fully qualified domain name (FQDN). See Adding Assets for more information.

Alternatively, you can use a script for multiple assets and then use the information provided by the unassociated agent to create a new asset.

Important: Some antivirus software may block the osqueryd service and prevent it from starting. If your service is not starting because of antivirus software, you need to add the /usr/local/bin/ path to your antivirus exclusions policy.

AlienVault Agent Installation on Multiple Host Systems

If you have multiple macOS host systems that are not currently in your USM Anywhere asset inventory or you don't want to generate a separate script for each asset, you can install the AlienVault Agent using a generated Terminal script on any macOS host system that meets the prerequisite requirements and supports the package type for the script. You can generate this script from the Agents page.

Note: If you use a multiple asset installation script to execute bulk deployment across multiple host systems, the script does not have the unique asset ID. In this case, USM Anywhere attempts to associate the AlienVault Agent with an existing asset if there is enough information and it can make a definitive match. After a successful deployment of the agent on a host, it sends only heartbeat events until it is has an asset association. These heartbeat events include basic information about the host system, including network interfaces and IP address, as well as the asset UUID.

When a deployed agent does not have an associated asset, you must make this association in USM Anywhere in order to enable queries and log collection for the host system. For more information, see Agent and Asset Associations.

You can generate this script from the Agents page. After you use the script to deploy the agent on your macOS host systems, you can view the list of unassigned agents and then associate each agent with an existing asset or add a new asset using the information provided by the agent.

To generate an agent deployment script for multiple host systems

  1. In USM Anywhere, go to Data Sources > Agents.
  2. Click macOS Deployment Script.

    In the dialog box, the Multiple Assets tab is selected by default.

  3. Select the Package Manager type for the macOS distribution.

  4. Click Copy to clipboard.

    Click Copy to clipboard to copy the generated bash script

    Use a remote access client to connect and log into the macOS host system.
  5. Open the Terminal and enter a sudo command containing the script you copied to the clipboard.

Additional AlienVault Agent Commands

The AlienVault Agent also comes with a bash script to control other features of the agent, such as starting, stopping, restarting, updating, and uninstalling the agent. See the The Agent Command Script documentation page for more information of the agent command script, including the file location and a list of the commands.

Installation Error Resolution

After the AlienVault Agent is installed, the Asset UID associations are stored in the osquery.flags file in your system. Asset changes, specifically changes that result in an asset being removed and added back to USM Anywhere, can cause issues with the way an agent associates with those assets in the future if you need to reinstall the agent for any reason.

If you encounter an error during installation of an agent, you need to remove the osquerydirectory before you reinstall the agent. To do this, delete the /var/osquery folder.