Configuration options for the macOS agent type

The Agent Configuration screen allows you to create or modify agent profiles for macOS agents. Selecting a macOS agent profile from the list will allow you to configure the profile.

Changes made to an agent profile can take up to 15 minutes to propagate to active macOS agents. You can force a configuration update using the Update Config option within the agent software itself.

Settings

Profile name / Tray icon tooltip

A friendly name for the profile to make it easier to manage. The name is also displayed in the tooltip for the agent icon.

Agent Password

The tamper-proof password which secures the configuration and start/stop options on the agent. This password is automatically generated when the profile is created but can be changed.

Proxy Mode

The agent can intercept requests in one of 3 operating modes.

Mode

Behaviour

SOCKS Proxy

Agent will operate as a SOCKS proxy and Network Settings will be automatically set

HTTP Proxy

Agent will operate as a HTTP proxy and Network Settings will be automatically set

Auto-Detect

Agent will behave as a SOCKS or HTTP proxy for incoming requests. Administrator must enforce the Network Settings manually

When the mode is changed for an existing installed agent, you should ensure you update any Group Policy or MDM profile that enforces the proxy setting configuration on the network adaptor(s).

Tag web requests with

The Tag to assign to this agent. Tags are used to identify the agent in Filter Rules. Select a tag to use, or choose No Selection if a tag is not required.

Preferred outbound ports

The agent will connect to the Web Security cloud service on ports 1344 & 1345 or 80 & 443. Select the preferred ports here and they will be tried first. If a connection is not established, the agent will try the remaining ports.

Hot Spot mode (Fail Open)

If enabled, the agent will provide unfiltered access if for any reason the Web Security cloud service ports are inaccessible. If not enabled, web access will be blocked until the cloud service becomes available again.

Check for new updates automatically

If enabled, the agent will poll for new software updates.

Install new updates when they are available

If enabled, the agent will install new software updates as soon as they are available.

Agent can be restarted without password following manual Stop Service action

If enabled, the agent can be started without a password as long as it was previously stopped using the password.

Identification & Privacy

The Identification & Privacy section allows you to control what information to log about your users and their devices.

Log username

Enables the capture of Active Directory or local user credentials. This captures the Active Directory domain and username if the user has logged into a Windows domain, or falls back to capturing the local username if this is not possible.

Capture Type

The type of username to attempt to capture.

Requires macOS agent version 4.3.20 or higher

Type

Behaviour

SAMAccountname

For use when the agent is part of an on-premise network domain and the SAM Account name is available. The active user will be captured in the format DOMAIN\username

UPN

For use when the agent is part of an Azure Active Directory environment and is signed in to an Azure domain. The active user will be captured in the format user@domain.ext

FQDN

For use when the agent is part of an Azure Active Directory environment. The active user will be captured in the format CN=name,CN=Users,DC=domain,DC=ext

If the user is not part of a domain, the DC=domain,DC=ext will be replaced by DC=hostname

Use hostname as username

Use the device's hostname instead of the captured username. Useful for deployments where no user identification mechanism is provided, or for device-based policy control.

Log device MAC address

Enable capture of the device MAC address for the primary network interface.

Log device IP address

Enable capture of the device IP address for the primary network interface.

Bypass Categories

The Bypass Categories section contains a list of available categories, created in the Bypass section of the Web Security product. Bypass categories provide a way for the agents to trust particular network resources, so that matching traffic does not get filtered by the Web Security cloud service. A number of pre-defined categories are provided as a starting point for common services.

You can easily see which Bypass categories come from the default provision: default Bypass Categories all have the text (System) appended to their name.
Selecting a category will apply all the overrides in that category to all the agents to which this configuration profile is assigned.

Agent Anti-Malware

A valid license for the Agent Anti-Malware (Mac OS X) product is required to configure this feature. Contact your service provider for more information.
At least 1GB free space is required to download the additional anti-malware database. Please note that signature updates will be downloaded from cdn.bitdefender.net
Once enabled, malware scanning is applied to all connections made by the agent unless the request has been matched by a bypass pattern, in which case it may not be scanned, depending on the Bypass Type in use.

Scanning Engine

Select the preferred Scanning Engine to use. Selecting none will disable anti-malware scanning.

If you are planning to enable anti-malware in a configuration profile with a large number of agents attached, consider that each agent will need to download the ~600Mb database and by default, agents update on a 15 minute interval. If you are using a contended, restricted or expensive Internet connection then consider staggering the roll out or increasing the poll time by following this Knowledge Base article. Contact your service provider to discuss your deployment in more detail.

Use Block Template

Select a Web Security template to use if malware is detected.

Ignore Media Content

Check this box to ignore content that cannot be scanned such as streaming video and audio.

Maximum scan size (Mb)

The maximum file size that will be scanned for malware.

Decreasing this value can allow malware to pass through without filtering and increasing this value will increase the system memory and disk requirements.

Scan small files in memory

Checking this option will allow the agent to store files in memory that are less than 100Mb in size. Files greater than 100Mb will be written to disk before scanning.

Setting a Maximum scan size under 100Mb and enabling Scan small files in memory provides the best possible performance

Network Detection

The Network Detection feature provides added flexibility when using a combination of the gateway and agent software on the same network. Using Network Detection, you can automatically disable macOS agents when the agent detects a new connection to a recognised network.

For example, you might have a gateway agent deployed at your Head Office, along with a number of remote workers each running a Mac agent. If a remote worker visits Head Office with their Mac device, you could instruct that their filtering is handled by the gateway rather than the local Mac agent.

If the agent detects a "known" network, the system tray icon will turn orange and an alert will be displayed.

Hostname(s) to detect

Use the [IMAGE add button] to add a hostname. The macOS agent will then monitor for that hostname. If the Expected IP is set to 0.0.0.0/0 then the agent state will change as long as the hostname can be resolved to an IP. If you want to only change state if a specific IP is resolved (recommended), specify the IP in CIDR format.

For security reasons, you cannot use the local hosts file on the device to specify the Expected IP - it must be a hostname served by the network DNS server.

Agent State

Choose what should happen to the macOS agent if a recognised network is detected (either disable or enable the agent).

Do not disable if agent gateway IP matches

In certain scenarios you may not want to automatically disable the agent if the device default gateway matches a certain IP (for example, the IP of a VPN router). Check this box, and add the IP address exceptions to the list underneath.

Advanced

Seek advice from your service provider if you are unsure what effect changes to these options will have.

Use strict SSL/TLS ciphers

If enabled, the agent will reject connections to Web servers that are configured to use old, deprecated or insecure ciphers (such as rc4 and rc4-md5). This may cause third-party services to stop working. Generally, a web browser will always try and negotiate at the highest possible cipher level supported by the web server.

Block QUIC protocol

The QUIC protocol is developed by Google, and is used by many of their services, such as Google Search and GSuite (when accessed via the Google Chrome browser). As QUIC is a variation of HTTP/S over UDP, it can bypass filtering. Enabling this option ensures the protocol is blocked, and therefore the services fall back to using HTTP/S over TCP and can be filtered appropriately.

Intercept all running processes

The agent has the capability to intercept HTTP/S traffic from any running process, but by default this is limited to set of known browser-based applications (listed below). Enabling this option allows interception of any application, however it will be limited to the intercept ports 80 and 443.

Known browser-based applications intercepted by default
  • Safari
  • Chrome
  • Firefox
  • Opera
  • WebKit

Service hostname

The service hostname is determined by the region chosen for the Web Security service, and cannot be changed directly.

Update repository (URL)

Select the preferred repository for software updates

Check for updates every

Specify the frequency with which to check for new software updates.

Whitelist URL

This can be used to create a custom list of applications for the agent to intercept, and should be used with the Intercept all running processes option detailed above. A version of the json file should be hosted on a public web server and must follow the same format as the original.

Profile ID

An internal ID of the agent profile which may be requested by the Service Provider during a troubleshooting session. This ID cannot be changed.

TLS Certificate

The TLS Certificate section allows you to add your own certificate (Bring-Your-Own-Certificate) or generate a certificate that all macOS agents will use that share this configuration profile. This will replace the self-signed certificate that is unique to each agent (default behaviour).

With the introduction of Big Sur enhanced security, a software process is no longer able to install a certificate on the keychain without user consent*, unless it is installed using MDM software. This section allows you to use your own or generate and download a certificate for manual installation or use with MDM software.

This feature requires macOS agent v4.3.8 or above
Once an TLS Certificate has been configured, agents assigned to this configuration profile will no longer use the locally generated certificate and will require you to download and install the newly generated certificate either manually or via MDM software.

The following options are available:

  • Add Certificate - provide your own public and private key pair that all agents using this configuration will use
  • Generate Self-Signed - generate a new self-signed certificate that all agents using this configuration will use
  • Copy - copy the public key to the clipboard for ease of transferring to the local key store or MDM software
  • Download - download the public key for ease of transferring o the local key store or MDM software
  • Clear Certificate - remove the custom or self-signed certificate. The agent will revert to using its own self-signed certificate which will be different for all agents using this configuration profile

* applies to new installations of Big Sur. Upgrading to Big Sur from a previous OS X version does not enforce this restriction.

How did we do?