Deploy Firefox Collector

To deploy a browser collector, you must:

• Install the browser extension.
• Save AIDR collector configuration in the extension's Managed storage.

Managed storage

All deployment methods populate the browser extension's Managed storage with values required to connect to AIDR.

Firefox reads managed storage configuration from OS-level settings:

• macOS - Configuration profiles
• Windows - Registry entries

Configuration fields

• Required fields:

  • registrationIdentity - Encoded credentials the extension uses to authenticate with the AIDR service and obtain an authorization token
  • urlTemplate - AIDR API base URL

  You can find collector-specific values for registrationIdentity and urlTemplate on the Install tab in the AIDR console. Configuration files and templates available on the Install tab are pre-populated with these values.

• Optional user identity fields that appear in AIDR event logs:

  • userId - User identifier (for example, email address). Appears in AIDR logs and findings as a top-level field. If not provided, defaults to user_<device-id>.
  • userFullName - User's display name. Appears in AIDR logs and findings under Extra Info. If not provided, defaults to name_<device-id>.
  • hostname - Device hostname. Appears in AIDR logs and findings under Extra Info. Has no default value. If not configured, the field is sent empty.

System paths

• macOS - Managed preference plist files

  Configuration profile (JAMF deployment)

  plutil -p /Library/Managed\ Preferences/org.mozilla.firefox.plist
  Example configuration

  {
    "3rdparty" => {
      "Extensions" => {
        "pangea-aidr-extension@pangea.cloud" => {
          "registrationIdentity" => "eyJzIjp...YiOjF9"
          "urlTemplate" => "https://api.eu-1.crowdstrike.com/aidr/aiguard"
          "userFullName" => "<user-full-name>"
          "userId" => "<user-id>"
          "hostname" => "<hostname>"
        }
      }
    }
    "EnterprisePoliciesEnabled" => true
    "ExtensionSettings" => {
      "pangea-aidr-extension@pangea.cloud" => {
        "install_url" => "https://pangea.cloud/firefox-aidr-extension/aidr-extension-latest.xpi"
        "installation_mode" => "force_installed"
      }
    }
  }
  Managed Storage (Self-Service deployment)

  cat /Library/Application\ Support/Mozilla/ManagedStorage/pangea-aidr-extension@pangea.cloud.json
  Example configuration

  {
    "name": "pangea-aidr-extension@pangea.cloud",
    "description": "Managed storage for AIDR",
    "type": "storage",
    "data": {
      "urlTemplate": "https://api.crowdstrike.com/aidr/aiguard",
      "registrationIdentity": "eyJzIj...IjoxfQ==",
      "userId": "<user-id>",
      "userFullName": "<user-full-name>",
      "hostname": "<hostname>"
    }
  }

• Windows - Registry keys

  Registry keys (machine level)

  Get-ItemProperty "HKLM:\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud"
  Registry keys (user-specific)

  Get-ItemProperty "HKCU:\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud"
  Example configuration

  urlTemplate          : https://api.crowdstrike.com/aidr/aiguard
  registrationIdentity : eyJzIj...I6MX0=
  userId               : <user-id>
  userFullName         : <user-full-name>
  hostname             : <hostname>
  ...

Select Install option

On the collector details page, switch to the Install tab. This tab provides instructions, links, and templates for common deployment methods. This documentation includes step-by-step guides for specific methods.

• JAMF - Use Apple-native Configuration Profiles to enforce extension deployment and system-level settings on macOS.
• Microsoft Intune - Deploy extensions and configuration profiles across Windows and macOS managed endpoints.
• Group Policy (Windows only) - Use Active Directory Group Policy to force-install the extension and configure managed storage via registry settings across domain-joined Windows endpoints.
• Self-Service - Install the extension and apply a configuration profile on a single machine to quickly test the collector.

Group Policy (Windows)

With Active Directory Group Policy, you can force-install the browser extension on domain-joined Windows endpoints and configure its managed storage through registry entries.

Requirements

• Active Directory domain environment with Group Policy Management console (GPMC) installed.
• Permission to create, edit, and link Group Policy Objects (GPOs). For example, membership in Domain Admins or Group Policy Creator Owners.
• Target computer and user accounts in Organizational Units (OUs) linked to the GPO. Verify OU membership in Active Directory Users and Computers (dsa.msc).
• If you plan to force-install the extension through GPO, you need write access to the domain's SYSVOL share (\\<domain>\SYSVOL\) to install administrative templates and place startup scripts.

Create or edit Group Policy Object

1. Open Group Policy Management console (gpmc.msc).
2. Right-click your target OU and select Create a GPO in this domain, and Link it here..., or right-click an existing GPO and select Edit.... This opens Group Policy Management Editor.

Force-install extension

If the extension is already deployed through another method (such as Microsoft Intune), skip to

Configure computer-level registry settings.

Install administrative templates

The Mozilla Firefox administrative templates (ADMX/ADML files) aren't included with Windows. Check whether they're installed, and install them if needed.

1. In Group Policy Management Editor, go to Computer Configuration > Policies > Administrative Templates. If Mozilla > Firefox policy settings are already listed, skip to Enable force-install policy.

2. Download the latest policy templates archive from

   Policy templates for Firefox on GitHub. Look for the policy_templates_v<version>.zip asset.
   tip:

   For more info about Firefox enterprise management, see Customizing Firefox Using Group Policy (Windows) on Mozilla Support.

3. Extract the downloaded archive.

4. Inside the extracted folder, locate the windows/ subfolder. It contains mozilla.admx and firefox.admx, and language-specific subfolders (for example, en-US) with mozilla.adml and firefox.adml.

5. Create the Central Store in SYSVOL. The Central Store is a PolicyDefinitions folder inside the domain's Policies folder. When this folder exists, GPMC reads administrative templates from the Central Store instead of the local machine. DFS Replication automatically copies the folder to all domain controllers. This folder doesn't exist by default - you must create it manually. Create PolicyDefinitions\ and a subfolder for each language you need (for example, en-US\):

   • \\<domain>\SYSVOL\<domain>\Policies\PolicyDefinitions\
   • \\<domain>\SYSVOL\<domain>\Policies\PolicyDefinitions\en-US\
   note:

   If no Central Store exists in SYSVOL, GPMC reads templates from the local C:\Windows\PolicyDefinitions\ folder on the machine running the console. Every Windows installation includes this folder with built-in OS templates, but the contents aren't replicated to other domain controllers. This approach works for single-admin environments and testing but isn't recommended for production.

6. Copy mozilla.admx and firefox.admx to PolicyDefinitions\, and the corresponding .adml files from each language subfolder to the matching subfolder under PolicyDefinitions\.

7. Close and reopen Group Policy Management Editor to load the new templates.

Enable force-install policy

Firefox uses JSON format in the ExtensionSettings policy to manage extensions.

1. In Group Policy Management Editor, go to: Computer Configuration > Policies > Administrative Templates > Mozilla > Firefox > Extensions.
2. Double-click Extension Management.
3. In the Extension Management dialog:
   1. Click Enabled.
   2. In the text field, enter the following JSON to force-install the extension:

      {
        "pangea-aidr-extension@pangea.cloud": {
          "install_url": "https://pangea.cloud/firefox-aidr-extension/aidr-extension-latest.xpi",
          "installation_mode": "force_installed"
        }
      }
   3. Click OK.

note:

The JSON value maps to Firefox's ExtensionSettings policy. force_installed mode installs the extension automatically and prevents the user from disabling or removing it.

warning:

Firefox uses a single ExtensionSettings JSON value for all force-installed extensions. The JSON you enter replaces the entire value. Extensions not included in the JSON lose their force-managed status, and users can remove them. If your organization force-installs other Firefox extensions, include them in the JSON alongside the AIDR extension entry.

Configure computer-level registry settings

Add extension settings that apply to all users under Computer Configuration:

1. Go to Computer Configuration > Preferences > Windows Settings > Registry.
2. Add AIDR base URL:
   1. Right-click and select New > Registry Item. Use these values in the New Registry Properties dialog:
      • Action: Update
      • Hive: HKEY_LOCAL_MACHINE
      • Key Path:

        SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud
      • Value name:

        urlTemplate
      • Value type: REG_SZ
      • Value data: Copy the cloud-specific value from the collector's Install tab in the AIDR console. The AIDR base URL depends on your CrowdStrike cloud:
        • US-1

          https://api.crowdstrike.com/aidr/aiguard
        • US-2

          https://api.us-2.crowdstrike.com/aidr/aiguard
        • EU-1

          https://api.eu-1.crowdstrike.com/aidr/aiguard
   2. Click OK.
3. Add collector credentials:

   1. Right-click and select New > Registry Item. Use these values in the New Registry Properties dialog:

      • Action: Update
      • Hive: HKEY_LOCAL_MACHINE
      • Key Path:

        SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud
      • Value name:

        registrationIdentity
      • Value type: REG_SZ
      • Value data: Copy the value from the collector's Install tab in the AIDR console. The value is a base64-encoded string that looks like eyJzIj...oxfQ==.

   2. Click OK.

4. Add device hostname:

   1. Right-click and select New > Registry Item. Use these values in the New Registry Properties dialog:

      • Action: Update
      • Hive: HKEY_LOCAL_MACHINE
      • Key Path:

        SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud
      • Value name:

        hostname
      • Value type: REG_SZ
      • Value data:

        %COMPUTERNAME%

   2. Click OK.

To edit a registry setting, right-click it and select Properties.

note:

• Group Policy Preferences expand variables, such as %COMPUTERNAME%, at processing time and write the target machine name to the registry as a static string. This differs from REG_EXPAND_SZ, where the OS expands variables each time the value is read.

Cleanup behavior:

GPO Registry Preferences don't remove registry entries when you delete the preference item from the GPO. To enable automatic cleanup, click the Common tab of each registry item and select Remove this item when it is no longer applied. Enable this setting before you apply the GPO to target machines. If you didn't select this option before initial application, you must remove the registry entries manually or with a script.

Configure user identity settings

User identity settings (userId and userFullName) rely on Windows environment variables, such as %USERNAME%, to resolve each user's identity at read time.

These settings require a GPO startup script instead of Registry Preferences:

• GPO Registry Preferences expand %USERNAME% at write time. The variable resolves when the preference is applied, not when the registry value is read. Registry Preferences provide no escape mechanism to store a literal %USERNAME% string.
• Firefox reads managed storage (3rdparty\Extensions\) only from HKLM, not HKCU. You can't use User Configuration Registry Preferences to write per-user values to HKCU instead.

The startup script bypasses both limitations by writing REG_EXPAND_SZ values directly to HKLM. The OS then expands the variables per user session at read time.

Add startup script to SYSVOL

1. In the same GPO, go to Computer Configuration > Policies > Windows Settings > Scripts (Startup/Shutdown).

2. Double-click Startup, then select the Scripts tab.

3. Click Show Files. This opens the GPO's Startup folder in SYSVOL.

4. Copy the following script into a new file named Configure-FirefoxAIDR-UserFields.bat in this folder:

   Configure-FirefoxAIDR-UserFields.bat

   @echo off
   REM Write user identity fields to Firefox managed storage as REG_EXPAND_SZ.
   REM The OS expands %USERNAME% per user session at read time.
   REM Double %% is a batch escape - cmd.exe reduces %% to % before passing to reg.exe.
   
   reg add "HKLM\Software\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud" /v userId /t REG_EXPAND_SZ /d "%%USERNAME%%" /f
   reg add "HKLM\Software\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud" /v userFullName /t REG_EXPAND_SZ /d "%%USERNAME%%" /f

5. Back in the Startup Properties dialog, click Add.

6. In the Script Name field, enter the path or browse to the .bat file you just placed. Leave Script Parameters blank.

7. Click OK to close each dialog.

The script runs at every machine boot in the SYSTEM context. It writes the registry values before any user logs in.

note:

• You can also use a PowerShell startup script to set the user identity fields.

  This guide uses a .bat script because cmd.exe has no execution policy - the script runs without additional configuration.

  On some systems, Windows security zone settings classify SYSVOL's UNC path (\\<domain>\SYSVOL\...) as an internet zone. This causes RemoteSigned to block unsigned .ps1 scripts stored there.

• %USERNAME% resolves to the Windows SAM account name (for example, jhammond), not an email address or display name.

• Multi-domain environments

  By default, userId is set to %USERNAME% (the SAM account name - for example, jhammond). In multi-domain environments, you can use %USERDOMAIN%\%USERNAME% (for example, INGENHQ\jhammond) to distinguish users who share a SAM name across domains.

  To use this format, update the userId line in the script:

  reg add "..." /v userId /t REG_EXPAND_SZ /d "%%USERDOMAIN%%\%%USERNAME%%" /f

tip:

• Script placement

  The standard location is the GPO's SYSVOL Startup folder (opened by Show Files above). For testing or restricted environments where you can't write to SYSVOL, place the script on target machines locally (for example, C:\Scripts\Configure-FirefoxAIDR-UserFields.bat). Then reference that local path in the startup script configuration.

Link GPO and verify

1. Link the GPO to target OUs.

   This GPO uses only Computer Configuration settings. Ensure target computer accounts are in OUs linked to the GPO.

2. On the Scope tab of the GPO, check the Security Filtering section. By default, this section includes Authenticated Users, which covers all domain-joined accounts. If your organization has narrowed filtering to a specific security group, confirm that target computer accounts are members. Otherwise, no endpoints receive the policy.

3. Run gpupdate /force on the target machine.

   gpupdate /force

4. Restart the machine. The startup script runs at boot, not on gpupdate.

5. After restart, log in and verify the registry values:

   reg query "HKLM\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud"
   • Confirm that all five values are present: urlTemplate, registrationIdentity, userId, userFullName, and hostname.
   • Confirm that userId and userFullName resolve to the logged-in user's name.

6. In Firefox on the target machine:

   • Go to about:addons and verify that the extension is installed. If you force-installed the extension through GPO, verify that it can't be disabled.
   • Go to about:policies. Confirm that the AIDR extension policy shows all five values with the correct per-user expansion.

To confirm that the extension connects to AIDR, see Verify Deployment. After successful registration, the extension status progresses through Configured and Ready to Active.

Self-Service (testing)

Select the Self-Service option to quickly evaluate the collector on your own machine before deploying it at scale. This option:

• Introduces the key browser collector deployment steps
• Requires no management tools
• Lets you perform both installation and configuration steps manually on your machine
• Describes the extension deployment statuses and functionality, also applicable to production deployments using enterprise management tools

Self-service limitations:

Self-service deployment is intended for testing and evaluation purposes. It isn't a supported option for production deployments.

The first time you select this option, you must acknowledge these limitations in a confirmation dialog before proceeding.

Install extension

The AIDR Firefox collector is available as a Firefox Add-on, which you can download by following instructions on the collector's Install page in the AIDR console.

1. Use the Get the AIDR Extension button on the collector Install page to download the Firefox extension (.xpi file).
2. In Firefox, go to the about:addons page.
3. Click the gear icon (⛭ - Tools for all add-ons) next to Manage Your Extensions title and select Install Add-on From File.
4. In the file system dialog go to and open the downloaded .xpi file.
5. Follow the prompts to install the extension.

Once the extension is installed, you can manage it on the about:addons page.

Configure extension

1. Return to the Install tab and download the configuration file for your operating system:

   • macOS - AIDR Firefox settings file (.json)
   • Windows - AIDR Windows Firefox policy file (.reg)

   This file contains the collector instance configuration, including credentials to authenticate the extension with the AIDR service.

2. Apply the configuration:

   • macOS

     1. Copy the downloaded .json file to /Library/Application Support/Mozilla/ManagedStorage/. Create the ManagedStorage folder if it does not exist. Administrator privileges are required to write to this location.

        Example copy command

        sudo rsync -av ~/Downloads/pangea-aidr-extension@pangea.cloud.json /Library/Application\ Support/Mozilla/ManagedStorage/

   • Windows - Double-click the .reg file to merge it into the Registry and confirm the prompts.

     warning:

     The registry file modifies the Windows Registry under the extension-specific key path. This doesn't affect other settings, but as a precaution, you can make a registry backup before applying the file. If you're unsure how to back up the Registry, contact your IT or system administrator.

3. Fully close and restart Firefox for the settings to take effect.

Uninstall collector

When you're done testing, remove the browser extension and its system configuration.

1. Remove the browser extension in Firefox's add-on manager (about:addons).

2. Remove the system configuration:

   • macOS - Delete the JSON configuration file from /Library/Application Support/Mozilla/ManagedStorage/:

     Remove the Firefox managed storage file on macOS

     sudo rm /Library/Application\ Support/Mozilla/ManagedStorage/pangea-aidr-extension@pangea.cloud.json

   • Windows - Delete the registry key for Firefox.

     warning:

     This modifies the Windows Registry. You can make a registry backup before proceeding. If you're unsure how to back up the Registry, contact your IT or system administrator.

     Run the following command in a PowerShell session as Administrator:

     Remove the registry key for Firefox

     Remove-Item -Path "HKCU:\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\pangea-aidr-extension@pangea.cloud" -Recurse