google/rrg

A Rust rewrite of the GRR agent.

RRG

RRG is a Rust rewrite of GRR (a remote live forensics framework).

It strives to evaluate how feasible it is to rewrite the client-side part of GRR (an agent service) without all the historical baggage that the current version has to carry. For example, it does not implement its own communication layer, but leverages Fleetspeak for that. It also tries to assess how many existing issues related to the Python codebase could be resolved by using a modern language with powerful type system and strong safety guarantees.

This project is not an official Google product, is under heavy development and should not be used for any production deployments. So far, it is nothing more than an experiment.

Development

Prerequisites

RRG is written in Rust and needs a Rust toolchain to be built. The recommended way of installing Rust is to use rustup.

Because RRG is only a component of a bigger system, to do anything useful with it you also need to setup Fleetspeak and GRR.

Building

RRG uses Cargo for everything, so building it is as easy as running:

$ cargo build

This will create a unoptimized executable target/debug/rrg.

To create release executable (note that this is much slower and is not suitable for quick iterations) run:

$ cargo build --release

This will create an optimized executable target/release/rrg.

Testing

To run all tests:

$ cargo test

To run tests only for a particular crate:

$ cargo test --package='ospect'

To run only a particular test:

$ cargo test --package='rrg' action::get_file_contents::tests::handle_empty_file

To verify that the code compiles on all supported platforms:

$ cargo check --tests --target='x86_64-unknown-linux-gnu' --target='x86_64-apple-darwin' --target='x86_64-pc-windows-gnu'

Note that this requires additional toolchains for cross-compilation to be installed.

It is also possible to use cross-compilation and tools like Wine to run tests on another operating system:

$ cargo test --target='x86_64-pc-windows-gnu' --package='rrg' --no-run
$ wine target/x86_64-pc-windows-gnu/debug/deps/rrg-bcf99adf861ea84a.exe

Structure

Directories

• crates/ — All Rust crates that the project consists of live here.
• docs/ — All non-code documentation and guides live here.
• proto/ — All Protocol Buffers definitions describing RRG's API live here.

Crates

• ospect — Tools for inspecting the operating system.
• rrg — Implementation of all agent actions and the entry point.
• rrg-proto — Code generated from Protocol Buffer definitions.

rrg's Issues

Implement the `ListDirectory` action

RRG should support the ListDirectory action. It accepts ListDirRequest as input and should respond with StatEntry.

Implement the `GetClientInfo` action

RRG should support the GetClientInfo action. It does not have any input arguments and should respond with ClientInformation.

Make the `fuse` crate an optional dependency

Currently, each developer needs to install libfuse-dev in order to run RRG tests (because the dependency on the fuse crate). Unfortunately, until rust-lang/cargo#1596 is resolved, this seems to be impossible to workaround for now.

Implement the `GetClientStats` action

RRG should support the GetClientStats action. It accepts GetClientStatsRequest as input and should respond with ClientStats.

Note that this action requires the statistics collection mechanism to be implemented in the first place.

Implement the `GetInstallDate` action

RRG should support the GetInstallDate action. It does not have any input arguments and should respond with an uint64 timestamp.

Implement the `Grep` action

RRG should support the Grep action. It accepts GrepSpec as input and should respond with BufferReference.

Implement the `GetPlatformInfo` action

RRG should support the GetPlatformInfo action. It does not have any input arguments and should respond with Uname.

Implement the `GetHostname` action

RRG should support the GetHostname action. It does not have any input arguments and should respond with DataBlob.

Implement the `GetFileStat` action

RRG should support the GetFileStat action. It accepts GetFileStatRequest as input and should respond with StatEntry.

Implement the `EnumerateInterfaces` action

RRG should support the EnumerateInterfaces action. It does not have any input arguments and should respond with Interface.

Implement the `EnumerateFilesystems` action

RRG should support the EnumerateFilesystems action. It does not have any input arguments and should respond with Filesystem.

Implement the `FingerprintFile` action

RRG should support the FingerprintFile action. It accepts FingerprintRequest as input and should respond with FingerprintResponse.

Implement the `HashFile` action

RRG should support the HashFile action. It accepts FingerprintRequest as input and should respond with FingerprintResponse.

Implement the `GetLibraryVersions` action

RRG should support the GetLibraryVersions action. It does not have any input arguments and should respond with Dict.

Implement the `Timeline` action

RRG should support the Timeline action. It accepts TimelineArgs as input and should respond with TimelineResult.

Implement the `GetMemorySize` action

RRG should support the GetMemorySize action. It does not have any input arguments and should respond with uint64.

Implement the `TransferBuffer` action

RRG should support the TransferBuffer action. It accepts BufferReference as input and should respond with the same (which is awkward, but we need to follow all GRR oddities).

Note that unlike the ReadBuffer action, this method also sends data to a persistent session (or a "well-known flow" using the GRR nomenclature).

Migrate from `getmntinfo` to `getfsstat`

Currently, in the macOS implementation of ospect::fs::mounts function we use the getmntinfo function. However, it is not thread-safe and even though we try to harden against some of the issues that might arise from its usage, it is still theoretically not sound from the Rust perspective. A much better approach would be to use getfsstat that apparently does not have such issues.

Implement the `FileFinderOS` action

RRG should support the FileFinderOS action. It accepts FileFinderArgs as input and should respond with FileFinderResult.

`ospect::os::fqdn` does not work on macOS

Some change recently caused the tests for ospect::os::fqdn to fail. GitHub Actions run for 34441db (run) succeeded but the following 1a39af0 (run) failed. The commit does not touch this function at all.

When testing locally the low-level function used to implement this (getaddrinfo), the same error happens:

#include <limits.h>
#include <stdio.h>
#include <unistd.h>
#include <netdb.h>

int main(void)
{
    int err;

    long host_name_max = sysconf(_SC_HOST_NAME_MAX);
    char hostname[host_name_max + 1];
    
    err = gethostname(hostname, sizeof(hostname));
    if (err != 0) {
        fprintf(stderr, "failed to get hostname: %d", err);
        return 1;
    }

    printf("hostname: %s\n", hostname);

    struct addrinfo hints = {0};
    hints.ai_family = PF_UNSPEC;
    hints.ai_socktype = 0;
    hints.ai_protocol = 0;
    hints.ai_flags = AI_CANONNAME;

    struct addrinfo *info;

    err = getaddrinfo(hostname, NULL, &hints, &info);
    if (err != 0) {
        fprintf(stderr, "failed to get hostname information: %s\n", gai_strerror(err));
        return 1;
    }

    printf("fqdn: %s\n", info->ai_canonname);

    freeaddrinfo(info);

    return 0;
}

When running this code, the call to getaddrinfo fails with EAI_NONAME ("nodename nor servname provided, or not known"). This indicates that we call this function incorrectly (either nodename or servname must be provided but we are clearly doing so).

The run for commit 34441db was on macOS 12.6.9 whereas the run for commit 1a39af0 was on macOS 12.7. There is a chance that some system-level change was introduced that broke us.

Implement the `EnumerateUsers` action

RRG should support the EnumerateUsers action. It does not have any input arguments and should respond with User.

Implement the `ListProcesses` action

RRG should support the ListProcesses action. It does not have any input arguments and should respond with Process.

Implement the `ListNetworkConnections` action

RRG should support the ListNetworkConnections action. It accepts ListNetworkConnectionsArgs as input and should respond with NetworkConnection.

Implement the `HashBuffer` action

RRG should support the HashBuffer action. It accepts BufferReference as input and should respond with BufferReference.

Implement the `SendFile` action

RRG should support the SendFile action. It accepts SendFileRequest as input and should respond with StatEntry.

Implement the `Osquery` action

RRG should support the Osquery action. It accepts OsqueryArgs as input and should respond with OsqueryResult.

Implement the `ReadBuffer` action

RRG should support the ReadBuffer action. It accepts BufferReference as input and should respond with the same (which is awkward, but we need to follow all GRR oddities).

Implement the `GetConfiguration` action

RRG should support the GetConfiguration action. It does not have any input arguments and should respond with Dict.

Implement the `Echo` action

RRG should support the Echo action. It accepts the EchoRequest as input and should respond with EchoRequest as well (which is not a good idea, but sadly RRG needs to follow all the bad decisions made by GRR).