Sensor Configuration
This page outlines how to configure the Weaklayer Sensor. The configuration options will be shown first. This is followed by how to apply configurations to the Weaklayer Sensor on different browser/operating system combinations.
Configuration Options
The sensor configuration is well represented in JSON. Some browser/operating system combinations will even require the configuration in JSON format. Here is an example configuration. All sensor configuration options are mandatory.
{
"api": {
"protocol": "http",
"hostname": "localhost",
"port": 8080
},
"installKey": {
"group": "68886d61-572b-41a5-8edd-93a564fb5ba3",
"secret": "jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q==",
"checksum": "jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU="
},
"label": "MitchLaptop-Firefox"
}
There are three top-level keys: api, installKey and label.
API
api contains information about the API location for where the Weaklayer Sensor should send data.
This should be the location of a running Weaklayer Gateway.
api.protocol is the protocol used and can have one of two values: http or https.
Encrypted communication with https is recommended for all production deployments.
api.hostname is the API host or IP address.
api.port is the API port.
Install Key
installKey contains information that the Weaklayer Sensor needs to preform installation.
Please see the gateway CLI documentation for instructions on how to create install key / verifier pairs.
Installation is the process of proving to the Weaklayer Gateway that the sensor belongs in a particular group and the gateway assigning the sensor a unique identity.
installKey.group is the identifer (UUID) for group the sensor will install into.
installKey.secret is a random 512-bit secret that functions as a passphrase for the given group.
installKey.checksum is a SHA-256 hash of installKey.group and installKey.secret. The sensor will not attempt installation and will log errors if this checksum does not match the expected value.
Label
label is a text field that allows you to give supplemental information about this sensor.
I recommend you give each sensor a unique value that will help you correlate Weaklayer data with other data sources.
A good starting point is something of the form {endpoint hostname}-{browser}.
Note that you can give multiple Weaklayer Sensors the same label if you desire.
Configuration Procedure
The Weaklayer Sensor is a browser extension. It retrieves its configuration from the browser extensions API for managed storage. The managed storage API gives a mechanism for providing a read-only copy of data to a browser extension. This makes it extremely useful for providing a rad-only configuration to the Weaklayer Sensor.
Providing data to the managed storage API involves some interaction with the host operating system. The instructions below say how to do this with default tools on these operating systems. However, for a production deployment, you will probably want to perform these operations with your endpoint management tool of choice.
Firefox
Information for configuring the Weaklayer Sensor on Firefox applies the Firefox documentation on "managed storage manifests" to this specific scenario.
Managed storage on Firefox involves using a JSON file no matter the operating system.
The resulting JSON file looks like the above sample JSON, with some extra JSON wrapping it.
You should have a JSON file whose contents look like this and whose name is [email protected].
Using [email protected] as the filename is required.
{
"name": "[email protected]",
"description": "Weaklayer Sensor configuration",
"type": "storage",
"data": {
"api": {
"protocol": "http",
"hostname": "localhost",
"port": 8080
},
"installKey": {
"group": "68886d61-572b-41a5-8edd-93a564fb5ba3",
"secret": "jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q==",
"checksum": "jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU="
},
"label": "MitchLaptop-Firefox"
}
}
When you place this file in its final destination, keep in mind that it needs to be readable by user accounts that will launch Firefox instances.
Linux
On Linux, you place this JSON file in one of a couple locations.
~/.mozilla/managed-storage/[email protected] is the first option where ~ is the home directory of a particular user.
Use this location if you want to apply a different Weaklayer Sensor configuration to each user on an endpoint.
/usr/lib/mozilla/managed-storage/[email protected] is the second option.
Use this location if you want to apply a global Weaklayer Sensor configuration across an endpoint.
If you apply the same configuration across to all Weaklayer Sensors on an endpoint, they will still be assigned different unique identities by the Weaklayer Gateway.
Therefore, I recommend the using the first location and using a different label value for each user account.
MacOS
MacOS is similar to Linux. You place the configuration file in one of two location.
~/Library/Application Support/Mozilla/ManagedStorage/[email protected] to provide different configurations for each user account.
/Library/Application Support/Mozilla/ManagedStorage/[email protected] to use a global configuration across an endpoint.
Again, I recommend providing a per-user configuration using a different label value for each user account.
Windows
Windows differs a little from Linux and MacOS. You need to place the file and then make a registry key pointing to the file. It is your choice where to put the sensor configuration file. Then create a registry key in one of two locations. The key should have a single default value, which is the path to the configuration file.
Use HKEY_CURRENT_USER\SOFTWARE\Mozilla\ManagedStorage\[email protected] to provide a different config for each user account.
Use HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\ManagedStorage\[email protected] to use a global configuration across an endpoint.
Again, I recommend providing a per-user configuration using a different label value for each user account.
Here is an example.
I will be creating a different configuration for each user account.
Lets say that I placed the configuration file at C:\Users\Mitch\configs\[email protected].
Then I would create a registry key at HKEY_CURRENT_USER\SOFTWARE\Mozilla\ManagedStorage\[email protected] pointing to this file.
This can be accomplish with the following command.
reg add HKEY_CURRENT_USER\SOFTWARE\Mozilla\ManagedStorage\[email protected] /ve /d C:\Users\Mitch\Desktop\[email protected]
Chrome
Information for configuring the Weaklayer Sensor on Chrome applies the Chromium documentation to this specific scenario.
Chrome uses an extension id for configuring the managed storage of an extension.
In this section, we'll assume the Weaklayer Sensor id is joancbgicjhnjkkknlpablgmdcgcpnhj.
You should find the actual extension id by opening the Chrome installed extensions page in developer mode.
Linux
Configuring the Weaklayer Sensor for Chrome / Linux uses a JSON file.
Create a file at /etc/opt/chrome/policies/managed/[email protected] with the following structure.
{
"3rdparty": {
"extensions": {
"joancbgicjhnjkkknlpablgmdcgcpnhj": {
"api": {
"protocol": "http",
"hostname": "localhost",
"port": 8080
},
"installKey": {
"group": "68886d61-572b-41a5-8edd-93a564fb5ba3",
"secret": "jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q==",
"checksum": "jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU="
},
"label": "MitchLaptop-Chrome"
}
}
}
}
MacOS
Configuring the Weaklayer Sensor for Chrome / MacOS uses a plist file and MCX preferences.
Create a file called [email protected] with the following contents.
The location of the file does not matter.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.google.Chrome.extensions.joancbgicjhnjkkknlpablgmdcgcpnhj</key>
<dict>
<key>api</key>
<dict>
<key>state</key>
<string>always</string>
<key>value</key>
<dict>
<key>protocol</key>
<string>http</string>
<key>hostname</key>
<string>localhost</string>
<key>port</key>
<integer>8080</integer>
</dict>
</dict>
<key>installKey</key>
<dict>
<key>state</key>
<string>always</string>
<key>value</key>
<dict>
<key>group</key>
<string>68886d61-572b-41a5-8edd-93a564fb5ba3</string>
<key>secret</key>
<string>jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q==</string>
<key>checksum</key>
<string>jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU=</string>
</dict>
</dict>
<key>label</key>
<dict>
<key>state</key>
<string>always</string>
<key>value</key>
<string>MitchLaptop-Chrome</string>
</dict>
</dict>
</dict>
</plist>
Next this plist file needs to be imported.
You'll use the dscl tool with admin privileges for this.
Issue the following command.
$ dscl -u <admin username> /Local/Default -mcximport /Computers/local_computer [email protected]
You should replace <admin username> with the admin account you want this action performed with.
You might receive an error about this node path being invalid.
The following commands, reproduced from the chromium docs, will create a not at /Computers/local_computer.
$ GUID=`uuidgen`
$ ETHER=`ifconfig en0 | awk '/ether/ {print $2}'`
$ dscl -u admin_username /Local/Default -create /Computers/local_computer
$ dscl -u admin_username /Local/Default -create /Computers/local_computer RealName "Local Computer"
$ dscl -u admin_username /Local/Default -create /Computers/local_computer GeneratedUID $GUID
$ dscl -u admin_username /Local/Default -create /Computers/local_computer ENetAddress $ETHER
Additionally, you may need to refresh preferences with this command.
$ sudo mcxrefresh -n <username>
Replace <username> with the user account that you wish to affect.
Windows
Configuring the Weaklayer Sensor for Chrome / Windows uses the Windows registry.
Create a file called [email protected] with the following contents.
The location of the file does not matter.
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Policies\Google\Chrome\3rdparty\extensions\joancbgicjhnjkkknlpablgmdcgcpnhj\policy\api]
"protocol"="http"
"hostname"="localhost"
"port"="8080"
[HKEY_CURRENT_USER\Software\Policies\Google\Chrome\3rdparty\extensions\joancbgicjhnjkkknlpablgmdcgcpnhj\policy\installKey]
"group"="68886d61-572b-41a5-8edd-93a564fb5ba3"
"secret"="jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q=="
"checksum"="jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU="
[HKEY_CURRENT_USER\Software\Policies\Google\Chrome\3rdparty\extensions\joancbgicjhnjkkknlpablgmdcgcpnhj\policy]
"label"="MitchLaptop-Chrome"
Import these registry entries with the following command in an administrator command prompt.
> REG IMPORT [email protected]
Note: The above file sets the registry for the current user. This is recommended so you can set a different label for each user on an endpoint. Substitute HKEY_LOCAL_MACHINE for HKEY_CURRENT_USER in the above file to set the registry for the entire endpoint. This will give the same configuration to all Weaklayer Sensors that run on the endpoint.
Edge
The Weaklayer Sensor runs on the Chromium-based Edge browser. Because it is Chromium-based, the configuration procedure for Edge is very similar to Chrome. Again, this section was created by applying the Chromium documentation to this specific scenario. Microsoft provides additional information for configuring Edge in the Edge documentation. Note that there is no Microsoft Edge for Linux.
Similar to Chrome, Edge uses an extension id for configuring the managed storage of an extension.
In this section, we'll assume the Weaklayer Sensor id is kngkbghmgoehankpjifhjjglibcickjb.
You should find the actual extension id by opening the Edge installed extensions page in developer mode.
MacOS
Managed storage for Edge on MacOS does not work as expected according to the Chromium documentation with corrections to account for Edge/Chrome/Chromium naming differences. Microsoft does not provide managed storage documentation for Edge. Furthermore, Edge itself is not open source so it isn't possible to see how the Edge code differs from Chromium here. Please get in touch if you want to see instructions for Edge on MacOS or if you know how to accomplish this configuration.
Windows
Configuring the Weaklayer Sensor for Edge / Windows uses the Windows registry.
Create a file called [email protected] with the following contents.
The location of the file does not matter.
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\3rdparty\extensions\kngkbghmgoehankpjifhjjglibcickjb\policy\api]
"protocol"="http"
"hostname"="localhost"
"port"="8080"
[HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\3rdparty\extensions\kngkbghmgoehankpjifhjjglibcickjb\policy\installKey]
"group"="68886d61-572b-41a5-8edd-93a564fb5ba3"
"secret"="jTbup3jD+nWFRw2LW5k6v0dP+qf6cWXsc3IazN39GnaMeKEp13kpyh6AJFo3V1ckeD3dt0JXfoqmeOWr2jU29Q=="
"checksum"="jvqWXRmh9JAnbwDS19W59lOJXD2dZuRglhFtsJzDedU="
[HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\3rdparty\extensions\kngkbghmgoehankpjifhjjglibcickjb\policy]
"label"="MitchLaptop-Edge"
Import these registry entries with the following command in an administrator command prompt.
> REG IMPORT [email protected]
Note: The above file sets the registry for the current user. This is recommended so you can set a different label for each user on an endpoint. Substitute HKEY_LOCAL_MACHINE for HKEY_CURRENT_USER in the above file to set the registry for the entire endpoint. This will give the same configuration to all Weaklayer Sensors that run on the endpoint.