Installing from source

This guide will walk you through the process of installing GRR from sources and making it communicate through Fleetspeak, rather than its old custom communication protocol.

At the end you should have a working single-machine setup with both the server and the client communicating with each other. Follow other documentation pages to learn how to adapt this setup to real deployments.

Installation

System

Because we are going to install everything from sources, there are some dependencies required to be installed on your system first.

Since GRR is written in Python, the fundamental requirement is to have it available on your system. GRR needs at least Python 3.6. On recent Debian-based distros it should be enough to install the python3-dev package:

$ sudo apt install python3-dev

Moreover, both GRR and Fleetspeak use MySQL (or MariaDB) as its RDBMS, so make sure it is also installed. The package that GRR uses to communicate with MySQL depends on the MySQL client library, so you should set it up as well. On Debian distros it is libmysqlclient-dev or libmariadbclient-dev:

$ sudo apt install libmysqlclient-dev

Finally, GRR uses Closure Compiler to process its JavaScript files. While installing Closure Compiler is handled for you in one of the build scripts, it requires a Java Runtime Environment to run. OpenJDK should work just fine, so on Debian distros it is enough to install it like:

$ sudo apt install openjdk-13-jre

Fleetspeak

Install Fleetspeak and follow the guide to learn how to configure services and run the Fleetspeak server and the Fleetspeak client.

GRR

Use Git to clone the GRR repository to your workstation and enter into it:

$ git clone https://github.com/google/grr
$ cd grr/

For the rest of the guide we will assume that the working directory is the root GRR folder, placed in your home folder (/home/username/grr), so remember to adapt to your specific setup.

To avoid cluttering the filesystem, we will also use Python’s virtual environment:

$ python3 -m venv venv

Before proceeding with installing GRR packages themselves, you also need to install grpcio-tools and protobuf packages (for compiling Protocol Buffers files) and nodeenv (for compiling JavaScript files):

$ venv/bin/pip install grpcio-tools protobuf nodeenv
$ venv/bin/nodeenv -p --prebuilt --node=12.16.1

Once your virtual environment is ready, install all the required GRR Python packages:

$ source venv/bin/activate
(venv) $ pip install -e grr/proto/
(venv) $ pip install -e grr/core/
(venv) $ pip install -e grr/client/
(venv) $ pip install -e grr/client_builder/
(venv) $ pip install -e api_client/python/
(venv) $ pip install -e grr/server/[mysqldatastore]
(venv) $ deactivate

If you encounter any problems related to mysqlclient during the installation of grr/server when using MariaDB, then try the following:

(venv) $ pip install mysqlclient
(venv) $ pip install -e grr/server/
(venv) $ deactivate

Configuration

MySQL / MariaDB

We need to create a GRR database along with an associated user. In this guide the database will be named grr, the user will be named grr-user and will be identified by password grr-password. We also need to increase the max allowed packet size to 40 MiB.

Fire up the MySQL console as an administrative user, e.g.:

$ mysql --user root

Then, use the following commands:

mysql> CREATE USER `grr-user` IDENTIFIED BY 'grr-password';
mysql> CREATE DATABASE `grr`;
mysql> GRANT ALL PRIVILEGES ON `grr`.* TO `grr-user`;
mysql> SET GLOBAL max_allowed_packet = 40 * 1024 * 1024;

GRR

Now you should initialize the GRR configuration. GRR comes with a tool for this and handles most of the things for you:

$ venv/bin/grr_config_updater initialize

Use the MySQL credentials that you configured previously. It should be fine to keep the rest of the things at the default values (but skip client repacking).

Now you need to configure GRR to work with Fleetspeak. Pick an unused port, e.g. 1138 on which your GRR service will run.

Add the following lines to the GRR config file in grr/core/install_data/etc/server.local.yaml (where localhost:1138 uses the port you picked and localhost:9091 is the address your Fleetspeak admin server binds to):

Client.fleetspeak_enabled: true
Server.fleetspeak_message_listen_address: "localhost:1138"
Server.fleetspeak_server: "localhost:9091"

Fleetspeak

Server

Add the following definition to your Fleetspeak server-side service configuration file (using appropriate port you chose for GRR):

services {
  name: "GRR"
  factory: "GRPC"
  config: {
    [type.googleapis.com/fleetspeak.grpcservice.Config] {
      target: "localhost:1138"
      insecure: true
    }
  }
}

Client

Define a new service text file with the following contents:

name: "GRR"
factory: "Daemon"
config: {
  [type.googleapis.com/fleetspeak.daemonservice.Config]: {
    argv: "/home/username/grr/venv/bin/python"
    argv: "-m"
    argv: "grr_response_client.grr_fs_client"
  }
}

Running

Start the Fleetspeak server and all the GRR components in separate terminals:

$ venv/bin/python -m grr_response_server.gui.admin_ui

$ venv/bin/python -m grr_response_server.bin.worker

$ venv/bin/python -m grr_response_server.bin.fleetspeak_frontend

Finally, start the Fleetspeak client. After a moment, it should successfully register with GRR and you should be able to see it in the GRR UI. In your web browser, using appropriate client identifier, navigate to:

http://localhost:8000/#/clients/C.<your_fleetspeak_client_id>/host-info

You should see a page with details about your client. GRR should automatically schedule initial interrogation flow, which should complete within couple of minutes. You can also try some simpler flows, for example listing all processes (ListProcesses in Processes category), to verify that everything works as expected.