Installing ServiceNow Agent Client Connector for macOS

Hello Phil,

I have done this, I just installed the pkg and then ran a script to write the launch agent and config

#!/bin/zsh

# Where the SNow Agent config needs to be
SNowAgentDir="/Library/Application Support/servicenow/agent-client-collector"
SNowAgentConfig="$SNowAgentDir/acc.yml"
SNowAgentAllowList="$SNowAgentDir/check-allow-list.json"
mkdir "${SNowAgentDir}"

echo "Creating ${SNowAgentConfig}."
(
cat <:/ws/events
# in case the MID Web server is configured to use Secure connection, use the following format: wss://:/ws/events
backend-url:
 - "wss://CHANGEME:443/ws/events"

# Single authentication configuration for all backend-URLs:
# Specify the user name as defined on the MID web server.
#user: "admin"
# Specify the password as defined on the MID web server.
#password: "admin"
# Specify the API key used by the MID to authenticate incoming Agent connections
api-key: "encrypted:CHANGEME"

##
# Agent log file
##
# macOS   location   : /var/log/servicenow/agent-client-collector/acc.log	
# Linux   location   : /var/log/servicenow/agent-client-collector/acc.log
# Windows location   : C:\\ProgramData\\ServiceNow\\agent-client-collector\\log\\acc.log

# Allowed log-level values: panic, fatal, error, warn, info, debug
log-level: "info"

##
# security configuration
# in case the MID Web server is configured to use secure connection, refer to the following attributes:
# Setting to false (which is not the default value) will force certificate verification on the backend-client connection
skip-tls-verify: true
# Specify location of the SSL certificate file
#trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"

# Path to json file that contains the allow list of check or hook commands the agent can execute
allow-list: /Library/Application\\ Support/ServiceNow/agent-client-collector/check-allow-list.json

# Redact the following parameters when the agent logs or sends keepalives
#redact:
#  - username
# -  bearer_token
# -  auth_algorithm
# -  access_key
# -  enrollment_number
# -  auth_method
# -  client_id
# -  ea_credential
# -  certificate
# -  cert_alias
# -  secret_key
# -  password
# -  passwd
# -  pass
# -  api_key
# -  api_token
# -  private_key
# -  secret
# -  ssh_private_key
# -  ssh_passphrase
# -  authentication_key
# -  authentication_protocol
# -  privacy_key
# -  privacy_protocol

# Specify location of the SSL certificate file
#trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"

# Specify if plugins should be verified, Default = true.
#verify-plugin-signature: true

# Specify the maximum number of checks that can run in parallel.
max-running-checks: 10

# Defines the threshold for agent CPU usage. If threshold is exceeded, data collection will be turned off.
agent_cpu_threshold:
  cpu_percentage_limit: 5 # CPU percentage limit. Default = 5.
  repeated_high_cpu_num: 3 # Number of consecutive times the CPU percentage limit must be exceeded. Default = 3.
  monitor_interval_sec: 60 # Indicates that the monitor will run every X seconds. Default = 60.
  agent_cpu_threshold_disabled: false # Indicates whether gathering CPU threshold values for the agent protection feature is disabled.
  proxy_cpu_percentage_limit: 80 # CPU percentage limit when agent is running proxy check(s). Default = 80

disable-sockets: true
statsd-disable: true

enable-auto-mid-selection: true # Enables or disables the Auto MID Selection feature. Disabling this feature means manual input of MID servers URLs using this file backend-url attribute.

# Specifies whether executables in the system PATH or ACC plugin executables have preference.  Default is plugin executables (value: false).
#check-commands-prefer-installed: false
agent-key-id: CHANGEME
ENDOFSNOWAGENTCONFIG
)  > "${SNowAgentConfig}"

echo "Creating ${SNowAgentAllowList}."
(
cat < 500\\"",
      "\\"select pid, name, uid, resident_size from processes order by resident_size desc limit 10\\"",
      "\\"select * from system_info\\"",
      "\\"select * from certificates\\"",
      "\\"select path, type, round((blocks_available * blocks_size *10e-10),2) as gigs_free from mounts where path='/'\\"",
      "\\"select * from chrome_extensions\\"",
      "\\"select name from kernel_info\\""
    ],
    "exec":"osqueryi",
    "skip_arguments":false
  },
  {
    "args":[
      ""
    ],
    "exec":"read-file.rb",
    "skip_arguments":true
  },
  {
    "args":[
      ""
    ],
    "exec":"rebootcount.sh",
    "skip_arguments":false
  },
  {
    "args":[
      "agent"
    ],
    "exec":"Restart",
    "skip_arguments":false
  },
  {
    "args":[
      ""
    ],
    "exec":"winchecks",
    "skip_arguments":true
  },
  {
    "args":[
      "self-test",
      "self-test debug",
      "self-test verbose"
    ],
    "exec":"acc",
    "skip_arguments":false
  }
]
ENDOFSNOWAGENTALLOWLIST
)  > "${SNowAgentAllowList}"

chown -R _servicenow:_servicenow "${SNowAgentDir}"

 I'm by no means saying this is the best or only way to do it, but it worked for us. Search for the CHANGEME's to personalise it.

#!/bin/zsh

# Where the SNow Agent config needs to be
SNowAgentDir="/Library/Application Support/servicenow/agent-client-collector"
SNowAgentConfig="$SNowAgentDir/acc.yml"
SNowAgentAllowList="$SNowAgentDir/check-allow-list.json"
mkdir "${SNowAgentDir}"

echo "Creating ${SNowAgentConfig}."
(
cat <:/ws/events
# in case the MID Web server is configured to use Secure connection, use the following format: wss://:/ws/events
backend-url:
 - "wss://CHANGEME:443/ws/events"

# Single authentication configuration for all backend-URLs:
# Specify the user name as defined on the MID web server.
#user: "admin"
# Specify the password as defined on the MID web server.
#password: "admin"
# Specify the API key used by the MID to authenticate incoming Agent connections
api-key: "encrypted:CHANGEME"

##
# Agent log file
##
# macOS   location   : /var/log/servicenow/agent-client-collector/acc.log	
# Linux   location   : /var/log/servicenow/agent-client-collector/acc.log
# Windows location   : C:\\ProgramData\\ServiceNow\\agent-client-collector\\log\\acc.log

# Allowed log-level values: panic, fatal, error, warn, info, debug
log-level: "info"

##
# security configuration
# in case the MID Web server is configured to use secure connection, refer to the following attributes:
# Setting to false (which is not the default value) will force certificate verification on the backend-client connection
skip-tls-verify: true
# Specify location of the SSL certificate file
#trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"

# Path to json file that contains the allow list of check or hook commands the agent can execute
allow-list: /Library/Application\\ Support/ServiceNow/agent-client-collector/check-allow-list.json

# Redact the following parameters when the agent logs or sends keepalives
#redact:
#  - username
# -  bearer_token
# -  auth_algorithm
# -  access_key
# -  enrollment_number
# -  auth_method
# -  client_id
# -  ea_credential
# -  certificate
# -  cert_alias
# -  secret_key
# -  password
# -  passwd
# -  pass
# -  api_key
# -  api_token
# -  private_key
# -  secret
# -  ssh_private_key
# -  ssh_passphrase
# -  authentication_key
# -  authentication_protocol
# -  privacy_key
# -  privacy_protocol

# Specify location of the SSL certificate file
#trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"

# Specify if plugins should be verified, Default = true.
#verify-plugin-signature: true

# Specify the maximum number of checks that can run in parallel.
max-running-checks: 10

# Defines the threshold for agent CPU usage. If threshold is exceeded, data collection will be turned off.
agent_cpu_threshold:
  cpu_percentage_limit: 5 # CPU percentage limit. Default = 5.
  repeated_high_cpu_num: 3 # Number of consecutive times the CPU percentage limit must be exceeded. Default = 3.
  monitor_interval_sec: 60 # Indicates that the monitor will run every X seconds. Default = 60.
  agent_cpu_threshold_disabled: false # Indicates whether gathering CPU threshold values for the agent protection feature is disabled.
  proxy_cpu_percentage_limit: 80 # CPU percentage limit when agent is running proxy check(s). Default = 80

disable-sockets: true
statsd-disable: true

enable-auto-mid-selection: true # Enables or disables the Auto MID Selection feature. Disabling this feature means manual input of MID servers URLs using this file backend-url attribute.

# Specifies whether executables in the system PATH or ACC plugin executables have preference.  Default is plugin executables (value: false).
#check-commands-prefer-installed: false
agent-key-id: CHANGEME
ENDOFSNOWAGENTCONFIG
)  > "${SNowAgentConfig}"

echo "Creating ${SNowAgentAllowList}."
(
cat < 500\\"",
      "\\"select pid, name, uid, resident_size from processes order by resident_size desc limit 10\\"",
      "\\"select * from system_info\\"",
      "\\"select * from certificates\\"",
      "\\"select path, type, round((blocks_available * blocks_size *10e-10),2) as gigs_free from mounts where path='/'\\"",
      "\\"select * from chrome_extensions\\"",
      "\\"select name from kernel_info\\""
    ],
    "exec":"osqueryi",
    "skip_arguments":false
  },
  {
    "args":[
      ""
    ],
    "exec":"read-file.rb",
    "skip_arguments":true
  },
  {
    "args":[
      ""
    ],
    "exec":"rebootcount.sh",
    "skip_arguments":false
  },
  {
    "args":[
      "agent"
    ],
    "exec":"Restart",
    "skip_arguments":false
  },
  {
    "args":[
      ""
    ],
    "exec":"winchecks",
    "skip_arguments":true
  },
  {
    "args":[
      "self-test",
      "self-test debug",
      "self-test verbose"
    ],
    "exec":"acc",
    "skip_arguments":false
  }
]
ENDOFSNOWAGENTALLOWLIST
)  > "${SNowAgentAllowList}"

chown -R _servicenow:_servicenow "${SNowAgentDir}"

Thank You @charliwest.. I'll take a look.

Heres a rundown of my solution to my question above.  Maybe it will be helpful to someone else in the future.

Someone did ask why we’re chasing this path rather than using the Service Now provided Jamf integration. In fact, we are using it to connect Jamf to the Service Now CMDB.  The problem has been that it is notoriously unreliable, constantly dropping the connection and not properly syncing data.  Our Service Now admins and developers have been working for months with Service Now Support to troubleshoot and have not had any success.  That issue has been escalated to Service Now engineering support, but there is little expectation at this point of a quick resolution.

Ok, on to the show…

In a nutshell, using Composer I created a new custom package containing config file edits and necessary fixes.  With that plus the package(s) provided by Service Now I have a functioning Service Now Agent Client Collector install.

I ran into several issues along the way, most of which, in my mind, were completely avoidable, but this is how Service Now has built these installers.

SN (aka Service Now) offers two install methods for installing ACC ( aka Agent Client Collector);

Option 1 is a “simple” one line command using curl, with some flags built in to capture needed configuration information.  I assume this command downloads and installs the app and edits the necessary configuration file(s).

Enter complaint #1; I say assume because I never got this method to work.  Every test on multiple machines and multiple OS’es results in failure due to System Integrity Protection  Something in the install script that is run is flagging SIP which prevents the “simple” commands from running successfully.

• FWIW, from a cursory look at the install script that is run this simple command includes what appears to be a lot of code carried over from the *nix version of the installer.  It almost appears that the original *nix script was modified to run on different kernels, including macOS, and making necessary adjustments to path variables and such.

Option 2 is a typical macOS package based install, using either an x86 or ARM64 pkg.  (Complaint #2).  At least these install correctly.

With this method ACC requires editing 1 or 2 config files, one for secure communications to the SN server, and another that configures what inventory and control tasks are allowed to run on the endpoint.

In order to configure, you must first duplicate the example files, then edit, then set the correct permissions. A bit of pain, but not especially difficult.  I can’t help but think there is a better way though.

Testing note- SN ACC includes a built-in self-test function that was very helpful in identifying the following issues;

(Complaint #3) During testing and troubleshooting, I found that the ACC installer failed to create one specific folder, and failed to correctly set permissions on several files and folders.

(Final complaint) Annoyingly, the ACC also requires editing sudoers to allow the _servicenow user account created during install to actually run some of the commands used to collect inventory data.

Using Composer I created a new customer PKG of the required files with edits, missing folders, etc. Again, I couldn’t help but think there must be a better way to handle this.

Hope this helps someone.

@pbenware1  I tried the second method by editing the configuration file but still we don't see the agent reflected in the console. 

@Bharath05 We too had other issues that required some extra work at the Service Now mid server.  This dives more into the Service Now side of things than Jamf.  These are all things you Service Now Admin should have some understanding of.

1- The mid server we were initially testing on was behind a firewall and using a non-routable IP address.  For devices outside the network we had to configure a new mid server in the DMZ with a public facing IP address.

2- The host VM had to have the local built-in firewall rules adjusted to allow for the TCP port that Agent Client collector was using.

3- The SN Admin made some changes to how ACC handled the inbound data.  We could see that the agent was connecting, but was not collecting data.  Something the admin did corrected that (I have no idea what they did).

The service now the agent has released the 3.5.5 framework which seamlessly works with single-line commands on ARM and Intel.

need to uninstall the agent and clean install with the command line.

I had to recreate the YAML file into a bash script and add it to the pkg.