Configuration options for the macOS USS agent - Console
Updated 3 hours ago
by
admin
- Settings
- Identification
- Bypass Categories
- Agent Anti-Malware
- Network Detection
- Advanced
The Agent Configuration page lets you create or modify agent profiles for macOS agents.
In the console, go to Browse ⟶ Agent Configuration and open the Mac tab. Click the settings (cog) icon next to a profile to open it. The profile editor has a menu on the left for each section described below. When you have made your changes, click Apply Changes at the top right.
Settings
Profile Name
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 Type
The agent can intercept requests in one of 3 operating modes.
Mode | Behaviour |
HTTP (recommended) | Agent will operate as a HTTP proxy and Network Settings will be automatically set. This gives the best compatibility with browsers and modern applications. |
SOCKS | Agent will operate as a SOCKS 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 |
Tag Web Requests With
The Tag to assign to this agent. Tags are used to identify the agent in the Rule Builder. Select a tag to use, or choose None if a tag is not required. Tags are managed in Browse ⟶ Module Settings ⟶ Tags.
Preferred Outbound Ports
The agent will connect to the Browse 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 Browse service ports are inaccessible. If not enabled, web access will be blocked until the cloud service becomes available again.
Check for Updates Automatically
If enabled, the agent will poll for new software updates.
Install Updates When Available
If enabled, the agent will install new software updates as soon as they are available.
Allow Restart Without Password
If enabled, the agent can be started without a password as long as it was previously stopped using the password.
Enable Popup Notifications
If enabled, the agent will attempt to display a notification when a download is blocked.
Identification
The Identification section lets you 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.
Username Capture Type
The type of username to attempt to capture.
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 |
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 |
FQDN | For use when the agent is part of an Azure Active Directory environment. The active user will be captured in the format If the user is not part of a domain, the |
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 Browse ⟶ Categories ⟶ Bypass. Tick the categories to apply to this profile. You can manage the patterns in a category by clicking its sliders icon. Bypass categories provide a way for the agents to trust particular network resources, so that matching traffic does not get filtered by the Browse service. A number of pre-defined categories are provided as a starting point for common services.
Agent Anti-Malware
cdn.bitdefender.net
Scanning Engine
Select the preferred Scanning Engine to use. Selecting none will disable anti-malware scanning.
Block Page Template
Select the block page template to show if malware is detected. Templates are managed in Browse ⟶ Module Settings ⟶ Templates.
Ignore Media Content
Check this box to ignore content that cannot be scanned such as streaming video and audio.
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.
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.
Tick Enable Network Detection to turn the feature on.
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.
Detection Hostnames
Click Add Entry to add a hostname and its expected CIDR. 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.
Agent State on Detection
Choose what should happen to the macOS agent if a recognised network is detected (either disable or enable the agent).
Do Not Disable If
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). Choose the detection method from the drop-down (the default is Always disable) and add the IP address exceptions.
Advanced
The Advanced section is split into Security, Update, Proxy and Service Information groups.
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
Allow Unknown Content Encoding
Allows content with an unrecognised encoding to pass through the agent. Use with caution, as it may affect security inspection.
Clear Proxy Configuration
Forces removal of any proxy redirections set by the agent when it is stopped or unloaded.
Update Repository
Select the preferred repository for software updates: Stable, Pre-Release, Beta or Custom URL.
Check for Updates Every
Specify how often, in minutes, to check for new software updates.
Agent Service Inspection List
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.
Agent Service Port
The port that the agent service uses to receive web requests after they have been intercepted.
Maximum Scan Size
The maximum file size that will be scanned for malware.
Service Hostname
Shown under Service Information. The service hostname is determined by the region chosen for the Browse service, and cannot be changed directly.
Profile ID
Shown under Service Information. 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 lets 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.
When no certificate is configured, the section shows Using the default agent certificate.
The following options are available:
- Upload Certificate - paste your own PEM-encoded certificate and private key, then click Verify. All agents using this profile will use it.
- Generate Self-Signed - generate a new self-signed certificate that all agents using this profile will use
Once a certificate is configured, the section shows its details (subject, issuer and validity dates) and the current certificate, with these extra options:
- Copy - copy the public key to the clipboard for ease of transferring to the local key store or MDM software
- Download .pem - download the public key for ease of transferring to the local key store or MDM software. See How to deploy the SSL Certificate to a macOS device.
- 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.