QuoLab Add-on for Splunk

Introduction

The QuoLab Add-On for Splunk adds the quolabquery generating command to a Splunk environment, allowing an authorized user to make requests to one or more QuoLab servers to bring in data to Splunk for additional forensic and analytic investigation.

Prerequisites

• Splunk
• a QuoLab server

Architecture

This add-on comprises an authentication lookup and a python script that implements quolabquery, a generating command. quolabquery wraps and simplifies requests to the QuoLab REST API. Requests will be sent through web hooks to the same url as the user interface.

Installation

Steps:

1. Install the app on your search head or standalone Splunk instance using the normal process.
   If you need additional help, please refer to Splunk's docs: About installing Splunk add-ons.
2. Configure app via UI (as an admin).
   The add on will automatically direct you to the setup page the first time you load it from the Splunk web interface.
   Here you will be prompted to configure a QuoLab server.
3. Configure one or more QuoLab servers.
   If only a single QuoLab server exists in your environment, name the server quolab to simplify your usage later.
   Add as many servers as you need, now or later.
4. Confirm that a quolab server is setup correctly by running the quolabquery search to test for a response.
   For example, run the search | quolabquery type=ip-address id="8.8.8.8".
   If you created more than one server or named it something other than "quolab", you can test it by running | quolabquery server=MY-SERVER-NAME type=ip-address id="8.8.8.8"
5. Grant authorization to users who should be allow to run quolabquery.
   Either add users directly to the quolab_servers_user role, or inherit that roles from role(s) that already exist within your organization.
   Members of the admin role will be able to run this automatically.

Use cases

QuoLab users looking to further enrich their investigations can now bring QuoLab artifacts into Splunk to leverage Splunk's ecosystem and analytics. See Combining QuoLab with Splunk below for expanded examples.

Find a specific domain

| quolabquery type=domain id=google.com

Find facets associated with multiple cases

| quolabquery type=case facets="display,tagged" limit=30

Find cases where a specific IP address was targeted

| quolabquery query="{'class': 'sysref', 'type': 'encases', 'target': {'id': '1.2.3.4', 'class': 'fact', 'type': 'ip-address'}}"

Upgrade instructions

No special upgrade procedures are necessary.

Reference material

Configuration: QuoLab Server

This add-on creates a new collection of entities called quolab_servers.
At least one server must be defined to use the custom SPL command.

Each server contains the following attributes:

Search command: quolabquery

The quolabquery command supports simple and advanced queries against a QuoLab catalog.
In simple mode, a user can specify just the type of object to query and optionally specify one or more specific ids to search for.
In advanced mode you can specify a query in JSON mode so the full power of the QuoLab query language is at your disposal.

Simple Usage:

| quolabquery [server=<server>] type=<quolab-type> [id=<list>]

Advanced Usage:

| quolabquery [server=<server>] query="<json-query>"

Parameters:

• type=<type>: For simple searches, provide one of the QuoLab catalog types here.
  For example: case, endpoint, or ip-address.
  The quolabquery command will determine the correct class associated with each type.
• id=<value>: For simple searches, this can be used to specify one or more values (ids) to search for.
  To search for multiple ids, simply enclose the id in double quotes and separate them with a comma.
• query=<json-query>: In advanced mode, a custom query can be provided in JSON mode.
  To avoid escaping double quotes, the quolabquery command accepts a JSON-like syntax that uses single quotes as shown in some of the examples later.
  The query can be top-level query (one that explicitly provides it's own query key), or a simpler query where it's assumed that the entire JSON body is the child of the query key. (If none of that made sense to you, start with the simple query.)

Optional parameters:

• server=<quolab-server>: Use this to determine which backend QuoLab server to query.
  If not provided, the default server name is quolab.
• limit=<int>: Restrict the number of query results.
• facets=<facet>: Facets are related data to be fetched and returned along with the primary data.
  To retrieve multiple facets at once, provide a comma separated list in double quotes.
• order=[-+]<field>: Return results based on field ordering.
  The field name should be provided in dot-notation.
  Precede the field name with a + to sort in ascending order and - to sort in descending order.
  To sort by multiple fields, use a comma separated list surrounded by double quotes.

Example searches:

• | quolabquery server=quolab type=wallet
• | quolabquery type=ip-address id="8.8.8.8, 1.2.3.4"
• | quolabquery type=endpoint id=tlsh:tlsh=virtual facets=display
• | quolabquery query="{'query':{'class': 'sysfact', 'type': 'case' },'limit': 15, 'facets': {'display': 1,'tagged': true}}"
• | quolabquery query="[{'class': 'sysfact', 'type': 'endpoint'}, {'class': 'sysfact', 'type': 'connector'}]" limit=100
• | quolabquery query="{'class': 'sysfact', 'type': 'endpoint'}" limit=100 facets="refcount,display"

HINT: If you're trying to learn the query language, you can use the quolabquery command with a simple query, and view the actual JSON query sent to QuoLab at the top of Splunk's Job Inspector.

Sourcetypes

Authorization

Configuration files

This add-on creates a custom configuration file named quolab_servers.conf.
For security reasons, the secret for each server is stored securely in passwords.conf and is encrypted at rest.
Typically there is no reason to modify these files directly.

Combining QuoLab with Splunk

The real power of the quolabquery command is that it can be combined with other Splunk search commands. We'd love to expand this section to showcase real-life use cases. Please reach out with with your success stories. In the meantime, here are some ideas to get you started:

Capturing Tor descriptors to a lookup using 'outputlookup'

Combining the quolabquery command with outputlookup allows you to overwrite or append an existing lookup table within Splunk.

| quolabquery limit=5000 type=known-as facets=refcount | search fact.type="tor-descriptor"
| rename fact.* as * | table id type label refcount.*
| outputlookup quolab_tor_descriptor.csv

Search for firewall events related to QuoLab cases with a subsearch

This technique uses Splunk's subsearch feature to insert specific fields returned by quolabquery command into a dynamic search. In this example, Splunk looks in the firewall index for ip addresses in the src_ip field.

index=firewall [
    | quolabquery query="{'class': 'sysref', 'type': 'encases', 'target': {'class': 'fact', 'type': 'ip-address'}}" facets="display"
    | return 1000 src_ip=target.display.label ]
| table _time, sourcetype, src_ip, src_port, dest_ip, dest_port, action

The final search Splunk executes will look like:

index=firewall (src_ip="1.2.3.4") OR (src_ip="99.99.99.99") OR ...
| table _time, sourcetype, src_ip, src_port, dest_ip, dest_port, action

Source & Licensing

This is an open source project. See LICENSE for full details.
Full source code for TA-quolab is available on GitHub.
Please check it out and send us your ideas about how to improve it. Pull requests are greatly appreciated!

Support

Community support is available on a best-effort basis. For information about commercial support, contact Kintyre.
Issues are tracked via GitHub issues.

History

See the full change log.