GRR On The Command Line With GRRShell

By

What is GRR?

GRR Rapid Response (or GRR) is an incident response framework focused on remote live forensics. It is a tool that communicates with its deployed endpoint agents to collect and deliver forensics artifacts to an incident responder for analysis from one machine or thousands. This article assumes you’re already familiar with using GRR in a production environment.

GRR is GRReat! But...

GRR is a beneficial tool to have available, but it does have some limitations:

  • Browsing the Virtual File System (VFS) In the Web UI can be time consuming for in-depth analysis. Upon browsing to a directory, a new ListDirectory flow is launched, and the operator must wait for that flow to complete before continuing. For repeated directory navigations, this time adds up.
  • Finding a file of an unknown location requires a ClientFileFinder flow. The exact syntax can be challenging to remember, resulting in needing to check the documentation frequently.
  • Launching artifact collection flows is located in a separate section of the Web UI than VFS browsing.
  • Artifacts collected are downloaded via a different method to files collected via the VFS in the Web UI.
  • Some people, including myself, just prefer the command line instead of a web browser.

Enter GRRShell

GRRShell is a command line REPL utility and it should be familiar to anyone who has used sftp or similar utilities in Linux. Designed for interacting with a single remote client, GRRShell fetches a TimelineFlow from the client, which is used to populate an in-memory representation of the client file system called the Emulated File System (EFS) - so named to differentiate it from the VFS in the Web UI. The operator can navigate the EFS with immediate speed rather than waiting for ListDirectory flows to complete.

Our analysis shows that a ListDirectory flow takes anywhere between 5 and 20 seconds, while a TimelineFlow takes approximately 1 minute to return a result to the engineer. As such, after approximately 7 directory changes, a single TimelineFlow used to populate the EFS is more time efficient. Front-loading that wait time for an engineer solves the first limitation above. Of course, timelines can become stale as files and artifacts change on the client, so fresh timelines can be requested within the tool from the client during your investigation.

The remaining points are addressed as follows:

  • Finding a location of a file can be near-instantaneous with the EFS, and can support more standardized filename patterns via regex.
  • Artifact collections (ArtifactCollectorFlow) are issued at the same command prompt as file collections (ClientFileFinder).
  • ArtifactCollector and ClientFileFinder flows download results to the same location on the engineers workstation.
  • No web browser - it's a CLI tool!

GRRShell In Action

At launch, GRRShell will (in the following order of preference) use a TimelineFlow specified by the operator, a recent existing TimelineFlow (up to 12 hours old), or request a new TimelineFlow, and use the result to populate a navigable EFS.

Typical usage may look like the following:

In addition to startup, the above shows artifact collection (supporting British and American English spelling) including autocomplete for both the command and selection of the artifact to collect. Artifacts that download files are performed asynchronously in the background. Artifacts that display a result like the above example are synchronous and will block until complete (or the user hits CTRL+C).

When navigating directories or collecting files or file information as shown above, autocomplete is supported for both directory names and files. Here we can see the operator requesting file information and the Zone.Identifier Alternate Data Stream for the file (via the --ads flag) for display, followed by collection of the file itself. The file information collection is synchronous, and the file collection is performed in the background with the result available in the local file system when complete.

Some GRRShell Limitations

GRRShell aims to provide support for most of the GRR Web UI features to navigate a file system and collect artifacts. GRRShell does not have any support for GRR Hunts, so you'll still need the Web UI for those.

Additionally, GRRShell is not primarily designed for collecting artifacts from multiple machines. It does however provide a couple of non-interactive commands that allow you to collect the same artifact or files for multiple hosts. For example:

$ cat clients | while read client; do grrshell artifact --grr-server http://address --username admin --password password --client $client --artifact BrowserHistory --local-path .; done

For a more comprehensive list of options see the appendix or the output of grrshell help

Getting GRRShell

GRRShell can be installed via pip: $ pip install grrshell

The source is available on Github. Bugs and feature requests can of course be raised at that same location.

Summary

GRRShell is designed for incident responders who prefer working on a command line instead of a web browser, for collecting files and artifacts from client machines to a consistent local location. GRRShell aims to be more time efficient for navigating, and finding files within, a client file system.

Appendix: Full Shell Commands List

  • help (aliases h, ?) - Display help text. help <command> displays extended help for the command, where available
  • artefact (alias artifact) - Perform an ArtifactCollector flow. The flow is performed synchronously or asynchronously, depending on the artifact requested
  • cd <path> - Change working directory
  • clear - Clear the terminal screen
  • collect <path> - Collect remote files via a ClientFileFinder flow. CFF syntax is supported, which is documented here
  • detail <flowid> - Displays detailed information on a specific flow
  • exit (alias quit, <CTRL+D>) - Exit the shell
  • find <regex> - Search the EFS for a filename matching a regex
  • flows - List flows launched in the GRRShell session. Specify --all for all flows launched on the client.
  • info <path> (alias hash) - Display file information.
    • --offline - Display the values in the EFS instead of a launching a flow
    • --ads - Include the Alternate Data Stream
  • ls - List entries in a directory. Adjust sorting with -S, -t and -r
  • pwd - Display the current working directory
  • refresh - Schedule a new TimelineFlow, and update the EFS with the result. An optional path can be specified for a Timeline root for refreshing only a subdirectory, if required
  • resume <flowid> - Reattach an existing completed or in progress flow to this GRRShell session
  • set <name> <value> - Set a shell variable. Currently, only one variable is supported:
    • max-file-size - Specify a max file size for file collections

Popular posts from this blog

Parsing the $MFT NTFS metadata file

By
Background Numerous articles have been written about parsing the $MFT NTFS metadata file before. Some of these explain the technique itself [ 1 ] and others mostly focus on how to use tools. Rarely do articles mention the pros and cons of the technique from a digital forensics perspective [ 2 ].  What is $MFT parsing?  For readers not familiar with the NTFS file system, MFT stands for Master File Table. This table is stored in a file system metadata file, meaning that as far as the file system is concerned it is a file, however that the file contains file system metadata not “regular” content. The name of this file is “$MFT”.  The MFT consists of a sequence of (predetermined) fixed-size entries (or MFT entries). These entries are typically 1024 bytes in size, however the size is defined in the NTFS volume header and in a “regular” MFT entry itself.  The first 4-bytes of a “regular” MFT-entry (or record) starts with the signature “FILE”. The MFT entry can also be filled wit
Read more

Incident Response in the Cloud

By
Many organizations have begun moving a majority of their services towards the cloud in recent years. As a result, attackers have shifted their focus towards the cloud. This has resulted in new techniques and methods specifically designed to compromise cloud infrastructure, like the recent SALTSTACK vulnerability that was widely exploited [ 1 ]. Therefore it is critical for these organizations to have an incident response team that understands the new risks attached to cloud and how cloud can make incident response easier or harder.  In this blog post we will walk you through each phase you may encounter in traditional incident response and highlight the differences when adopting cloud computing. It is aimed towards both those who are new to incident response and cloud computing. We’ve included insights that will benefit organizations taking that step towards cloud who want to ensure they are prepared to respond efficiently to cloud incidents.  Traditional Incident Response Before jump
Read more

Container Forensics with Docker Explorer

By Anonymous
  Introduction As previous blog posts on cloud forensics have noted, applications are increasingly being deployed using container orchestration frameworks such as Kubernetes, especially in cloud environments.  Similar to traditional deployments on physical servers or virtual machines (VMs), when a containerised application has a security issue it can lead to a compromise of the underlying compute architecture. In the case of container deployments this means a compromise of the container itself, the container host, or even a wider cluster compromise via abuse of orchestration tools. Often digital forensics is required to establish what went wrong and remediate any issues. This article will provide an introduction to container forensics with Docker Explorer by working through a scenario involving a compromised container running within a Kubernetes cluster. Although Kubernetes is briefly mentioned, this article will focus on analysis of an individual container rather than the wider clust
Read more