Add action for snapshot query results (#2061)

docs/wiki/deployment/logging.md

@@ -15,7 +15,7 @@ lrwxr-xr-x   1 root  wheel    77 Sep 30 17:37 osqueryd.INFO -> osqueryd.INFO.201
 -rw-------   1 root  wheel   388 Sep 30 17:37 osqueryd.results.log
 ```
 
-### Logger Plugins
+## Logger Plugins
 
 osquery includes logger plugins that support configurable logging to a variety of interfaces. The built in logger plugins are **filesystem** (default), **tls** and **syslog**. Multiple logger plugins may be used simultaneously, effectively copying logs to each interface. To enable multiple loggers set the `--logger_plugin` option to a comma separated list of the requested plugins.
 
@@ -29,6 +29,8 @@ As the above directory listing reveals, *osqueryd.INFO* is a symlink to the most
 
 ### Results logs
 
+#### Differential logs
+
 The results of your scheduled queries are logged to the "results log". These are differential changes between the last (most recent) query execution and the current execution. Each log line is a JSON string that indicates what data has been added/removed by which query. There are two format options, *single*, or event, and *batched*. Some queries do not make sense to log "removed" events like:
 
 ```sql
@@ -51,7 +53,7 @@ By adding an outer join of `time` and using `time.minutes` as a counter this que
 }
 ```
 
-### Snapshot logs
+#### Snapshot logs
 
 Snapshot logs are an alternate form of query result logging. A snapshot is an 'exact point in time' set of results, no differentials. If you always want a list of mounts, not the added and removed mounts, use a snapshot. In the mounts case, where differential results are seldom emitted (assuming hosts do not often mount and unmount), a complete snapshot will log after every query execution. This *will* be a lot of data amortized across your fleet.
 
@@ -111,6 +113,43 @@ Example output of `SELECT name, path, pid FROM processes;` (whitespace added for
 
 This tells us that a binary called "osqueryd" was stopped and a new binary with the same name was started (note the different pids). The data is generated by keeping a cache of previous query results and only logging when the cache changes. If no new processes are started or stopped, the query won't log any results.
 
+### Snapshot format
+
+Snapshot queries attempt to mimic the differential event format, instead of emitting "columns", the snapshot data is stored using "snapshot". An action is included as, you guessed it, "snapshot"!
+
+Consider the following example:
+```json
+{
+  "action": "snapshot",
+  "snapshot": [
+    {
+      "parent": "0",
+      "path": "/sbin/launchd",
+      "pid": "1"
+    },
+    {
+      "parent": "1",
+      "path": "/usr/sbin/syslogd",
+      "pid": "51"
+    },
+    {
+      "parent": "1",
+      "path": "/usr/libexec/UserEventAgent",
+      "pid": "52"
+    },
+    {
+      "parent": "1",
+      "path": "/usr/libexec/kextd",
+      "pid": "54"
+    },
+  ],
+  "name": "process_snapshot",
+  "hostIdentifier": "hostname.local",
+  "calendarTime": "Mon May  2 22:27:32 2016 UTC",
+  "unixTime": "1462228052"
+},
+```
+
 ### Batch format
 
 If a query identifies multiple state changes, the batched format will include all results in a single log line. If you're programmatically parsing lines and loading them into a backend datastore, this is probably the best solution.

osquery/config/parsers/tests/decorators_tests.cpp

@@ -89,9 +89,9 @@ TEST_F(DecoratorsConfigParserPluginTests, test_decorators_run_interval) {
   std::string log_line;
   serializeQueryLogItemJSON(item, log_line);
   std::string expected =
-      "{\"snapshot\":\"\",\"decorations\":{\"internal_60_test\":\"test\","
-      "\"one\":\"1\"},\"name\":\"\",\"hostIdentifier\":\"\",\"calendarTime\":"
-      "\"\",\"unixTime\":\"0\"}\n";
+      "{\"snapshot\":\"\",\"action\":\"snapshot\",\"decorations\":{\"internal_"
+      "60_test\":\"test\",\"one\":\"1\"},\"name\":\"\",\"hostIdentifier\":\"\","
+      "\"calendarTime\":\"\",\"unixTime\":\"0\"}\n";
   EXPECT_EQ(log_line, expected);
 
   // Now clear and run again.

osquery/database/database.cpp

@@ -268,6 +268,7 @@ Status serializeQueryLogItem(const QueryLogItem& i, pt::ptree& tree) {
       return status;
     }
     tree.add_child("snapshot", results_tree);
+    tree.put<std::string>("action", "snapshot");
   }
 
   // Check if the config has added decorations.

osquery/logger/plugins/tests/filesystem_logger_tests.cpp

@@ -89,8 +89,10 @@ TEST_F(FilesystemLoggerTests, test_log_snapshot) {
   EXPECT_TRUE(readFile(snapshot_path.string(), content));
 
   std::string expected =
-      "{\"snapshot\":\"\",\"name\":\"test\",\"hostIdentifier\":\"test\","
+      "{\"snapshot\":\"\",\"action\":\"snapshot\",\"name\":\"test\","
+      "\"hostIdentifier\":\"test\","
       "\"calendarTime\":\"test\",\"unixTime\":\"0\"}\n{\"snapshot\":\"\","
+      "\"action\":\"snapshot\","
       "\"name\":\"test\",\"hostIdentifier\":\"test\",\"calendarTime\":\"test\","
       "\"unixTime\":\"0\"}\n";
   EXPECT_EQ(content, expected);