Manually Installing the macOS Managed Agent (AD Enterprise 7.3+)

Introduction

This document outlines the procedure of installing the Managed Agent on macOS for AD Enterprise 7.3 and later.

 

Prerequisite

• Remove Full Disk Access for any previous versions of the MacOS Agent.
• Uninstall any previous versions of the MacOS Agent.
• Make sure the "QuincServerUrl" key in the "Qview.exe.config" file (typically in "C:\Program Files\AccessData\Forensic Tools\<version>\bin\QView\") on the Enterprise machine is correct. Meaning using the correct protocol, correct name and correct port.

• Make sure the "QuincServerUrl" key in the "JobsMonitor.exe.config" file (typically in "C:\Program Files\AccessData\Forensic Tools\<version>\bin\QView\") on the Enterprise machine is correct.
  

 

Procedure

Install the Agent:

1. Copy the macOS Managed Agent installer PKG, found at "\Forensic_Tools\Agents\MAC\AccessDataAgent-macos-installer-x64-<version>.pkg" on the Forensic Tools ISO/disc, to the Mac system.
2. Once copied check the hash value to confirm it matches that of the hash value for the file on the ISO image.
3. Double-click the PKG file and follow the prompts to install the Managed Agent

 

Grant the Agent Full Disk Access:

1. On the macOS machine, go to System Preferences > Security & Privacy
2. Select the Privacy tab
3. Select Full Disk Access on the left, click the lock  icon in the lower-left corner, then enter administrator credentials when prompted
4. Under the list of items with access, click the + button
   
5. Select Applications on the left, then Utilities, select the Console app, and click Open
6. Repeat steps 4 and 5, but select the Terminal app
   
7. Leaving the Security & Privacy dialog open, open Finder and navigate to "/Library/AccessDataAgent/<version>"
8. Select & drag both ADG.Agent.IndexingService and ADG.ManagedAgentSvc from the Finder window to the open application list in the Security & Privacy window
   Note: You must browse to these files via Finder, as the Security & Privacy dialog won't let you add them directly.
9. Confirm that the following items are listed and checked, then close the Security & Privacy dialog:
   ADG.Agent.IndexingService
   ADG.ManagedAgentSvc
   sh
   Console
   Terminal

 

Configure Agent Indexing:

1. On the macOS machine, open a Terminal window and run the following command to stop the Agent:
   

   sudo launchctl unload /Library/LaunchDaemons/com.adg.managedagent.plist

2. Open "/usr/local/share/AccessData/ManagedAgent/AgentData/agentsetting.json" in a text editor.
3. Reference the Agent Settings Reference Table in the Installing the Mac Agent chapter of the Enterprise User Guide to make any desired changes to the Agent's indexing settings.
4. Save and close the modified agentsettings.json.
5. Open a Terminal window and run the following command to start the Agent:
   

   sudo launchctl load /Library/LaunchDaemons/com.adg.managedagent.plist

6.  Wait up to 24 hours for the index to build.

 

Check if the Agent is online and accessible:

From the Enterprise machine, go to https://<AgentIP>:3999/api/hostname in a browser.  If the page returns a JSON string with the Agent's hostname, you should be good to go.  If you aren't able to access that page, there may be a firewall blocking communication between the Agent and Examiner.

 

Add the Target to the Agent List:

1. On the main screen in Enterprise, go to Tools > Preferences.
2. Click Agent List.
   
3. In the bottom-right, click Add...
   
4. Do the following, then click OK:
   1. Enter a Friendly Name.
   2. Enter a Description (optional).
   3. Under Node/Range, select IP and enter the target's IP address.
   4. Check the is Mac box.
      

 

Notes

• The macOS Agent with Forensic Tools 7.3.0 listens on port 4999 by default.  The macOS Agent with Forensic Tools 7.4.0 and newer listens on port 3999 by default.  Follow this article to make sure your Agents and Enterprise are both set to use the same port.
• Without granting full disk access to the necessary apps on the target, Enterprise may not be able to list and/or collect all desired items.
• Refer to the chapter on "Installing the Mac Agent" in the Enterprise User Guide for additional notes on optional Agent configurations that can be applied after installation.
• If a target isn't added to the Agent List, it will not be available for selection during a collection job.