Getting Started Tutorial

Welcome to the Weaklayer "Getting Started" tutorial. This page provides you instructions on how to start receiving browser security data from a Weaklayer sensor running locally. This will allow you to get a hands-on feel for the Weaklayer system and the data it can provide you. This tutorial attempts to be browser agnostic, but Chrome on Windows is used as a specific example where appropriate.

Weaklayer System Overview

Weaklayer is a software system for "Browser Detection and Response". It is designed to provide you useful security data from user activity in their web browsers. The Weaklayer system has two halves to it.

The first half is the Weaklayer Sensor. The Weaklayer Sensor is a browser extension. It is the code that collects and produces the useful security data.

The second half is the Weaklayer Gateway. The Weaklayer Gateway is a server application. The gateway is responsible for securely receiving and handling Weaklayer Sensor data. Sensors contact the gateway over HTTP(S) with the data they have collected. The gateway then takes this data and makes it available to the rest of your security stack.

Both the Weaklayer Sensor and Reference Gateway are Open Source. Please see our GitHub for more details.

Weaklayer Gateway

First, we will set up a Weaklayer Gateway instance in order to receive sensor data. Download the latest binary release from the Weaklayer Gateway Reference Implementation releases page. Extract the package in a location you like. Your Downloads folder is fine.

The Weaklayer Gateway Reference Implementation binary packages comes with an example config. This example config makes the gateway listen on localhost:8080 for HTTP connections. Look at the Gateway Configuration documentation for an explanation of all the gateway configuration options. Note that the example config should not be used in production.

To run the gateway, navigate to the extracted folder on the command line and execute this command.

weaklayer-gateway-{os}-{architecture} server --config example_config.json

It will look like this on Windows. 

> weaklayer-gateway-windows-amd64.exe server --config example_config.json
{"level":"info","time":1594169688635508,"message":"Starting Weaklayer Gateway Server"}

Application logs print to stderr (like above) and incoming sensor data will print to stdout. The time field in the application logs is in Epoch microseconds.

Weaklayer Sensor

The next step is to install and configure the Weaklayer Sensor.

Installation

Please see the Sensor Installation docs page.

Configuration

Configuring browser extensions is highly dependant on which browser and operating system is in use. The Sensor Configuration docs page provides fulls details on how to configure the Weaklayer Sensor with each browser / operating system combination that is supported. Additionally, the Sensor Configuration docs page explains what each sensor configuration option does. Instructions for Chrome on Windows are reproduced here.

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]

This config gives the sensor three pieces of information:

  1. Where to send its data
  2. An install key that matches the example gateway config
  3. A label that will be attached to the sensor's identity

Feel free to change the label value to something more personalized. Additionally, you may need to restart your browser for this configuration to take effect.

Weaklayer Data

Data Explanation

Now start browsing the web with the Weaklayer Sensor installed. The Weaklayer Gateway's output should look something like this.

> weaklayer-gateway-windows-amd64.exe server --config example_config.yaml
{"level":"info","time":1594208999270931,"message":"Starting Weaklayer Gateway Server"}
{"type":"Install",isNewInstall":true,"time":1594209020167364,"sensor":"f5d4650e-5c73-4384-bfeb-90153fe65e0c","group":"68886d61-572b-41a5-8edd-93a564fb5ba3","label":"Mitch's Laptop","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:82.0) Gecko/20100101 Firefox/82.0"}
{"type":"Window","time":1594209078132495,"sensor":"f5d4650e-5c73-4384-bfeb-90153fe65e0c","group":"68886d61-572b-41a5-8edd-93a564fb5ba3","isTopLevelWindow":true,"topLevelWindowReference":1594209078132495}
{"type":"WindowLocation","time":1594209078152194,"sensor":"f5d4650e-5c73-4384-bfeb-90153fe65e0c","group":"68886d61-572b-41a5-8edd-93a564fb5ba3","protocol":"https","hostname":"www.youtube.com","path":"/","search":"","hash":"","windowReference":1594209078132495}
{"type":"WindowLocation","time":1594209111551197,"sensor":"f5d4650e-5c73-4384-bfeb-90153fe65e0c","group":"68886d61-572b-41a5-8edd-93a564fb5ba3","protocol":"https","hostname":"www.youtube.com","path":"/watch","search":"?v=dQw4w9WgXcQ","hash":"","windowReference":1594209078132495}

The first line is an application log from the gateway that printed to stderr. The remaining lines are Weaklayer events printed to stdout.

Each Weaklayer event specifies four pieces of information at minimum:

  1. The event type in the type field
  2. The time the event occurred at, measured in epoch microseconds, in the time field
  3. The sensor identity UUID in the sensor field
  4. The installation group UUID in the group field

An event can be uniquely identified by the sensor and time fields. We'll see that some events link to other events by referencing the time value of an event from the same sensor. Additional fields may be present based on the event type.

Install Events

The first event printed is an Install event. Its content looks like this.

{
  "type":         "Install",
  "isNewInstall": true,
  "time":         1594209020167364,
  "sensor":       "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":        "68886d61-572b-41a5-8edd-93a564fb5ba3",
  "label":        "Mitch's Laptop"
  "userAgent":    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:82.0) Gecko/20100101 Firefox/82.0"
}

The primary purpose of install events is to associate metadata with the sensor UUID that will appear in future events. label provides the value you set in the sensor config for the sensor label.
userAgent is the value of the User-Agent HTTP header when the sensor is installing.

Window Events

The Window event corresponds to the creation of a new window (a javascript execution environment - not a javascript GUI window) in the browser. For example, a new browser tab or an iframe embedded in a web page will generate window events. The event looks like this.

{
  "type":                    "Window",
  "time":                    1594209078132495,
  "sensor":                  "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":                   "68886d61-572b-41a5-8edd-93a564fb5ba3"
  "isTopLevelWindow":        true,
  "topLevelWindowReference": 1594209078132495
}

isTopLevelWindow indicates if this window is an embedded window (e.g. iframe) or the topmost window in the window hierarchy.
topLevelWindowReference points to the topmost window in the window hierarchy. This relationship provides information regarding windows being embedded in web pages. If isTopLevelWindow is true then topLevelWindowReference will be equal to time.

WindowLocation Events

A simple thing that can happen inside of a window is a user visiting a web page. This web page is loaded from a URL or location. WindowLocation events give the locations of web pages that are loaded. These events look like this.

{
  "type":            "WindowLocation",
  "time":            1594209078152194,
  "sensor":          "f5d4650e-5c73-4384-bfeb-90153fe65e0c",
  "group":           "68886d61-572b-41a5-8edd-93a564fb5ba3",
  "protocol":        "https",
  "hostname":        "www.youtube.com",
  "path":            "/",
  "search":          "",
  "hash":            "",
  "windowReference": 1594209078132495
}

The fields in this event give you the different URL components for the window's location. Note that the port field is missing. This indicates the default port for the protocol is being used (https/443 above).

The windowReference field points to a Window event. It tells you which window loaded a page from this location. In the example trail of events, we see multiple WindowLocation events point to the same Window event. This is popular in modern web apps where the same javascript execution environment is used when navigating between pages on the same site. Try going to a different domain (e.g. https://weaklayer.com) from the same tab. This should result in a new Window event, indicating a new javascript execution environment is being used for that page.

The Events docs page gives examples and explanations for all the events that Weaklayer produces.

What's Next

Hopefully this page has given you a path to getting Weaklayer up and running on your systems today. The Kicking Ass with Weaklayer page will show you how to start producing value from Weaklayer data by detecting credential phishing.

Please submit an issue on Github or contact us if you have any questions. Starring the Weaklayer Sensor repository is a big help if you like what you see.