Links

Querying Reference

The runreveal logs command is the method to retrieve the logs that you've collected using a SQL interface. Under the hood, RunReveal's storage layer is Clickhouse and a full reference of the syntax is available within the Clickhouse Docs

Getting Started

Running a query

The logs command takes a single string argument, which is the query that you'd like to run.
$ runreveal logs "SELECT sourceType, COUNT(*) FROM runreveal_logs GROUP BY sourceType ORDER BY sourceType;"
+------------+---------+
| SOURCETYPE | COUNT() |
+------------+---------+
| cloudtrail | 313188 |
| webhook | 24 |
+------------+---------+
Retreived 2 rows in 449.640708ms
The logs command can also run a named query by using the --name flag.
$ runreveal logs --name source-count
+------------+---------+
| SOURCETYPE | COUNT() |
+------------+---------+
| cloudtrail | 313188 |
| webhook | 24 |
+------------+---------+
Retreived 2 rows in 449.640708ms

Data Organization

All of the data you store with runreveal is stored in a single table, runreveal_logs. Additionally, each log source that you
$ runreveal logs
rr> show tables
+-----------------+
| NAME |
+-----------------+
| cloudtrail_logs |
| runreveal_logs |
+-----------------+
Retreived 2 rows in 266.233667ms
Similar to the SQL interfaces you're likely used to, you can use the basic commands you're used to in order to figure out what types of data is available to you.
$ runreveal logs "describe runreveal_logs"
+-------------------+---------------------+--------------+--------------------+----------------------------------------------------------------------------------------------+------------------+----------------+
| NAME | TYPE | DEFAULT_TYPE | DEFAULT_EXPRESSION | COMMENT | CODEC_EXPRESSION | TTL_EXPRESSION |
+-------------------+---------------------+--------------+--------------------+----------------------------------------------------------------------------------------------+------------------+----------------+
| id | String | | | The RunReveal-generated ID of the individual event | | |
| receivedAt | DateTime | | | The time at which RunReveal received the event | | |
| workspaceID | String | | | Customer workspaceID this belongs to | | |
| sourceType | String | | | The source type which sent the event | | |
| sourceID | String | | | The instance of the source | | |
| eventID | String | | | The ID generated by the source for the event | | |
| eventName | String | | | The event name generated by the source for the event | | |
| eventTime | DateTime | | | The time at which the event occurred | | |
| readOnly | Bool | | | Indicates whether or not this was a state altering action | | |
| srcIP | String | | | The apparent, public IP of the actor performing the action/event | | |
| srcASOrganization | Nullable(String) | | | AS Organization Name that IP belongs to | | |
| srcASNumber | Nullable(UInt32) | | | AS Number that IP belongs to | | |
| srcASCountryCode | Nullable(String) | | | AS Country Code that IP belongs to | | |
| dstIP | String | | | The (preferably public) IP belonging to the service upon which the action is being performed | | |
| dstASOrganization | Nullable(String) | | | AS Organization Name that IP belongs to | | |
| dstASNumber | Nullable(UInt32) | | | AS Number that IP belongs to | | |
| dstASCountryCode | Nullable(String) | | | AS Country Code that IP belongs to | | |
| actor | Map(String, String) | | | details about the actor for which the event belongs | | |
| tags | Map(String, String) | | | | | |
| rawLog | String | | | | | |
+-------------------+---------------------+--------------+--------------------+----------------------------------------------------------------------------------------------+------------------+----------------+
Retreived 20 rows in 345.061292ms

Natural Language Queries

You can query your logs using natural language, and use GPT-4 to convert your query to a SQL query.
rr> show me eventTime and eventName most recent log; \a
+----------------------+------------------------+
| eventTime | eventName |
+----------------------+------------------------+
| 2023-07-08T19:03:38Z | DescribeInstanceStatus |
+----------------------+------------------------+
Ran Query: SELECT eventTime, eventName FROM runreveal_logs ORDER BY receivedAt DESC LIMIT 1;
Retrieved 1 rows in 1.176173667s

Vertical Queries

The RunReveal CLI supports the \G terminator to a query after a semicolon, which will print the results of your query.
:) runreveal logs
rr> SELECT sourceType, COUNT(*) as count FROM runreveal_logs GROUP BY sourceType ORDER BY sourceType; \G
Row 0
sourceType | cloudtrail
count | 313381
Row 1
sourceType | webhook
count | 24
Retreived 2 rows in 461.255333ms